本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 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，然後位置引數訊息，最後是從管線進來的 stdin。

# 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

stdin 不是 TTY 時，其內容會附加到組合後的提示；若沒有提供其他內容，它就是整份提示。stdin 讀取器會等 300 毫秒的安靜區間，才放棄仍開著的管線，因此請盡快寫完提示並關閉 stdin。大量或慢慢產生的提示請用 --prompt-file。--prompt-file - 會明確從 stdin 讀取提示（stdin 是 TTY 時為用法錯誤）；該次叫用不會再把隱含的管線 stdin 附加第二次。

-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 工具的指令，因為它走同一個殼層啟動器；碰到拒絕規則的呼叫會以工具錯誤失敗，並計入被阻擋執行狀態的一次拒絕。未知 id 不是錯誤，因為 MCP 工具 id 是動態的；但在預設格式下，每個不在內建工具集裡的 id 會在 stderr 印出一行警告（可用 --quiet 抑制）。

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

`--add-dir PATH`

授予代理程式一個額外目錄的存取權（可重複）：會在新工作階段的權限規則中加入一條 external_directory 允許規則，對象是 <resolved-path>/*，涵蓋該目錄及其下的一切。

每條路徑必須存在，而且必須是目錄（像 --file 一樣，依呼叫者的 cwd 解析）。規則在建立工作階段時套用，因此在 --session 與 --continue 之下不會生效。CLI 會在 stderr 印出 --add-dir applies only to new sessions 並繼續。它不會改變 --file 的範圍限制：附件仍必須位於專案目錄內。它涵蓋檔案工具（read、glob、grep、list、edit、write）。殼層指令若透過動態路徑進入該目錄，仍會觸發僅限互動的路徑存取提示，而無介面執行會自動拒絕，因此請優先使用檔案工具，或明確傳入檔案內容。

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 印到 stderr。

輸出格式

--format 接受 default（預設）、json、jsonl 或 ndjson（jsonl 與 ndjson 是 json 的別名）。

預設（文字）

預設格式只把最終的助理文字印到 stdout。所有進度、工具活動與診斷都到 stderr，一開始是包含工作階段 id 的 > Agent · model · ses_... 標頭，因此多回合的呼叫者可以用 --session 續接，而不必改用 --format json（--quiet 會抑制標頭）。stderr 不是 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）：stdout、--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，或呼叫者的 cwd）以 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 文件寫到 stdout；失敗時 stdout 保持空白，一份 {"error":{"code","message"}} 文件寫到 stderr，結束代碼為 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 送到 stdout。

從另一個代理程式呼叫 ax-code

用指令稿、CI 步驟或其他代理程式包裝 ax-code run 時：

使用 --format json，並讀取最後一行。即使串流提早結束，result 紀錄也始終是最終行。
從該結果行取得 sessionID，供任何後續回合使用；再用 --session 傳回去。
並行的呼叫者絕不要使用 --continue。它會續接最近的工作階段，多個呼叫者同時活動時會互相競爭；請改傳明確的 --session id。
傳入明確的 --model，讓執行不依賴會變動的已設定預設。
始終傳入 --timeout，讓卡住的代理程式不能佔住呼叫者。
關閉 stdin，或使用 --prompt-file 與 --prompt-file -：隱含的管線讀取器在 300 毫秒的安靜區間之後就會放棄，並悄悄截斷慢速管線。
設定 NO_COLOR=1，或依賴非 TTY 的偵測，讓管線執行絕不會送出 ANSI 跳脫碼。
從專案目錄執行：家目錄，或多個儲存庫的父目錄，在非互動模式會被拒絕。設定 AX_CODE_ALLOW_BROAD_DIR=1 可覆寫該防護。
用法失敗不會在 stdout 印出任何東西（說明與單行錯誤送到 stderr），因此打錯的指令會讓 stdout 空白，並以 1 結束。在 --format json 之下，用法失敗也會在 stdout 寫成一行 error。
處理程序仍在載入、run 指令尚未作用時抵達的信號，會以結束代碼 130 結束處理程序，而且沒有輸出；指令作用之後，SIGINT 與 SIGTERM 始終產生單一的結尾 result 行，狀態為 cancelled。

無介面 CLI（ax-code run）