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

自主模式

状态：生效 范围：当前状态 最近审阅：2026-08-25 负责人：ax-code 运行时

自主模式让 ax-code 在每个低风险步骤上无需等待人工确认即可完成任务。启用后，权限提示会自动批准，除非被明确阻止；问题对话框会按最佳实践启发式自动作答，优先选择推荐、默认、常见、简单和最小化的选项，同时避开有风险或过度设计的选项。

默认情况下，自主模式为开启。若你此前将其关闭，该偏好会被保存，并在下次启动时恢复。

快速开始

在 TUI 中切换：

• 在提示中输入 /autonomous，或
• 按下 Ctrl+P 并搜索 “autonomous”，或
• 点击状态栏中的 autonomous on/off 指示器

状态栏显示当前状态：

• autonomous on（黄色背景，红色粗体文字）——智能体不暂停直接运行
• autonomous off（绿色文字）——智能体在权限或问题提示处暂停

该设置会跨会话保存在 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() 请求权限时，Permission 模块会对权限进行分类：

• 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 沙箱模式下，标记为 interactive-only 的 external_directory 请求——因使用 glob、变量或花括号展开而无法静态验证路径的 bash 命令——也会自动批准，因为完全访问的沙箱已没有需要守卫的文件系统边界。显式拒绝规则仍然适用，而沙箱开启模式（workspace-write、read-only）保留逐次调用提示。

空闲时的“允许一次”（默认开启）： 自动开启且沙箱关闭（full-access）意味着最少交互：每一项待处理权限都可以在 15 秒后自动回复一次，包括 requireInteractive、hook 与沙箱升级提示。自动关闭或沙箱开启时，待处理提示需要人工回答。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 hooks。与可配置的阻止路径列表不同，这些路径不能通过项目或用户配置移除。

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 中提高或降低它们。

一次模型回合是外层循环中的一次模型请求。一次工具调用是模型回合内部的一次工具执行。这是两套独立预算：单次模型回合可以发出多次工具调用。包含 steps 的旧配置名仍然受支持，但它们不会使这两种单位可以互换。

优先使用一等的 autonomy 对象。旧的 session.* 与 experimental.autonomous_caps.* 键仍可作为别名使用（优先级更低）。

二进制文件（可执行文件的 cp、zip 的 curl -o，以及其他非文本写入）仍计入文件上限，但计为零行。行数上限衡量的是文本变更。Shell 文本写入保留 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. 避免过度设计——自主延续会提醒智能体优先采用最简单的常见做法变更，并避免没有 3 个以上具体用例的抽象
6. 会话快照会被记录——每次工具调用都会记入日志以供审计或回放
7. 中止始终有效——按下 Esc（中断）会立即停止智能体