本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

自主模式

狀態：現行 範圍：現行狀態 上次審閱：2026-08-25 負責人：ax-code 執行環境

自主模式讓 ax-code 完成工作時，不必在每個低風險步驟等待人工確認。啟用之後，權限提示會自動核准，除非被明確阻擋；提問對話框會以最佳做法的啟發式判斷自動回答，偏好建議的、預設的、常見的、簡單的與最小的選擇，並避開有風險或過度設計的選項。

自主模式預設是開啟。若你先前把它關掉，該偏好會被儲存，並在下次啟動時恢復。

快速開始

從 TUI 切換：

• 在提示中輸入 /autonomous，或
• 按 Ctrl+P 並搜尋「autonomous」，或
• 點選狀態列上的 自主開啟／關閉 指示

狀態列會顯示目前狀態：

• 自主開啟（黃底、粗體紅字）：代理程式執行時不會暫停
• 自主關閉（綠色文字）：代理程式會在權限與提問提示時暫停

這項設定會跨工作階段保存在 ax-code.json。

會改變什麼

它如何運作

自主模式在三個層運作：

事實來源

這一頁摘要的是使用者看得到的行為。行為改變時，請對照下列來源驗證文件：

• 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() 時，權限模組會分類該權限：

• SAFE 權限（read、glob、grep、list、lsp、code_intelligence、skill、todoread）會自動核准，而不建立阻擋用的提示。
• RISK 權限（edit、bash、external_directory、task、webfetch、websearch、codesearch 等）落到規則集：代理程式已設定的允許與拒絕規則仍然適用，使用者定義的拒絕規則一律強制執行。在 full-access 沙箱模式中，拒絕規則評估之後，RISK 權限會自動核准。
• Unknown 權限預設會詢問（experimental.autonomous_strict_permission: false 保留舊的允許行為）。

一律走到逐次決定、而不是立即依規則核准的權限： isolation_escalation（沙箱覆寫請求）、INTERACTIVE_ONLY 權限，以及 NEVER_AUTONOMOUS_AUTOAPPROVE 集合。一項收窄（ADR-098）：在 full-access 沙箱模式中，標成僅限互動的 external_directory 請求也會自動核准。那些是路徑無法靜態驗證的 bash 指令，因為它們使用 glob、變數或大括號展開；完整存取的沙箱已經沒有檔案系統邊界需要守住。明確的拒絕規則仍然適用，而沙箱開啟的模式（workspace-write、read-only）仍保留逐次提示。

閒置的「允許一次」（預設開啟）： 自動開啟加上沙箱關閉（full-access）表示互動最少：每一個待處理權限都可以在 15 秒之後自動回覆一次，包含 requireInteractive、鉤子與沙箱升級提示。自動關閉或沙箱開啟時，待處理提示需要人工回答。WebMCP 另外要求對應的橋接已經連線；另一個已連線的橋接不算。明確的拒絕規則仍然適用。experimental.permission_idle_once.enabled: false 會停用倒數，permissions 可以限制它們的範圍。舊的 timeout_ms 設定為了相容而接受，但不再改變固定的 15 秒時間。

倒數由伺服器持有。每個工作階段最舊的請求會收到期限；排在佇列裡的請求走到最前面時，會重新得到 15 秒。人工回覆會取消計時器。關掉自動、打開沙箱，或中斷相關的 WebMCP 橋接，會取消待處理的倒數。恢復資格會開始新的倒數。暫時的設定重新載入空檔會暫停倒數。自動回覆會再檢查目前模式、橋接與拒絕規則，而且絕不會儲存持久核准。AX_CODE_PERMISSION_IDLE_ONCE_MS 這個內部的除錯與測試覆寫仍然可用，上限是 Node 計時器的最大值。

模式的範圍是作用中的目錄。巢狀的 ax-code.json 可以覆寫儲存庫根目錄的設定；請用作用中工作階段的沙箱切換，改變它的有效模式。

不可覆寫的受保護路徑： 自主模式也拒絕寫入一組固定的原則與控制平面路徑，也就是 ax-code.json／ax-code.jsonc、.ax-code/**、.git/config 與 .git/refs/**，因此代理程式不能編輯自己的設定、提高自己的自主上限，或植入 git 鉤子。和可設定的封鎖路徑清單不同，這些不能被專案或使用者設定移除。

2. 提問自動回答（伺服器端）

工具向使用者提問時，提問模組會立刻選一個答案。它偏好標成建議、預設、安全、標準、常見、慣例、最佳做法、簡單或最小的選項。它避開標成實驗性、有風險、危險、破壞性、進階、複雜、重寫或過度設計的選項。若沒有選項帶有訊號，它會選第一個，因為提問工具指示代理程式把建議選項放在最前面。

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 調高或調低。

模型回合是一次外層迴圈的模型請求。工具呼叫是模型回合內的一次工具叫用。這是分開的預算：單一模型回合可以發出數個工具呼叫。包含 steps 的舊設定名稱仍然支援，但它們不會讓這兩個單位可以互換。

請優先使用一等的 autonomy 物件。舊的 session.* 與 experimental.autonomous_caps.* 鍵仍可當別名（優先順序較低）。

二進位檔（執行檔的 cp、zip 的 curl -o，以及其他非文字寫入）仍計入檔案上限，但計入零行。行數上限量的是文字變更。殼層的文字寫入保留 ceil(size / 80) 估計，因此換行很少的密集承載不能規避預算。

git check-ignore 回報為已忽略的未追蹤路徑，也計入零行，但仍算一個檔案。這涵蓋產生出來的樹，例如驗證器把輸出導向那裡時的 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 會跨自動延續保留。當作用中的目標或 Super-Long 模式提高一般的延續上限時，cont 會顯示 ∞。

自動路由： 關鍵字路由可能把工作階段切到專責代理程式（Debug、Security、DevOps 等）。除非你設定 agent.<name>.steps，專責代理程式與 Dev 共用相同的、預設無上限之代理程式模型回合原則。若只要 Dev 代理程式，請用 "routing": { "disable": true } 停用路由。

長時間執行： 數小時的工作請用 /goal 或 Super-Long。它們會提高一般的延續上限，並使用較大的累計上限（預設 20,000）。驗證與暫停的語意見 迴圈模式。/goal 會先寫出可供審閱的契約（驗收條件加上驗證計畫）；若無法產生該計畫，就失敗即關閉並進入暫停。

上限讓執行停止時

一般執行到達累計模型回合上限之前，AX Code 會注入一次有上限的收斂指示（最多最後 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 不會停用權限、隔離、影響範圍、停滯、token、時間，或累計模型回合的防護。

範例：為大型自主批次提高預算

{
  "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 預設印出精簡的工具輸出：指令輸出縮成尾端，編輯顯示差異摘要，待辦寫入顯示一行進度計數。錯誤絕不會被藏起來，它們以與其他輸出相同的尾端上限呈現。加上 --full 可恢復完整的工具輸出（完整差異、未截斷的指令輸出、完整待辦清單），供稽核使用。

安全保證

即使自主模式開啟：

1. 沙箱仍然強制邊界：工作區以外的寫入會被阻擋，與自主模式無關
2. 隔離提升一律詢問：代理程式不能悄悄覆寫沙箱限制
3. 拒絕規則會被強制執行：明確的 "deny" 權限規則仍會阻擋工具呼叫
4. 自主選擇會被記錄：提問工具的中繼資料包含結構化的 autonomousDecisions 帳本，工具輸出也包含選取的答案，讓代理程式之後可以報告
5. 避免過度設計：自主延續會提醒代理程式偏好最簡單的常見作法，並避免沒有三個以上具體使用情境的抽象
6. 工作階段快照會被記錄：每一次工具呼叫都會記入日誌，供稽核與重播
7. 中止一律有效：按 Esc（中斷）會立刻停止代理程式