Claude Code 权限模式：会话从哪个模式启动，CI 里该怎么写

什么时候用

• 需要确认某个会话或 CI 作业会从哪个权限模式开始，或升级版本后行为变了想找原因。[1]

什么时候不用

• 需要的是 VS Code 扩展、桌面应用或云端会话的起始模式，它们按各自的列表判定，本文不覆盖。[1]

启动模式的判定顺序

• 在终端启动新会话时，Claude Code 取首个适用的来源：（1）--permission-mode 标志或 --dangerously-skip-permissions；（2）设置文件里的 permissions.defaultMode；（3）内置默认。
• 在 .claude/settings.json 或 .claude/settings.local.json 里写 "auto"，该值不生效，并且 Claude Code 会退回内置默认，而不是改用 ~/.claude/settings.json 里的 defaultMode；在这两个文件里写 "bypassPermissions" 同样不生效，会话从 Manual 开始。其他取值在任何设置文件里都生效。
• 多个设置文件同时设置 defaultMode 时，由设置优先级决定，项目或托管的值高于 ~/.claude/settings.json。
• 内置默认取决于运行方式：任何设置文件把 disableAutoMode 设为 "disable" 时是 default；claude -p 或 Agent SDK 是 default；终端或 VS Code 扩展在 v2.1.283 及以上是 auto，更早的版本只在部分套餐且会获取功能开关的会话里是 auto，其余是 default。
• auto 在会话不满足可用条件时（例如设置把它关掉、模型不支持或服务端暂时关闭），会话改以 Manual 启动。

[1]

用小模型演算几种常见设置

下面的函数把上面的顺序写成了代码：flag 优先；否则取设置层里优先级最高的一层（调用者按设置优先级自行排好顺序）；项目或本地层的 auto 退回内置默认，bypassPermissions 退回 default；没有任何设置时取内置默认。内置默认对终端会话写成「built-in default」（官方说明 v2.1.283 及以上是 auto），对 -p 写成 default。后面的 8 条断言就是演算样例。[1]

import assert from "node:assert/strict";

// layers: defaultMode values from settings files, highest precedence first.
// source: "managed" | "user" | "project" | "local". Terminal sessions only.
export function startMode({ flag, layers = [], print = false }) {
  if (flag) return flag;
  const builtIn = print ? "default" : "built-in default"; // -p: Manual since v2.1.302
  const top = layers[0];
  if (top) {
    const shared = top.source === "project" || top.source === "local";
    if (shared && top.value === "auto") return builtIn;
    if (shared && top.value === "bypassPermissions") return "default";
    return top.value;
  }
  return builtIn;
}

const user = { source: "user", value: "acceptEdits" };
assert.equal(startMode({ flag: "plan", layers: [user] }), "plan");
assert.equal(startMode({ layers: [user] }), "acceptEdits");
assert.equal(startMode({ layers: [{ source: "project", value: "auto" }, user] }), "built-in default");
assert.equal(startMode({ layers: [{ source: "local", value: "bypassPermissions" }, user] }), "default");
assert.equal(startMode({ layers: [{ source: "project", value: "dontAsk" }] }), "dontAsk");
assert.equal(startMode({ print: true }), "default");
assert.equal(startMode({}), "built-in default");
assert.equal(startMode({ print: true, layers: [{ source: "project", value: "auto" }] }), "default");
console.log("start-mode model: all assertions passed");

[1]

模型没有覆盖的部分同样重要：disableAutoMode 与 HIPAA 配置、auto 的可用性条件、VS Code 扩展的专属顺序、桌面应用与云端会话、会话恢复时的模式，以及 --settings 与托管设置在设置优先级里的具体位置。官方对 -p 写的是「没有设置权限模式」，模型把 defaultMode 视为已设置；这一点需要在你的版本上核对。官方还写明：v2.1.302 之前，这类非交互运行在没有获取功能开关时（例如使用第三方提供方，或设置了 DISABLE_TELEMETRY）可能以 auto 启动；内置 auto 默认要求 macOS、Linux 和 WSL 上的 v2.1.228 及以上、原生 Windows 上的 v2.1.233 及以上，更早版本的内置默认是 Manual。所以旧版本里同一条命令的启动模式可能不同。[1]

CI 与脚本里要写明什么

官方说明 v2.1.302 及以上，没有指定模式的 claude -p 以 Manual 启动，需要批准的调用会被直接拒绝，除非有 allow 规则、hook、canUseTool 回调或 --permission-prompt-tool 批准它。因此无人值守的作业最好显式写出模式。官方给出的两种写法是：给 claude -p 传 --permission-mode auto，让分类器模型审核调用；或者用 dontAsk 配合精确的允许列表。dontAsk 会自动拒绝所有本来要询问的调用（官方补充：已安装的 mod 仍可批准其中一部分），官方的 CI 示例如下，它来自官方说明，本文没有执行。[1]

claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

[1]

• 版本：在 CI 镜像里固定 Claude Code 版本，并用文中的版本分界核对默认值是否会随升级改变。
• 模式：在命令行里写出 --permission-mode，不依赖设置文件或内置默认；官方说明云端会话会忽略设置文件里的 dontAsk 与 bypassPermissions。
• 范围：dontAsk 下，无需批准的操作（如工作目录内的读取）和匹配 allow 规则的调用照常运行，其余自动拒绝；bypassPermissions 在官方说明里只用于隔离的容器或虚拟机，且不防提示注入。
• 规则：deny 规则在所有模式下都生效，包括 bypassPermissions；allow 规则在 bypassPermissions 里无效。

[1]

起始模式与预期不符时停止作业，先核对版本，再逐层检查标志、设置文件和内置默认，不要通过放宽到 bypassPermissions 来让作业继续。本文只核验官方说明并演算文档规则，没有启动 Claude Code，没有读取你的设置，也没有调用模型；费用取决于你实际使用的模型与服务，本文不认证任何额度。[1]