このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 7.24.4 · SDK 2.6.7。英語版

ヘッドレス CLI (`ax-code run`)

状態: 有効範囲: 現行状態最終確認: 2026-09-22 担当: AX Code ランタイムメンテナー

ax-code run は、AI コーディングエージェントとスクリプト向けの、単発で非対話の入口です。プロンプトを 1 つ送り、アシスタントの最終応答を表示して終了します。端末 UI も、対話の確認もありません。この案内では、オプションの面、出力の契約、終了コード、スクリプトと CI に貼り付けて使えるレシピを扱います。

実行を呼び出す

プロンプトの渡し方は 4 つあります。次の順で合成されます。--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 ms の静かな区間を待ちます。プロンプトは速やかに書き、標準入力を閉じてください。大きいプロンプトや、ゆっくり生成されるプロンプトには --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 に分類されます。

実行を導く

3 つのフラグが、プロンプトの文言を変えずに実行を導きます。すべて長い形式のみで、ケバブケースです。

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

エージェントと環境のシステムプロンプトのあと、システムプロンプトへ追加のテキストを足します。追記であり、組み込みのシステムプロンプトを置き換えることはありません。2 つの形式は同時には使えません。ファイル版は、長い指示に便利です。末尾の改行はちょうど 1 つ削られます。空のテキスト（または読めないファイル）は、何も送信される前の使用法エラーです。

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 へ警告を 1 つ出します（--quiet で抑制されます）。

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

`--add-dir PATH`

エージェントへ、追加のディレクトリを 1 つ許可します（繰り返し可）。新しいセッションの権限ルールへ、external_directory の許可ルールが <resolved-path>/* 向けに追加され、そのディレクトリとその下のすべてを覆います。各パスは存在し、ディレクトリでなければなりません（--file と同じく、呼び出し元の作業ディレクトリを基準に解決されます）。ルールはセッション作成時に適用されるため、--session または --continue の下では効きません。CLI は stderr に --add-dir applies only to new sessions を出して続行します。--file の封じ込めは変えません。添付は、引き続きプロジェクトディレクトリの中になければなりません。対象はファイルツール（読み取り、glob、grep、一覧、編集、書き込み）です。動的なパスを通じてそのディレクトリへ入るシェルコマンドは、対話専用のパスアクセス確認を依然として引き起こします。ヘッドレス実行はそれを自動で拒否するため、ファイルツールを使うか、ファイル内容を明示的に渡してください。

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

モデルを選ぶ

使える ID は ax-code models で一覧します。得られた provider/model の値を --model（-m）へ渡します。

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

ax-code models --json は、次の形の文書を 1 つ出力します。 {"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）イベントストリームを出します。1 行につき JSON オブジェクトが 1 つで、単一の JSON 文書ではありません。イベントには step_start、text、tool_use、reasoning（--thinking があるときだけ）、permission_denied、error、step_finish が含まれます。ストリームは、必ずちょうど 1 行の 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 が運ぶのはトークン数だけです。input、output、reasoning、cacheRead、cacheWrite であり、数が不明なときは項目ごと省かれます。費用のフィールドはありません。送信前に実行が失敗したとき（不正なフラグ、未知のモデルなど）、ストリーム形式は終了前に 1 行を出します。

{ "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	ブロックされました。権限の拒否が少なくとも 1 件あり、成功した変更系のツール呼び出しがありません（`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）として報告され、終了コードは

です。スキーマファイルは、モデルが動く前に事前確認されます。読めない、解析できない、またはオブジェクトでないスキーマは、何も送信される前の使用法エラーです。成功時には、解析済みのスキーマが、実行の json_schema 出力形式としてモデルにも送られます。サーバは無効な応答を最大 2 回再試行し、そのあと CLI 自身の最終検証が最後の砦として走ります。最終出力は、直列化された構造化オブジェクト（JSON の 1 行）です。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、または呼び出し元の作業ディレクトリ）の管理ランタイムへ接続します。そのランタイムは 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 フラグを持つほかの読み取り専用コマンドは、より厳しい契約に従います。成功時は stdout へ JSON 文書をちょうど 1 つ書き、失敗時は 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 フラグは一貫性のために受け付けますが、状態の操作は常に stdout へ JSON を出します。

別のエージェントから ax-code を呼ぶ

スクリプト、CI のステップ、または別のエージェントから ax-code run を包むとき:

--format json を使い、最後の行を読んでください。ストリームが早く終わっても、result の記録は常に最終行です。
その結果行から sessionID を取り、続きのターンに使います。--session で戻してください。
並行する呼び出し元から --continue を使わないでください。直近のセッションを再開するため、複数の呼び出し元が動いていると競合します。明示的な --session の ID を渡してください。
明示的な --model を渡し、変わり得る設定済みの既定に依存しないようにします。
常に --timeout を渡し、止まったエージェントが呼び出し元を開いたままにしないようにします。
標準入力を閉じるか、--prompt-file または --prompt-file - を使ってください。暗黙のパイプ読み取りは、300 ms の静かな区間のあと諦め、遅いパイプを黙って切り詰めます。
NO_COLOR=1 を設定するか、TTY でないことの検出に任せてください。パイプした実行が ANSI のエスケープコードを出すことはありません。
プロジェクトディレクトリから実行してください。ホームディレクトリや、複数リポジトリの親ディレクトリは、非対話モードでは拒まれます。そのガードを上書きするには AX_CODE_ALLOW_BROAD_DIR=1 を設定します。
使用法の失敗は stdout に何も出しません（ヘルプと 1 行のエラーは stderr へ行きます）。打ち間違えたコマンドは、終了コード 1 で stdout が空のままです。--format json の下では、使用法の失敗は stdout 上の error の 1 行としても書かれます。
プロセスがまだ読み込み中で、run コマンドが有効になる前に届いたシグナルは、出力なしの終了コード 130 でプロセスを終わらせます。コマンドが有効になったあと、SIGINT と SIGTERM は常に、終端の result 行を状態 cancelled とともに出します。

ヘッドレス CLI (ax-code run)