本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

无头 CLI（`ax-code run`）

状态：生效范围：当前状态最近审阅：2026-09-22 负责人：AX Code 运行时维护者

ax-code run 是面向 AI 编码智能体和脚本的一次性、非交互入口。它提交一条提示，打印助手的最终回复，然后退出——没有终端界面，也没有交互提示。本指南覆盖选项表面、输出契约、退出码，以及用于脚本和 CI 的可复制配方。

调用一次运行

有四种方式提供提示。它们按顺序组合：--prompt-file，然后 -p/--prompt，然后位置消息，然后管道标准输入。

# Positional after -- (safest; flags after -- are never consumed as options)
ax-code run --model qwen -- "Review this change"

# Explicit prompt flag
ax-code run --model qwen --prompt "Review this change"
ax-code run --model qwen -p "Review this change"

# Prompt read from a file (not an attachment)
ax-code run --model qwen --prompt-file ./prompt.txt

# Piped stdin (used as the prompt when no positional/--prompt is given)
printf 'Review this change' | ax-code run --model qwen

当标准输入不是 TTY 时，其内容会追加到组合后的提示，因此在没有其他内容时它就是整个提示。标准输入读取器在放弃打开的管道之前等待 300 毫秒的安静窗口，因此请及时写入提示并关闭标准输入——或对大型或缓慢产生的提示使用 --prompt-file。--prompt-file - 显式从标准输入读取提示（标准输入是 TTY 时为用法错误）；对该次调用，隐式的管道标准输入追加从不会再运行第二次。

-f/--file 把文件附加到消息，并且从不替换提示；它可以重复：

ax-code run --model qwen --file README.md --file src/main.ts -- "Summarize these"

附件必须位于项目目录内：无论权限规则如何，服务器都拒绝目录之外的附件，因此 CLI 会预先以用法错误拒绝它们。把文件复制进项目，或用 --prompt-file 传入其内容。--add-dir 授予工具对额外目录的访问，但不改变此规则。

附件 MIME 类型从扩展名推断：png、jpg、jpeg、gif 和 webp 映射到它们的 image/* 类型，pdf 映射到 application/pdf，因此二进制附件以其真实类型到达服务器，而不是 text/plain。其他任何东西——包括没有可识别扩展名的文件——都作为 text/plain 发送，目录附件被分类为 application/x-directory。

引导这次运行

三个标志在不改变提示文本的情况下引导运行。它们都只有长形式，并且是 kebab-case。

`--append-system-prompt TEXT` / `--append-system-prompt-file PATH`

在智能体和环境系统提示之后，把额外文本追加到系统提示——它追加，并且从不替换内置系统提示。两种形式互斥。文件变体便于较长的说明；恰好修剪一个尾部换行，空文本（或不可读的文件）在提交任何东西之前就是用法错误。

ax-code run --model qwen --append-system-prompt "Answer in English only" -- "Review this change"

`--disallowed-tools a,b`

按 id 为这次运行禁用工具（逗号分隔，可重复）。它通过两种服务器机制应用：创建的会话上的拒绝规则覆盖新运行，按请求的工具映射也覆盖恢复的 --session/--continue 运行。拒绝 bash 也会拒绝 monitor 工具的命令，它通过同一 shell 启动器运行；命中拒绝规则的调用作为工具错误失败，并计入被阻止运行状态的拒绝。未知 id 不是错误——MCP 工具 id 是动态的——但在默认格式下，内置工具集之外的每个 id 会打印一条标准错误警告（由 --quiet 抑制）。

ax-code run --model qwen --disallowed-tools bash,write -- "Audit this module without mutating anything"

`--add-dir PATH`

授予智能体对一个额外目录的访问（可重复）：一条 external_directory 允许规则被加入新会话的权限规则，对象是 <resolved-path>/*，覆盖该目录及其下的一切。每条路径必须存在并且是目录（像 --file 那样相对调用方的当前工作目录解析）。规则在会话创建时应用，因此在 --session/--continue 下它不能生效——CLI 在标准错误上打印 --add-dir applies only to new sessions 并继续。它不改变 --file 的包含规则：附件仍必须位于项目目录内。它覆盖文件工具（read、glob、grep、list、edit、write）；通过动态路径进入该目录的 shell 命令仍会触发仅交互的路径访问提示，无头运行会自动拒绝它，因此请优先使用文件工具或显式传入文件内容。

ax-code run --model qwen --add-dir ../design-docs -- "Read ../design-docs/spec.md and summarize it"

选择模型

用 ax-code models 列出可用 ID。把得到的 provider/model 值传给 --model（-m）：

ax-code models            # one "provider/model" ID per line
ax-code models --json     # one JSON document

ax-code models --json 打印一份形如 {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]} 的文档。

系列名 deepseek、glm 和 qwen 解析到它们的 Flash 默认值，因此 ax-code run --model qwen -- "..." 无需拼出完整的 provider/model ID 即可工作。省略 --model 则使用已配置的默认值；有效的智能体和模型以 > Agent · model 打印到标准错误。

输出格式

--format 接受 default（默认）、json、jsonl 或 ndjson（jsonl 和 ndjson 是 json 的别名）。

默认（文本）

默认格式只在标准输出上打印最终的助手文本。所有进度、工具活动和诊断都到标准错误，以包含会话 id 的 > Agent · model · ses_... 头开始，因此多回合调用方可以用 --session 恢复，而无需切换到 --format json（--quiet 抑制该头）。当标准错误不是 TTY 或设置了 NO_COLOR（任何值）时，ANSI 颜色被禁用，因此管道运行从不会发出转义码。

JSON 流（`--format json`）

--format json 打印换行分隔的 JSON（NDJSON）事件流——每行一个 JSON 对象，而不是单个 JSON 文档。事件包括 step_start、text、tool_use、reasoning（仅在有 --thinking 时）、permission_denied、error 和 step_finish。流始终以恰好一行 result 结束：

{
  "type": "result",
  "timestamp": 1727000000000,
  "sessionID": "ses_...",
  "status": "completed",
  "text": "...",
  "permissionDenials": 0,
  "usage": { "input": 1200, "output": 80, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0 }
}

status 为 completed、blocked 或 error。usage 只携带 token 计数——input、output、reasoning、cacheRead、cacheWrite——计数未知时整个省略；没有成本字段。当运行在提交之前失败（错误标志、未知模型等）时，流格式在退出前打印一行：

{ "type": "error", "error": { "code": "usage", "message": "..." } }

error.code 是以下之一：

代码	何时触发
`usage`	错误或矛盾的标志、缺失的提示，或不可读的 `--output-schema`。
`provider`	未知的提供方 id，或已知但未连接的提供方。
`model`	已知提供方上的未知模型 id，或无法解析的 `--model` 值。
`session`	缺失或被拒绝的 `--session` id（在运行提交之前预检）。
`attach`	无法到达附加的服务器、凭据被拒绝（401/403），或没有为 `--runtime` 运行的受管运行时。
`internal`	任何其他未处理的拒绝。

退出码

代码	含义
0	已完成。
1	用法错误、提供方/模型错误、流错误，或 `--output-schema` 校验失败。
3	被阻止——至少一次权限拒绝，且没有成功的变更类工具调用（`result.status` 为 `blocked`）。
124	超时（`--timeout` 已过去；`result.status` 为 `timeout`）。
130	被 SIGINT 或 SIGTERM 取消（服务器上的会话已中止；`result.status` 为 `cancelled`）。

沙箱

--sandbox read-only|workspace-write|full-access 选择隔离模式（默认 full-access）。在无头运行中，权限询问被自动拒绝并报告为 permission_denied 事件，因此需要它未被允许的写入的运行会报告 blocked 并以 3 退出。这也覆盖子智能体：由 task 工具创建的子会话中提出的询问以同样方式拒绝，它们的 permission_denied 事件携带子项 sessionID。被权限拒绝规则拒绝的工具调用（例如来自 --disallowed-tools）或被只读沙箱拒绝的调用也计为拒绝。交互式的 question 和 plan_exit 工具在无头运行中始终禁用，包括恢复的会话。仅当不期望变更时使用 read-only；workspace-write 把写入保持在项目内。

在 --attach 下，该标志也会作为每次请求的隔离策略放进每个提示正文；服务器应用其自身模式与所请求策略中更严格的一个，因此它只能收紧。对本地拥有的服务器发送相同的按请求策略，使行为保持一致。

结构化输出

-o/--output-file <path> 把最终助手文本写入文件。--output-schema <file> 对照 JSON Schema 文件把最终文本校验为 JSON；不匹配被报告为 error 事件，并带 result.status error，且以 1 退出。模式文件在模型运行之前预检——不可读、无法解析或非对象的模式在提交任何东西之前就是用法错误。成功时，解析后的模式也会作为这次运行的 json_schema 输出格式发送给模型，服务器在 CLI 自己的最终校验作为后盾运行之前，最多重试两次无效回复。最终输出是序列化的结构化对象（一行 JSON）：它是标准输出、--output-file 和 result.text 所携带的内容：

ax-code run --model qwen --output-schema ./answer.schema.json -- "Return a JSON object with a summary field"

会话与恢复

-c/--continue — 继续最近的会话。
-s/--session <id> — 按 ID 继续特定会话。
--fork — 在继续之前分叉会话（需要 --continue 或 --session）。
--show-history — 恢复时打印可见的会话历史（需要 --continue 或 --session）。
--attach <url> — 附加到已经在运行的服务器，而不是启动一个；与 --dir 组合以指向该服务器上的项目目录。用 AX_CODE_SERVER_PASSWORD 保护的服务器接受 --password（或调用方一侧的同一变量）；受管运行时从 AX_CODE_RUNTIME_TOKEN 取得其令牌。
--runtime — 附加到项目目录（--dir 或调用方当前工作目录）的受管运行时，该运行时由 ax-code runtime start 启动，从其私有运行时记录解析 URL 和令牌。没有正在运行的运行时时，运行在任何请求之前失败，错误代码为 attach，消息中指出启动命令。--runtime 和 --attach 互斥。

配方

一次性

ax-code run --model qwen -- "Fix the failing test in src/parser.ts"

用超时限制一次运行

ax-code run --timeout 120 --model qwen -- "Fix the failing test in src/parser.ts"

--timeout <seconds> 在服务器上中止运行，并在运行超出界限时以 124 退出（result.status 为 timeout），因此卡住的智能体不能无限期占用 CI 作业。该界限覆盖整个调用——它在第一次服务器调用之前武装，因此即使是黑洞般的 --attach 主机或挂起的启动也会按时终止（在那种早期情况下，结果行携带空的 sessionID）。

等待后台子智能体

ax-code run --await-background 300 --timeout 360 --model qwen -- \
  "Delegate the independent checks, then integrate their results"

--await-background <seconds> 为本次调用保持打开，以等待其会话创建的后台 task 子项，以及由其结果触发的父后续回合。它是可选加入的，上限为 3600 秒。最终回复和 JSON result.text 来自最后完成的父回合。如果子项或其后续没有在等待界限内安定，运行报告错误并以 1 退出。--timeout 仍然是总体界限。项目计划任务在单独的会话中运行，不属于这次等待。这个一次性命令不认领到期的项目计划；持久后端拥有它们的分发。

解析 JSON 流

result=$(ax-code run --format json --model qwen -- "..." | tail -n 1)
echo "$result" | jq -r '.status'
echo "$result" | jq -r '.text'

result 行始终是最后一行，因此即使流提前结束，tail -n 1 也能把它分离出来。

只读审阅

ax-code run --sandbox read-only --model qwen -- "Review this diff for bugs"

带模式的结构化 JSON 输出

cat > answer.schema.json <<'JSON'
{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}
JSON
ax-code run --model qwen --output-schema answer.schema.json --output-file answer.json \
  -- "Return JSON with a one-sentence summary"

恢复会话

# Start a session and note the sessionID from the result line
ax-code run --format json --model qwen -- "Draft the outline" | tail -n 1

# Continue it
ax-code run --model qwen --session ses_... -- "Now write section 2"

附加文件

ax-code run --model qwen --file docs/spec.md -- "Summarize the attached spec"

机器可读命令

ax-code run --format json 发出换行分隔的事件流（见 JSON 流）；它是唯一流式的 --json 表面。其他每个带 --json 标志的只读命令遵循更严格的契约：成功时它向标准输出写入恰好一个 JSON 文档，失败时标准输出保持为空，同时单个 {"error":{"code","message"}} 文档进入标准错误，退出码为 1。

带 --json 的命令：

ax-code session list --json
ax-code models --json
ax-code providers list --json
ax-code agent list --json
ax-code mcp list --json
ax-code mcp auth list --json
ax-code stats --json
ax-code context --json
ax-code memory status --json
ax-code memory list --json
ax-code task list --json / ax-code task show <taskID> --json
ax-code schedule list --json / ax-code schedule show <taskID> --json
ax-code runtime list --json / ax-code runtime status --json
ax-code doctor --json
ax-code risk <sessionID> --json
ax-code wiki status --json
ax-code workflow list --json / ax-code workflow status <runID> --json

ax-code runtime status 无条件打印其 JSON 文档——--json 标志为一致性而被接受，但状态动作始终在标准输出上发出 JSON。

从另一个智能体调用 ax-code

当从脚本、CI 步骤或另一个智能体包装 ax-code run 时：

使用 --format json 并读取最后一行——即使流提前结束，result 记录也始终是最后一行。
从该结果行捕获 sessionID 以供任何后续回合使用；用 --session 把它传回去。
并发调用方绝不要使用 --continue——它恢复最近的会话，多个调用方活动时会竞态；请改为传入显式的 --session id。
传入显式的 --model，以免运行依赖可变的已配置默认值。
始终传入 --timeout，以免卡住的智能体占用调用方。
关闭标准输入，或使用 --prompt-file / --prompt-file -：隐式管道读取器在 300 毫秒安静窗口后放弃，并会静默截断缓慢的管道。
设置 NO_COLOR=1，或依赖非 TTY 检测，以免管道运行发出 ANSI 转义码。
从项目目录运行：在非交互模式下，主目录或多仓库父目录会被拒绝。设置 AX_CODE_ALLOW_BROAD_DIR=1 以覆盖该守卫。
用法失败在标准输出上不打印任何东西（帮助和一行错误进入标准错误），因此打错的命令使标准输出为空且退出码为 1。在 --format json 下，用法失败也会作为标准输出上的一行 error 写出。
在进程仍在加载、run 命令尚未活动时到达的信号，以退出码 130 且无输出结束进程；一旦命令活动，SIGINT 和 SIGTERM 始终产生单条终局 result 行，状态为 cancelled。

无头 CLI（ax-code run）