权限模式

控制 CodeBuddy 在编辑文件、运行命令、发起网络请求前要不要先停下来询问。模式决定整段会话的节奏：保守模式逐次审批，宽松模式让 CodeBuddy 长时间不打断地推进、最后回报。敏感操作选严格、信任方向时选宽松。

可用模式

CodeBuddy Code 提供以下权限模式。前 4 个是用户可在 CLI 中直接切换或指定的；后几个用于 IDE 集成与子代理场景。

用户可手动切换的模式

模式	不询问就能跑什么	适用场景
default	信任目录内的 Read 工具	默认；适合敏感工作 / 上手期
acceptEdits	信任目录内的 Read + Edit 系列工具	边写边走 git diff 复核
plan	委托给"进入 plan 前"的那个模式（默认 = default）；额外允许写入会话计划文件	落手改动前先摸清代码再决定
bypassPermissions	全部工具，无询问	沙箱容器 / VM / 离线 dev container 才用
delegate	仅协调类工具（如 Agent / TaskCreate / SendMessage / 团队管理），实现类工具被屏蔽	主代理只做拆派、把执行交给子代理

程序化 / 集成模式（不在 Shift+Tab 循环里）

模式	何时出现
fullAccess	IDE 客户端通过协议传入；语义上等价于 bypassPermissions 的全局放行
work	IDE 客户端传入。Read 直接放行（不查信任目录），Edit 一律询问，Bash 仅安全命令直接放行，其他询问
ignore	仅在子代理（subagent / teammate）场景生效，表示"用主会话的模式，不要被子代理自己的 frontmatter 覆盖"；主会话用不到

切换权限模式

模式不是用对话告诉 CodeBuddy 来切的，而是通过下面三个入口设置。

会话中切换：Shift+Tab

CLI 里按 Shift+Tab 在以下 5 个模式之间循环：

default → bypassPermissions → acceptEdits → plan → delegate → default → ...

切换后会话状态栏左下角会显示当前模式：

模式	状态栏文案	颜色
default	不显示	—
bypassPermissions	⏵⏵ bypass permissions on (shift+tab to cycle)	warning（警示）
acceptEdits	⏵⏵ accept edits on (shift+tab to cycle)	info
plan	⏸ plan mode on (shift+tab to cycle)	planMode
plan + 前置	⏸ plan + accept edits (shift+tab to cycle) 等	planMode
delegate	⇢ delegate mode on (shift+tab to cycle)	delegateMode

启动时指定：--permission-mode

codebuddy --permission-mode plan
codebuddy --permission-mode acceptEdits
codebuddy --permission-mode bypassPermissions
codebuddy --permission-mode default

CLI 选项 --permission-mode 只接受这 4 个字面量。其他模式（delegate / work / fullAccess / ignore）不能在命令行传入。

-p（非交互模式）下同样有效：

codebuddy -p --permission-mode acceptEdits "重构 src/utils/foo.ts"

启动时还可以追加：

• -y / --dangerously-skip-permissions：等价于 --permission-mode bypassPermissions，跳过全部权限检查

持久化默认值：defaultMode

写到 ~/.codebuddy/settings.json 或仓库 .codebuddy/settings.json：

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

启动时同时给 --permission-mode 时，CLI 参数优先。优先级顺序为：会话当前值 → permissions.defaultMode → default。

计划进入前的"前置模式"自动记忆

进入 plan 时，CodeBuddy 会记住当前模式，离开 plan 时还原。这意味着：

• 你在 acceptEdits 下按 Shift+Tab 进 plan，plan 期间 Read/Edit/Bash 的审批策略仍然按 acceptEdits 的规则做（计划文件除外，永不询问）
• 离开 plan 时回到 acceptEdits，不会被强行掉到 default

各模式语义详解

default（默认）

逐次审批模式，是初学者和处理敏感工作时的安全选项。

工具类型	决定
Read	路径在信任目录内（cwd + permissions.additionalDirectories + 用户加的 addDir）→ 放行；否则询问
Edit	一律询问
Bash	一律询问
其他	一律询问

acceptEdits（自动批准文件编辑）

适合"想边写边过 diff，不想被每个 Edit 弹窗打断"。

工具类型	决定
Read	信任目录内 → 放行；否则询问
Edit	一律放行
Bash	一律询问
其他	一律询问

注意：

• 仅自动批准 Edit 类工具（Edit / Write / NotebookEdit 等），不影响 Bash —— Bash 永远走单独的安全分级
• "信任目录"以工作区根 + 用户配置的 permissions.additionalDirectories + 启动时 --add-dir 为准
• 读写受保护文件仍照原模式询问，不走自动放行

plan（探索后再改）

CodeBuddy 在 plan 模式下专心读代码、跑只读 Bash 命令探查，把方案写成计划再回来征求你的同意；不会落地修改你的源码。

plan 模式不是独立的"全块只读"，而是委托给前置模式：

• Read：把决定权交给前置模式（默认是 default）
• Edit：仅当目标路径是当前会话的计划文件时放行；否则委托给前置模式
• Bash：委托给前置模式
• 进入 plan 通过 Shift+Tab 或工具 EnterPlanMode；退出通过再次 Shift+Tab 或 ExitPlanMode

启动时直接进 plan：

codebuddy --permission-mode plan

bypassPermissions（跳过所有检查）

字面意思：全部跳过审批。所有 Bash、Edit、网络、MCP 都立刻执行。仅在以下场景使用：

• 隔离的容器 / VM / dev container
• 没有外网的 sandbox
• 你完全清楚后果的脚本化场景

启动方式：

codebuddy --permission-mode bypassPermissions
# 等价
codebuddy -y
codebuddy --dangerously-skip-permissions

关闭通道（管理员）

把 permissions.disableBypassPermissionsMode: "disable" 写到任一层 settings：

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

写入后即使会话切到 bypassPermissions，权限策略也会降级回 default 的判定；多层 settings（user / project / local / CLI 启动参数）任一层为 "disable" 即生效。

delegate（多代理协调模式）

主代理在 delegate 模式下只能调度：发任务、起子代理、跨成员通信，自己不动手编辑或跑命令。

行为：

• 主代理可用的工具集中只保留协调类工具（Agent / TaskCreate / SendMessage 等），全部自动放行
• 实现类工具（Read / Write / Edit / Bash 等）会被屏蔽，由子代理执行

适合的场景：你明确要做"主代理只规划、各专业子代理实施"的协作任务（Agent Teams / 子代理）。

按 Shift+Tab 循环到 delegate 即可进入。

work（IDE 集成）

由 IDE 客户端通过协议设置，CLI 用户不直接接触。语义：

工具类型	决定
Read	直接放行（不检查信任目录）
Edit	一律询问
Bash	安全命令直接放行；危险或需要审批的命令询问
其他	放行

fullAccess（IDE 集成）

仅由 IDE 客户端通过协议传入；与 bypassPermissions 同语义。

ignore（子代理专用）

仅子代理的 frontmatter / option 用到 —— 子代理把 permissionMode: ignore 写在自己的元信息里时，会被识别为"不要覆盖父代理的模式"，沿用父会话当前模式。主会话不会出现这个值。

受保护的关键文件

下列路径的写入操作即使在 acceptEdits / bypassPermissions 也会保留特殊处理：

• 仓库自身：.git、.gitconfig、.gitmodules
• shell 配置：.bashrc / .bash_profile / .zshrc / .zprofile / .envrc 等
• 包管理：.npmrc / .yarnrc / .pnpmfile.cjs / bunfig.toml 等
• IDE / 工具：.vscode / .idea / .husky / .devcontainer / .cargo / .yarn / .mvn
• CodeBuddy 自身：.codebuddy（除 .codebuddy/worktrees）
• MCP / 配置：.mcp.json / .codebuddy.json

子代理的权限模式继承

子代理（Agent 工具调用、Agent Teams 队员）默认继承主会话的权限模式。要在团队 / 项目层强制覆盖：

{
  "permissions": {
    "subagentPermissionMode": "bypassPermissions"
  }
}

写入后所有子代理都会按 bypassPermissions 跑。注意：

• Agent 工具调用时显式传 mode 参数 → 优先级最高，覆盖此设置
• 子代理 frontmatter 里写 permissionMode: ignore → 仍按主会话模式跑（不被本设置影响）

与 Permissions 规则配合

权限模式定义"基线"。在 ~/.codebuddy/settings.json 或仓库 .codebuddy/settings.json 的 permissions 下还可以叠加规则：

{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test)", "Read(/etc/hosts)"],
    "ask": ["WebFetch"],
    "deny": ["Bash(rm -rf *)", "Edit(.git/**)"]
  }
}

• allow / ask / deny 三层优先级高于 mode 的判定（除 bypassPermissions 整段跳过权限层）
• 详细规则语法见 Settings 配置、安全 与 IAM

相关资源

• Agent Teams：多代理协作：在 delegate 模式下让主代理专注调度
• 子代理（Sub-agents）：子代理的工具与权限模式继承
• Hooks 钩子系统：用 PreToolUse 钩子做自定义放行 / 拦截
• Bash 沙箱化：在 Bash 命令层加文件系统 / 网络隔离
• Settings 配置：权限规则、信任目录、disableBypassPermissionsMode 等完整字段
• CLI 参考：--permission-mode / -y / --add-dir 等启动参数
• 非交互模式：-p 流程下使用权限模式