在本地为你的应用启动开发与测试服务。它会从你的项目读取配置（例如 pyproject.toml 或 llama_agents.yaml），启动 Python API 服务端，并在开发期可选地代理你的界面。

另见：部署配置参考 与 界面构建与开发集成。

用量

终端窗口

llamactl serve [DEPLOYMENT_FILE] [options]

• DEPLOYMENT_FILE 默认为 .（当前目录）。需要时请给出某个具体部署文件或目录的路径。

选项

• --no-install：跳过安装 Python 与 JS 依赖
• --no-reload：禁用 API 服务端在代码变更时的自动重载
• --no-open-browser：不自动打开浏览器
• --preview：把界面构建为静态文件并直接提供（接近生产形态）
• --port <int>：API 服务端的端口
• --ui-port <int>：开发期界面代理的端口
• --log-level <DEBUG|INFO|WARNING|ERROR|CRITICAL>：API 服务端的日志级别
• --log-format <console|json>：API 服务端的日志格式
• --persistence <memory|local|cloud>：工作流服务端的持久化模式。默认为本地持久化。
• --local-persistence-path <path>：本地持久化使用的 SQLite 数据库路径
• --host <host>：API 服务端监听的主机。默认为 127.0.0.1；要接受远程连接请用 0.0.0.0。

行为

• 准备服务端环境（除非给了 --no-install，否则会安装依赖）
• 开发模式（默认）下代理你的界面开发服务器，并在变更时重载
• 预览模式下把界面构建为静态文件并直接提供，不走代理
• 默认使用本地的工作流持久化；--persistence cloud 会把工作流状态存进 LlamaCloud

凭据注入

如果你的应用使用 LlamaCloud（例如 LlamaParse 或云端持久化），llamactl serve 会自动把凭据注入子进程环境。它先看环境里有没有 LLAMA_CLOUD_API_KEY，没有则回退到当前活动配置档的 API key。凭据也会带上 PUBLIC_、VITE_ 与 NEXT_PUBLIC_ 前缀一并转发，以便前端框架在本地开发时能读到它们。

关于环境变量与基于配置档的认证，详见 llamactl auth。