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

自律モード

状態: 有効 範囲: 現行状態 最終確認: 2026-08-25 担当: ax-code ランタイム

自律モードを使うと、ax-code は低リスクの各ステップで人間の確認を待たずにタスクを完了できます。有効なとき、権限プロンプトは明示的にブロックされない限り自動承認され、質問ダイアログはベストプラクティスのヒューリスティックで自動回答されます。推奨、既定、一般的、単純、最小の選択を好み、リスクのある、または過剰に設計された選択肢を避けます。

既定では、自律モードは オン です。以前にオフへ切り替えたことがある場合、その設定は保存され、次の起動で復元されます。

クイックスタート

TUI から切り替えます。

• プロンプトで /autonomous と入力する、または
• Ctrl+P を押して「autonomous」を検索する、または
• ステータスバーの 自律 オン/オフ 表示をクリックする

ステータスバーは現在の状態を示します。

• 自律オン（黄色の背景、太字の赤文字）— エージェントは一時停止せずに実行します
• 自律オフ（緑文字）— エージェントは権限と質問のプロンプトで一時停止します

設定はセッションをまたいで ax-code.json に残ります。

何が変わるか

仕組み

自律モードは 3 つの層で動きます。

真実の源

このページは、利用者向けの振る舞いを要約します。振る舞いが変わったら、ドキュメントを次と照合してください。

• 権限の自動承認、ループの振る舞い、拒否の扱い、自律の上限については packages/ax-code/src/session/processor.ts。
• 自律ワークフローの指示については packages/ax-code/src/session/system.ts と、packages/ax-code/src/session/prompt/ 配下のプロバイダープロンプトファイル。
• 質問の自動回答ヒューリスティックとエスカレーションについては packages/ax-code/src/question/ と packages/ax-code/test/question/question.test.ts。
• 自律のステップとファイル変更の上限については packages/ax-code/src/session/blast-radius.ts。
• プロンプトと決定台帳の振る舞いについては packages/ax-code/test/session/system.test.ts、packages/ax-code/test/session/prompt.test.ts、および関連するセッションテスト。

ここでの安全保証は、サンドボックスのドキュメントと揃えてください。自律モードは承認の振る舞いを変え、分離の強制は変えません。

1. 権限の自動承認（サーバー側）

自律モードは ハイブリッドな拒否優先ポリシー（ADR-004 / PRD v4.2.0）を使います。ツールが権限のために ctx.ask() を呼ぶとき、Permission モジュールはその権限を分類します。

• SAFE 権限（read、glob、grep、list、lsp、code_intelligence、skill、todoread）は、ブロックするプロンプトを作らず自動承認します。
• RISK 権限（edit、bash、external_directory、task、webfetch、websearch、codesearch など）は ルールセットへ落ちます。エージェントに設定された許可と拒否のルールは依然として適用され、ユーザー定義の拒否ルールは常に強制されます。full-access サンドボックスモードでは、拒否ルールの評価後に RISK 権限が自動承認されます。
• 未知の権限は既定で尋ねます（experimental.autonomous_strict_permission: false は従来の許可振る舞いを保ちます）。

即時のルールに基づく承認ではなく、常に呼び出しごとの決定へ至る権限: isolation_escalation（サンドボックス上書きの要求）、INTERACTIVE_ONLY 権限、NEVER_AUTONOMOUS_AUTOAPPROVE 集合。1 つの狭め（ADR-098）: full-access サンドボックスモードでは、対話のみと印付けられた external_directory 要求、つまり glob、変数、またはブレース展開を使うためにパスを静的に検証できない bash コマンドも自動承認されます。フルアクセスのサンドボックスには守るべきファイルシステム境界が残っていないためです。明示的な拒否ルールは依然として適用され、サンドボックスオンのモード（workspace-write、read-only）は呼び出しごとのプロンプトを保ちます。

アイドルの「一度だけ許可」（既定でオン）: 自動オンにサンドボックスオフ（full-access）は、最小の対話を意味します。保留中のすべての権限は、requireInteractive、フック、サンドボックスエスカレーションのプロンプトを含め、15 秒後に 一度自動返信できます。自動オフまたはサンドボックスオンは、保留プロンプトへの人間の回答を必要とします。WebMCP はさらに、対応するブリッジが接続されていることを必要とします。別の接続されたブリッジでは足りません。明示的な拒否ルールは依然として適用されます。experimental.permission_idle_once.enabled: false はカウントダウンを無効にし、permissions はその範囲を制限できます。従来の timeout_ms 設定は互換のために受け付けられますが、固定の 15 秒を変えなくなりました。

カウントダウンはサーバーが所有します。各セッションの最も古いリクエストが期限を受け取り、待ち行列のリクエストは先頭に達したときに新しい 15 秒を受け取ります。人間の返信はタイマーを取り消します。自動をオフにする、サンドボックスをオンにする、または関連する WebMCP ブリッジを切断すると、保留中のカウントダウンは取り消されます。適格性を戻すと新しいカウントダウンが始まります。一時的な設定再読み込みの隙間はカウントダウンを中断します。自動返信は現在のモード、ブリッジ、拒否ルールを再確認し、永続的な承認を決して保存しません。AX_CODE_PERMISSION_IDLE_ONCE_MS の内部デバッグとテストの上書きは利用可能なままで、Node タイマーの最大に上限されます。

モードはアクティブディレクトリに範囲が限られます。入れ子の ax-code.json はリポジトリルートの設定を上書きできます。有効なモードを変えるには、アクティブセッションの Sandbox 切り替えを使ってください。

上書きできない保護パス: 自律モードは、ポリシーと制御プレーンの固定されたパス集合への書き込みも拒否します。ax-code.json/ax-code.jsonc、.ax-code/**、.git/config、.git/refs/** です。これによりエージェントは自身の設定を編集できず、自身の自律上限を上げられず、git フックを植え付けられません。設定可能なブロックパス一覧とは異なり、これらはプロジェクトやユーザー設定では削除できません。

2. 質問の自動回答（サーバー側）

ツールがユーザーに質問するとき、Question モジュールはすぐに回答を選びます。推奨、既定、安全、標準、一般的、慣習的、ベストプラクティス、単純、最小と印付けられた選択肢を好みます。実験的、リスク、危険、破壊的、高度、複雑、書き換え、過剰設計と印付けられた選択肢を避けます。信号のある選択肢がなければ、質問ツールが推奨選択肢を最初に置くようエージェントへ指示しているため、最初の選択肢を選びます。

3. プロセッサループ（セッションレベル）

権限が何らかの理由で拒否された場合（たとえば明示的な拒否ルール）、プロセッサループは停止しません。セッションを止める代わりに、次のステップへ続きます。

4. PRD/ADR 形式の決定枠

自律モードは、システムプロンプトに軽いワークフローの注意を追加します。実装前に、エージェントは問題、制約、決定、トレードオフ、計画、検証で作業を枠づけるべきです。実質的な複数ファイル、アーキテクチャ、または製品に見える変更では、リポジトリのドキュメント様式に合うとき、リポジトリ文書を作るか更新してよいです。些細な変更では、過剰設計を避けるため、この枠を計画の中で軽く保つべきです。

自律とサンドボックス

自律モードとサンドボックスモードは 独立 です。両方を同時に使えます。

既定のランタイム姿勢は、自律オンにサンドボックスオフです。ネットワークが有効な full-access です。これは摩擦の最も少ない CLI 振る舞いを提供しますが、分離境界はありません。信頼できない、または無人の作業に制限を有効にするには、/sandbox、--sandbox workspace-write、AX_CODE_ISOLATION_MODE、またはプロジェクト設定を使ってください。

設定

設定ファイル

ax-code.json の中:

{
  "autonomous": true
}

無効にするには false に設定します。

{
  "autonomous": false
}

環境変数

AX_CODE_AUTONOMOUS=true ax-code    # force autonomous on
AX_CODE_AUTONOMOUS=false ax-code   # force autonomous off

優先順位

環境変数 > 設定ファイル > 既定（オン）

ワークロード予算（モデルターンとツール呼び出し）

自律モードは無制限の実行を意味しません。いくつかの独立した上限が適用されます。下記の既定は出荷された定数です。ワークロードにより余裕が必要なときは、ax-code.json で上げるか下げてください。

モデルターンは、外側ループのモデルリクエスト 1 回です。ツール呼び出しは、モデルターンの中のツール起動 1 回です。これらは別の予算です。1 つのモデルターンが複数のツール呼び出しを出せます。steps を含む従来の設定名は対応されたままですが、2 つの単位を交換可能にはしません。

第一級の autonomy オブジェクトを優先してください。従来の session.* と experimental.autonomous_caps.* キーは、別名として依然として動きます（優先度はより低いです）。

バイナリファイル（実行ファイルの cp、zip の curl -o、その他の非テキスト書き込み）は依然として ファイル上限に数えられますが、請求する行はゼロです。行上限はテキストの変更を測ります。シェルのテキスト書き込みは ceil(size / 80) 見積もりを保つため、改行が少ない密集ペイロードが予算を逃れられません。

git check-ignore が無視と報告する未追跡パスも、行はゼロを請求し、ファイルとしては 1 つ数えます。検証器が出力をそこへ向けたときの target/ のような生成ツリーを含みます（cargo clippy > target/review/clippy.log）。免除は git が終了コード 0 のときだけ適用されます。リポジトリがない場合、git の失敗、追跡ファイルは、無視パターンに名前が一致する追跡ファイルを含め、通常の行請求を保ちます。

プロファイル

複数のフィールドを一度に種まきするには autonomy.profile を設定します（明示的なフィールドが依然として勝ちます）。

/limits で調べる

セッションで /limits を実行すると、解決された予算スタック、アクティブエージェントの有効な TUI 分母、設定源、doctor の警告（たとえば agent.steps がセッションセグメントより厳しいとき）を表示します。キー名には /limits help を使います。

TUI が表示するもの: 自律実行中、ヘッダーは turn current/max · total current/max · cont current/max を報告します。turn は現在の継続セグメントで、アクティブエージェントの 有効なペース上限 を使います。エージェントに上限があるときは min(agent.steps, session.max_steps)、そうでなければセグメントあたりの上限です。total は自動継続を生き延びます。cont は、アクティブなゴールまたは Super-Long モードが通常の継続上限を持ち上げるとき、∞ を示します。

自動ルーティング: キーワードルーティングは、セッションを専門エージェント（Debug、Security、DevOps など）へ切り替えることがあります。専門エージェントは、agent.<name>.steps を設定しない限り、Dev と同じ既定で無制限のエージェントモデルターンポリシーを共有します。Dev エージェントだけが欲しい場合は、"routing": { "disable": true } でルーティングを無効にしてください。

長い実行: 数時間の作業には /goal または Super-Long を使います。通常の継続上限を持ち上げ、より大きい累積上限（既定 20,000）を使います。検証と一時停止の意味は ループモード に文書化されています。/goal はまずレビュー可能な契約（受け入れ基準と検証計画）を書き、その計画を作れなければフェイルクローズドで一時停止します。

上限が実行を止めるとき

通常の実行が累積モデルターンの上限に達する前に、AX Code は上限付きの収束指示を 1 つ注入します（最大で最後の 50 ターン、小さなカスタム予算では縮小）。モデルに、広い探索を止め、進行中の作業を終えるか安全に留め、対象を絞った検証を実行し、未完了の作業を正直に報告するよう伝えます。予算を追加せず、いずれの上限も迂回しません。

終端の予算に達したとき、session.error は任意の機械可読な code を含み、再生の session.end イベントは同じ値を stopCode として記録します。既存の粗い終了理由は互換のため変わりません。現在の上限コードは次です。

• MODEL_TURN_SEGMENT_LIMIT
• MODEL_TURN_TOTAL_LIMIT
• AGENT_MODEL_TURN_LIMIT
• AGGREGATE_TOOL_CALL_LIMIT
• FILE_CHANGE_LIMIT
• LINE_CHANGE_LIMIT

セグメント上限では、設定された継続予算が残っている間、AX Code は自動継続します。その予算が尽きたら実行は停止し、メッセージは何が起きたかを述べます。continue のような新しいプロンプトを送ると、新しい実行計上を持つ、ユーザーが指示した新しい実行が始まります。止まった実行を遡って延ばしません。目的が完了、ブロック、またはゴールとランタイムの予算境界まで明示的で再開可能であるべきときは、/goal を使ってください。/goal は、権限、分離、爆風半径、停滞、トークン、時間、累積モデルターンの安全装置を無効にしません。

例: 大きな自律バッチのために予算を上げる

{
  "autonomous": true,
  "autonomy": {
    "profile": "long",
    "budget": {
      "model_turns": { "per_segment": 500, "total": 20000 },
      "tool_calls": {
        "per_segment": 1000,
        "rate": { "count": 40, "window_seconds": 10 },
        "per_tool": { "bash": 80, "edit": 150 }
      },
      "changes": { "files_total": 100, "lines_total": 10000 }
    },
    "stall": {
      "tool_only_turns": 50,
      "tool_only_nudge": 20,
      "failed_mutation_attempts": 30,
      "max_consecutive_errors": 3
    }
  },
  "agent": {
    "debug": { "steps": 200 }
  }
}

自律をオフにするとき

• ax-code を学ぶ — 各ステップでエージェントが何をするか見る
• 敏感な操作 — 適用前に各ファイル変更をレビューする
• エージェントの振る舞いをデバッグする — エージェントがなぜある決定をするかを理解する
• 信頼できないコード — 見慣れないリポジトリで作業するとき、ツール呼び出しをレビューする

自律をオンのままにするとき

• 日常のタスク — エージェントを信頼できるリファクタ、バグ修正、移行
• CI/CD パイプライン — タスクがすでにポリシーで制約されているヘッドレス実行
• SDK の利用 — createAgent() を通したプログラム的なエージェント実行
• 大きなタスク — 各権限で止まると数時間かかる複数ファイルの変更

ヘッドレスと CI の利用

ヘッドレスモード（ax-code run、ax-code serve、SDK）では、自律モードが不可欠です。プロンプトを表示する TUI がありません。サーバー側の自動承認により、エージェントは未回答のプロンプトでハングせず完了まで実行します。

# Headless one-shot with autonomous on (default)
ax-code run "Fix all TypeScript errors in src/"

# Explicit override
AX_CODE_AUTONOMOUS=true ax-code run "Migrate API routes"

ax-code run は既定で簡潔なツール出力を表示します。コマンド出力はその末尾に縮小され、編集は差分要約を示し、todo の書き込みは 1 行の進捗数を示します。エラーは決して隠されません。他の出力と同じ末尾上限で描画されます。監査のために完全なツール出力（完全な差分、切り詰められないコマンド出力、完全な todo 一覧）を戻すには、--full を渡します。

安全保証

自律モードがオンでも:

1. サンドボックスは依然として境界を強制します — ワークスペース外への書き込みは、自律モードにかかわらずブロックされます
2. 分離のエスカレーションは常に尋ねます — エージェントはサンドボックス制限を黙って上書きできません
3. 拒否ルールは強制されます — 明示的な "deny" 権限ルールは依然としてツール呼び出しをブロックします
4. 自律の選択は記録されます — 質問ツールのメタデータには構造化された autonomousDecisions 台帳が含まれ、ツール出力には選ばれた回答が含まれるため、エージェントは後でそれらを報告できます
5. 過剰設計を避けます — 自律の継続は、最も単純な一般的実践の変更を好み、具体的な利用が 3 件以上ない抽象を避けるようエージェントに思い出させます
6. セッションスナップショットは記録されます — すべてのツール呼び出しは監査と再生のために記録されます
7. 中止は常に働きます — Esc（割り込み）を押すとエージェントはすぐに止まります