命令行参考

agentengine 是 KsADK 的公开命令行入口。

bash

agentengine [OPTIONS] COMMAND [ARGS]...

全局参数：

参数	含义
`--output pretty/json`	在支持时选择人类可读或 JSON 输出
`--no-color`	关闭彩色终端输出
`--dry-run`	对支持的操作打印计划请求，而不实际执行
`--version`	显示包版本
`-h, --help`	显示帮助

核心命令

bash

agentengine --help
agentengine init --help
agentengine run --help
agentengine web --help
agentengine studio --help

命令分组

分组	公开角色	是否本地优先
`init`	创建或包装项目	是
`config`	管理模型和项目设置	是
`run`	运行终端循环或本地 API server	是
`web`	启动本地浏览器 UI	是
`studio`	启动本地 Agent 构建与调试工作区	是
`a2a`	在配置后暴露 A2A surface	是
`replay`	只读回放 RuntimeEvent 历史	是
`mcp`	构建或管理 MCP 资源	取决于目标
`build`	准备部署制品	取决于目标
`deploy`	部署到配置的云端运行时	否
`launch`	一次性构建并部署	否
`agent`	管理 hosted Agent 资源	否
`dashboard`	打开 hosted dashboard 链接	否
`files`	管理 hosted 工作区文件	否
`version`	管理 hosted Agent 版本	否
`hermes`	管理 Hermes 资源	否
`openclaw`	管理 OpenClaw 资源	否

公开 quickstart 应聚焦本地优先命令。Hosted 命令文档必须说明它们的凭证和基础设施前置条件。

本地开发

`agentengine init`

创建新项目：

bash

agentengine init my-agent -f langgraph
agentengine init my-agent -f adk
agentengine init my-codex-agent -f codex
agentengine init my-agent --from-agent ./existing_agent.py

支持的 framework flag 包括 adk、langchain、langgraph、deepagents、 openclaw、hermes 和 codex。公开示例应优先使用不依赖内部基础设施就能本地运行的框架。

0.8 新增：声明式 Codex 项目

agentengine init --framework codex 只生成 agentengine.yaml、.env、 requirements.txt 和 README，不生成 agent.py。它的 artifact_type 是 ManagedRuntime；本机运行原生 Codex 子进程，云端由服务端选择 Runtime 镜像。详见 Codex Managed Runtime。

导入已有代码后，先检查 agentengine.yaml 再运行。

`agentengine config`

管理项目和模型设置：

bash

agentengine config
agentengine config show
agentengine config set OPENAI_MODEL_NAME=my-model
agentengine config model

`agentengine run`

运行 Agent 项目：

bash

agentengine run .
agentengine run . -i
agentengine run . --port 8080
agentengine run . --model my-model

参数	含义
`--port`	本地 server 端口，默认 `8080`
`--interactive` / `-i`	终端交互模式
`--model`	单次模型覆盖
`--show-thinking`	provider 可用时展示 reasoning 输出
`--no-stream`	关闭流式渲染
`--no-trace`	关闭 tracing

手动测试用交互模式，API 客户端用 server 模式：

bash

agentengine run . -i
agentengine run . --port 8080

`agentengine web`

启动本地调用和调试 UI：

bash

agentengine web .
agentengine web . --port 7860
agentengine web . --model my-model
agentengine web . --no-open

Codex ManagedRuntime 同样使用 agentengine web . --no-open。它会校验当前操作系统对应的本地 Codex 二进制；离线但未显式锁定 Runtime 版本时会给出未锁定提示。

`agentengine studio`

启动只监听 loopback 的本地 Agent 构建工作区：

bash

agentengine studio .
agentengine studio . --port 8081 --no-open
agentengine studio . --env-file ./model.env --codex-proxy auto

Studio 使用单一 React shell 承载 Agent、会话、构建、资源、Trace 与任务编排页面，根路径直接进入工作区；没有需要单独维护的 /chat 前端。模型环境可从当前进程、全局配置或显式 --env-file 解析，浏览器写操作使用本地 session 与 CSRF 双重校验。

studio/static 是随 Python 包分发的 React 生产构建产物。公开仓、sdist 与 wheel 不包含 Studio 的 React / TypeScript 可编辑源码；make build-wheel 和 make public-build-check 会校验并打包经过审计的静态产物。

从启动工作区到创建、构建和测试 Agent 的完整流程见 AgentKit Local Studio。

`ksadk replay` / `agentengine replay`

从一个 session 的新 RuntimeEvent 日志生成可读 transcript 或 JSON，适合排查断线、刷新后的审批状态、A2UI activity 和跨 runner 事件顺序。它不会重新调用模型、工具或审批 action。

bash

ksadk replay session_123
ksadk replay session_123 --after-seq-id 120 --format json
agentengine replay session_123 --before-seq-id 260

只有通过 canonical RuntimeEvent v2 store 持久化的 session 可被这个命令读取；旧式 SessionEvent 不会被静默转换成新的 canonical 事实。 --after-seq-id 是开区间，--before-seq-id 是不含上界，可用二者缩小诊断窗口。

协议和集成

`agentengine a2a`

暴露 A2A 协议 surface 和 Agent Card metadata：

bash

agentengine a2a card --help
agentengine a2a serve --help

`agentengine mcp`

管理 MCP 相关资源和运行时流程：

bash

agentengine mcp --help

构建与 Hosted 操作

这些命令属于 SDK surface，但可能需要金山云凭证或经过批准的 hosted 基础设施。

bash

agentengine build --help
agentengine deploy --help
agentengine launch --help
agentengine agent --help
agentengine dashboard --help
agentengine files --help
agentengine hermes --help
agentengine openclaw --help

解释或审核部署形态命令时，在支持的地方使用 --dry-run。

Codex ManagedRuntime（0.8 新增）

artifact_type: ManagedRuntime 让 agentengine build . 自动生成只含 YAML 与 lock 的本地审计 zip。它不是部署上传物；直接部署会以内联 manifest 请求服务端解析 Runtime catalog：

bash

agentengine build .
agentengine deploy . --target serverless --dry-run
agentengine deploy . --target serverless

ManagedRuntime 不使用 KS3 代码包，因此不能传 --push、--ks3-bucket 或 --ks3-path。强制 --mode code 也会失败，避免把开发机平台二进制打入 Linux 部署路径。需要完全自管镜像时，使用显式 --mode container。

运行时 env 透传

agentengine deploy 和 agentengine launch 支持向 hosted runtime 透传自定义环境变量（0.6.5）：

bash

agentengine deploy . \
  --env OPENAI_API_KEY=sk-test \
  --env LOG_LEVEL=debug \
  --env-file ./runtime.env
agentengine launch . --env KEY=VALUE --env-file ./runtime.env

参数	含义
`--env KEY=VALUE`	额外运行时环境变量，可重复传入；显式 env 进入部署 payload `env_vars`
`--env-file PATH`	额外运行时环境变量文件，支持 `.env` 或 JSON 对象

敏感凭证（包括通过 --env 传入的密钥）会在 --dry-run 输出中脱敏。

env 文件边界

传入的 --env-file 用于显式注入运行时 env。真实的 .env / .env.local 不会进入 Code、Container 或 MCP 构建上下文，构建只保留 .env.example / .env.sample / .env.template 模板文件。详见环境变量参考。

默认可观测性与显式关闭

托管 Agent 的 deploy、launch 和 hermes deploy 默认发送 enable_observability=true。CLI 与控制台使用同一个控制面开关；平台在开启时注入 Langfuse 标准 OTLP 主路和 CloudMonitor OTLP 次路，同一 span 在两端保持相同的 trace_id / span_id。

bash

# 默认开启
agentengine deploy . --target serverless
agentengine launch . --target serverless
agentengine hermes deploy --name my-hermes

# 用户显式关闭
agentengine deploy . --target serverless --no-observability
agentengine launch . --target serverless --no-observability
agentengine hermes deploy --name my-hermes --no-observability

关闭后平台会清理托管 OTLP endpoint、headers 和 protocol；不要用 --env 覆盖平台托管的可观测变量。环境变量协议见环境变量参考。

`agentengine hermes`

Hermes deploy 支持显式运行时环境变量，也会在未指定 --env-file 时自动读取当前目录 .env：

bash

agentengine hermes deploy --name my-hermes \
  --env LOG_LEVEL=debug \
  --env FEATURE_FLAG=on
agentengine hermes deploy --name my-hermes --env-file ./hermes.env

--env 可重复传入，--env-file 支持 dotenv 或 JSON 对象。优先级为 --env > --env-file > 当前进程环境 > 自动发现的 .env。显式环境参数会更新已有 Hermes 的 env_vars；未显式传入模型或环境参数时，镜像更新不会覆盖服务端现有环境配置。

Hermes exec 使用 argv 透传，不经过 shell 解析。支持以下目标形式：

bash

agentengine hermes exec --agent my-hermes -- status
agentengine hermes exec ar-123 -- status
agentengine hermes exec -- sessions list

--agent 用于显式指定名称；位置参数只兼容 ar-* Agent ID。未指定目标时，命令会使用当前项目的默认 Agent，普通 argv token 不会被猜测为 Agent 名称。传入 --session 的业务 session ID 会同时写入 terminal start frame（并保留兼容 header），以便运行时恢复会话。

`agentengine openclaw`

部署预构建的 OpenClaw 镜像到云端运行时，模型配置自动复用 OPENAI_* 环境变量。

bash

agentengine openclaw deploy my-openclaw --region cn-beijing-6
agentengine openclaw deploy my-openclaw --memory-system mem0 \
  --mem0-instance-id inst-xxxx \
  --mem0-region cn-beijing-6
agentengine openclaw list
agentengine openclaw status
agentengine openclaw --help

记忆后端选项（0.6.7）：

参数	含义
`--memory-system {openclaw_default\|mem0}`	记忆后端类型；`openclaw_default` 使用内置默认，`mem0` 切换到 mem0 后端
`--mem0-instance-id ID`	mem0 实例 ID，`--memory-system mem0` 时必填
`--mem0-instance-name NAME`	mem0 实例名称（可选）
`--mem0-region REGION`	mem0 实例区域（可选）

lancedb 不在 CLI 暴露

--memory-system CLI 选项只暴露 openclaw_default 与 mem0。lancedb 后端需要通过 MEMORY_BACKEND_MANIFEST 在运行时侧声明 manifest，不走 CLI 参数；详见环境变量参考。

mem0 参数约束

传入 --memory-system openclaw_default 时不能再带任何 mem0 参数；选择 mem0 时 --mem0-instance-id 必填，--mem0-instance-name 与 --mem0-region 为可选补充信息。

OpenClaw 部署同样支持可重复的 --env KEY=VALUE、--env-file 和当前目录 .env 自动发现，并采用与 Hermes 相同的优先级。通用 deploy / launch 只读取显式传入的 --env / --env-file，不会自动加载项目 .env。

JSON 输出

部分命令支持结构化输出：

bash

agentengine --output json agent status
agentengine --output json build --help

交互命令和浏览器 UI 命令在结构化输出可能误导时可以拒绝 JSON。

公开发布 gate

发布 CLI 文档前，应从 release candidate 重新生成 help 输出，并检查是否包含内部 URL、凭证、私有 registry 名称、kubeconfig 路径和部署假设。

推荐检查项：内部 URL、凭证、私有 registry 名称、kubeconfig 路径和部署假设均不应出现在公开 help 输出中。

推荐检查：

bash

agentengine --help
agentengine init --help
agentengine run --help
agentengine web --help
agentengine config --help

命令行参考

本页导航