设置

配置文件

settings.json 文件是配置 CodeBuddy Code 的官方机制，支持分层设置：

用户设置 定义在 ~/.codebuddy/settings.json，应用于所有项目

项目设置 保存在项目目录中：

.codebuddy/settings.json 用于检入源代码控制并与团队共享的设置

.codebuddy/settings.local.json 用于不检入的设置，适合个人偏好和实验。CodeBuddy Code 会自动配置 git 忽略此文件

完整配置示例

{  "language": "简体中文",  "permissions": {    "allow": [      "Bash(npm run lint)",      "Bash(npm run test:*)",      "Read(~/.zshrc)"    ],    "ask": [      "Bash(git push:*)"    ],    "deny": [      "Bash(curl:*)",      "Read(./.env)",      "Read(./.env.*)",      "Read(./secrets/**)"    ]  },  "env": {    "NODE_ENV": "development",    "DEBUG": "codebuddy:*"  },  "model": "gpt-5",  "subagents": {    "agents": {      "Explore": { "model": "lite" },      "Plan": { "model": "reasoning" }    }  },  "variantModels": {    "lite": "<fast-model-id>",    "reasoning": "<reasoning-model-id>"  },  "cleanupPeriodDays": 30,  "includeCoAuthoredBy": false,  "statusLine": {    "type": "command",    "command": "~/.codebuddy/statusline.sh"  }}

可用设置

settings.json 支持以下选项：

权限设置

Auto Mode 配置

autoMode 是一个顶层 settings 字段，不是 permissions 的子字段。它定义 auto 权限模式使用的分类器上下文与规则。

autoMode 里有哪些字段？

这些字段的值都是字符串数组。数组项不是正则，也不是工具模式，而是写给分类器看的自然语言规则。

分类器会从哪里读取 autoMode？

CodeBuddy 只会从以下来源读取 autoMode：

不会读取的来源：

共享项目配置 .codebuddy/settings.json

原因是：autoMode 属于本地安全边界定义，仓库提交的配置不应该悄悄改变您本机对“哪些地方算内部、哪些动作算允许”的判断。

与 permissions.defaultMode: "auto" 的区别

这里有两个容易混淆的限制：

autoMode 规则来源：允许来自 user / project-local / CLI

默认进入 auto 模式的授权来源：只允许来自 user / CLI

也就是说：

.codebuddy/settings.local.json 可以补充 autoMode.environment / allow / soft_deny / hard_deny

但 .codebuddy/settings.local.json 不能通过 permissions.defaultMode: "auto" 让会话默认进入 auto

.codebuddy/settings.json 两者都不行：既不能提供 autoMode，也不能授予 defaultMode: "auto"

多个来源如何合并？

autoMode 的四个字段会按来源顺序合并：

user

project-local

CLI

合并时遵循两个原则：

每个字段独立合并，互不影响

每个字段都是把不同来源的数组追加在一起，再统一处理 "$defaults"

这意味着：

您只设置 environment，不会影响 allow / soft_deny / hard_deny 的默认值

您可以在 user settings 里放组织级受信域名，再在 project-local 补充某个项目独有的 staging 服务

"$defaults" 怎么工作？

"$defaults" 是一个特殊占位符，表示“把内置默认规则插到这里”。

例如：

{  "autoMode": {    "environment": [      "$defaults",      "Trusted internal domains: staging.example.com"    ]  }}

表示：

先使用内置 environment 默认规则

再追加您自定义的 staging.example.com

关键语义：

字段未配置：该字段直接使用内置默认规则

字段里包含 "$defaults"：在该位置展开默认规则

字段里不包含 "$defaults"：表示完整替换该字段的内置默认规则

多个来源都写了 "$defaults" 时，内置规则只会展开一次，不会重复注入

额外提醒：

soft_deny / hard_deny 如果不写 "$defaults"，等于主动放弃内置安全规则

运行时会对此打 warning，但不会阻止您这样配置

如何检查当前生效结果？

codebuddy auto-mode defaultscodebuddy auto-mode configcodebuddy auto-mode critique

这三个命令分别用于：

defaults：打印内置默认规则

config：打印最终生效的规则（含多来源合并、"$defaults" 展开后的结果）

critique：让 lite 模型审视您自定义的 allow / soft_deny / hard_deny 是否含糊、冗余或容易误伤

如果您准备完全接管某个字段，最稳妥的做法通常是：

先运行 codebuddy auto-mode defaults

复制内置规则

在您的 settings 中显式改写

再运行 codebuddy auto-mode config 检查最终结果

配置示例

只补充受信环境

{  "autoMode": {    "environment": [      "$defaults",      "Source control: git.example.com/acme and all repos under it",      "Trusted internal domains: staging.example.com, api.internal.example.com",      "Trusted buckets: s3://acme-build-artifacts"    ]  }}

同时补充 allow / deny 规则

{  "permissions": {    "defaultMode": "auto"  },  "autoMode": {    "environment": [      "$defaults",      "Trusted internal domains: staging.example.com"    ],    "allow": [      "$defaults",      "允许 dev namespace 的发布"    ],    "soft_deny": [      "$defaults",      "修改共享测试数据库 schema"    ],    "hard_deny": [      "$defaults",      "把私有仓库内容发布到公网"    ]  }}

记忆功能配置

记忆功能允许 CodeBuddy Code 在会话之间保持持久化记忆，自动管理项目上下文和学习历史。

配置示例：

{  "memory": {    "autoMemoryEnabled": true,    "typedMemory": true,    "relevanceSelection": true,    "memoryExtraction": false,    "teamMemory": {      "enabled": true,      "userId": "yangsubo"    }  }}

记忆存储位置：

个人模式（默认）：~/.codebuddy/memories/{project-id}/

团队模式：{project}/.codebuddy/memories/@{user-id}/

全局记忆：~/.codebuddy/memories/global/

也可以通过 /config 命令在设置面板中启用此功能。

Bash 沙箱设置

配置高级沙箱行为。沙箱将 bash 命令与您的文件系统和网络隔离。详见 Bash 沙箱文档。

文件系统和网络限制通过 Read、Edit 和 WebFetch 权限规则配置，而非通过这些沙箱设置。

配置示例：

{  "sandbox": {    "enabled": true,    "autoAllowBashIfSandboxed": true,    "excludedCommands": ["docker"],    "network": {      "allowUnixSockets": [        "/var/run/docker.sock"      ],      "allowLocalBinding": true    }  },  "permissions": {    "deny": [      "Read(.envrc)",      "Read(~/.aws/**)"    ]  }}

文件系统访问通过 Read/Edit 权限控制：

Read deny 规则阻止沙箱中的文件读取

Edit allow 规则允许文件写入（除默认值外，如当前工作目录）

Edit deny 规则阻止路径内的写入

注意：

沙箱默认将 CodeBuddy 配置文件（settings.json、settings.local.json）加入写保护列表，防止沙箱内的命令或工具篡改配置。详见 Bash 沙箱 - 配置文件保护。

网络访问通过 WebFetch 权限控制：

WebFetch allow 规则允许网络域

WebFetch deny 规则阻止网络域

设置优先级

设置按优先级顺序应用（从高到低）:

命令行参数

特定会话的临时覆盖

本地项目设置 (.codebuddy/settings.local.json)

个人项目特定设置

共享项目设置 (.codebuddy/settings.json)

源代码控制中的团队共享项目设置

用户设置 (~/.codebuddy/settings.json)

个人全局设置

此层次结构确保团队可以建立共享标准，同时仍允许个人自定义体验。

配置系统要点

内存文件 （CODEBUDDY.md)：包含 CodeBuddy 在启动时加载的指令和上下文

设置文件 （JSON)：配置权限、环境变量和工具行为

斜杠命令：可在会话期间使用 /command-name 调用的自定义命令

MCP 服务器：使用额外工具和集成扩展 CodeBuddy Code

优先级：更高级别的配置覆盖更低级别的配置

继承：设置被合并，更具体的设置添加或覆盖更广泛的设置

排除敏感文件

为防止 CodeBuddy Code 访问包含敏感信息的文件（如 API 密钥、秘密、环境文件），在 .codebuddy/settings.json 文件中使用 permissions.deny 设置：

{  "permissions": {    "deny": [      "Read(./.env)",      "Read(./.env.*)",      "Read(./secrets/**)",      "Read(./config/credentials.json)",      "Read(./build)"    ]  }}

匹配这些模式的文件将对 CodeBuddy Code 完全不可见，防止任何敏感数据的意外泄露。

Gateway 配置

gateway 字段配置 Remote Gateway（--serve 模式下 HTTP/SSE 对外暴露 /api/v1/runs 等端点）的行为。

{  "gateway": {    "auth": "none",    "maxConnections": 5,    "tokenTtlMs": 86400000,    "runTimeoutMs": 1800000  }}

runTimeoutMs 覆盖优先级

长任务（如复杂 agent 多轮搜索、大文件处理）可能超过默认 30 分钟，支持两种覆盖方式：



HTTP 请求头 X-Codebuddy-Run-Timeout（毫秒数）： 针对单次请求覆盖，优先级最高

settings.json 里 gateway.runTimeoutMs — 进程级默认值

内置默认值 ：30 分钟

示例：

# 单次请求给 60 分钟curl -X POST http://127.0.0.1:7890/api/v1/runs \  -H "Content-Type: application/json" \  -H "X-Codebuddy-Run-Timeout: 3600000" \  -d '{"id":"run-1","type":"message","payload":{"text":"..."}}'

设为 0 或负数关闭超时保护（不建议，长任务未结束会一直占用 SSE 长连接）。

子代理配置

CodeBuddy Code 支持为内置子代理独立选择模型，也支持通过 Markdown 文件创建自定义子代理。

内置子代理与场景模型可以在用户级或项目级 settings.json 中组合配置：

{  "subagents": {    "agents": {      "Explore": { "model": "lite" },      "Plan": { "model": "reasoning" }    }  },  "variantModels": {    "lite": "<fast-model-id>",    "reasoning": "<reasoning-model-id>"  }}

使用 /agents 编辑内置子代理映射；使用 /model:lite / /model:reasoning 编辑 lite 和 reasoning 映射。

Global 写入用户设置，Project 写入共享项目设置。

subagents 按子代理名合并，variantModels 按变体名合并。项目级覆盖 Explore 不会删除用户级的其他子代理配置；项目级覆盖 reasoning 也不会删除用户级的 lite。

在 /agents 中选择 Inherit / Default，或在 /model 中选择 Default，会删除所选范围的对应项并恢复低优先级解析链。

自定义子代理存储为带有 YAML frontmatter 的 Markdown 文件：

用户子代理：~/.codebuddy/agents/ - 在所有项目中可用

项目子代理：.codebuddy/agents/ - 特定于项目，可与团队共享

自定义子代理文件定义专用提示、模型和工具权限。完整配置方式和优先级详见 子代理文档。

插件配置

CodeBuddy Code 支持插件系统，允许您使用自定义命令、代理、hooks 和 MCP 服务器扩展功能。插件通过市场分发，可在用户和项目级别配置。

插件设置

settings.json 中的插件相关设置：

{  "enabledPlugins": {    "formatter@company-tools": true,    "deployer@company-tools": true,    "analyzer@security-plugins": false  },  "extraKnownMarketplaces": {    "company-tools": {      "source": {        "source": "github",        "repo": "company/codebuddy-plugins"      }    }  }}

enabledPlugins

控制启用哪些插件。格式："plugin-name@marketplace-name": true/false

作用域：

用户设置 (~/.codebuddy/settings.json)：个人插件偏好

项目设置 (.codebuddy/settings.json)：与团队共享的项目特定插件

本地设置 (.codebuddy/settings.local.json)：每台机器的覆盖（不提交）

示例:

{  "enabledPlugins": {    "code-formatter@team-tools": true,    "deployment-tools@team-tools": true,    "experimental-features@personal": false  }}

extraKnownMarketplaces

定义应为项目提供的额外市场。通常在项目级设置中使用，以确保团队成员可以访问所需的插件源。

当项目包含 extraKnownMarketplaces 时:

团队成员在信任文件夹时被提示安装市场

然后团队成员被提示从该市场安装插件

用户可以跳过不需要的市场或插件（存储在用户设置中）

安装遵守信任边界并需要明确同意

示例:

{  "extraKnownMarketplaces": {    "company-tools": {      "source": {        "source": "github",        "repo": "company-org/codebuddy-plugins"      }    },    "security-plugins": {      "source": {        "source": "git",        "url": "https://git.company.com/security/plugins.git"      }    }  }}

市场源类型:

github: GitHub 仓库（使用 repo)

git:任何 git URL(使用 url)

directory:本地文件系统路径(使用 path,仅用于开发）

管理插件

使用 /plugin 命令交互式管理插件：

浏览市场中的可用插件

安装/卸载插件

启用/禁用插件

查看插件详细信息（提供的命令、代理、hooks)

添加/删除市场

详见 插件文档。

环境变量

CodeBuddy Code 支持通过环境变量来控制其行为。所有环境变量也可以在 settings.json 的 env 字段中配置，这样可以自动为每个会话应用，或为整个团队推出配置。

完整的环境变量参考文档请参见 环境变量参考。

快速入门

基础认证配置：

# 使用 API 密钥
export CODEBUDDY_API_KEY="your-api-key"
codebuddy

# 或使用授权令牌
export CODEBUDDY_AUTH_TOKEN="your-token"
codebuddy

设置代理：

export HTTPS_PROXY="https://proxy.example.com:8080"export NO_PROXY="localhost,127.0.0.1"codebuddy

启用高级功能：

# 扩展思考
export MAX_THINKING_TOKENS="10000"

# 自动内存
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

codebuddy -p "您的查询"

在 settings.json 中配置

环境变量也可以在 settings.json 的 env 字段中设置：

{  "env": {    "CODEBUDDY_API_KEY": "your-api-key",    "HTTPS_PROXY": "https://proxy.example.com:8080",    "MAX_THINKING_TOKENS": "10000"  }}

更多配置示例和高级用法，请参见 环境变量参考 和 使用示例。

状态行配置

配置终端底部显示的状态行，可以显示当前会话、模型、成本等信息：

{  "statusLine": {    "type": "command",    "command": "~/.codebuddy/statusline-script.sh"  }}

状态行命令会接收包含会话信息的 JSON 数据作为 stdin 输入，包括：

session_id：会话 ID

model：当前模型信息

workspace：工作空间路径信息

cost：成本统计信息

version：应用版本

使用 /statusline 命令可以快速配置状态行。

配置管理命令

使用 codebuddy config 命令管理配置：

基本语法

codebuddy config [command] [options]

可用命令

选项

使用示例

查看配置

# 列出所有配置
codebuddy config list

# 获取特定配置值
codebuddy config get model
codebuddy config get permissions

设置配置

# 设置项目级模型（不需要 -g 标志）
codebuddy config set model gpt-5

# 设置全局模型（需要 -g 标志）
codebuddy config set -g model gpt-4

# 设置项目级权限配置（不需要 -g 标志）
codebuddy config set permissions '{"allow": ["Read", "Edit"], "deny": ["Bash(rm:*)"]}'

# 设置项目级环境变量（不需要 -g 标志）
codebuddy config set env '{"NODE_ENV": "development", "DEBUG": "true"}'

# 设置全局专用配置（需要 -g 标志）
codebuddy config set -g cleanupPeriodDays 30
codebuddy config set -g includeCoAuthoredBy false

CodeBuddy 可用的工具

CodeBuddy Code 可以访问一组强大的工具，帮助它理解和修改您的代码库：

权限规则可以使用 /permissions 或在权限设置中配置。另见工具特定的权限规则。

使用 hooks 扩展工具

您可以使用 CodeBuddy Code hooks 在任何工具执行前后运行自定义命令

例如，您可以在 CodeBuddy 修改 Python 文件后自动运行 Python 格式化程序，或通过阻止对某些路径的 Write 操作来防止修改生产配置文件。

常见配置场景

团队协作配置

项目共享配置（.codebuddy/settings.json）：

{  "model": "gpt-5",  "permissions": {    "allow": ["Read", "Edit", "Bash(git:*)", "Bash(npm:*)"],    "ask": ["WebFetch", "Bash(docker:*)"],    "deny": ["Bash(rm:*)", "Bash(sudo:*)"]  },  "env": {    "NODE_ENV": "development"  }}

个人本地配置（.codebuddy/settings.local.json）：

{  "model": "gpt-4",  "env": {    "DEBUG": "myapp:*"  }}

安全配置

限制敏感操作和文件访问：

{  "permissions": {    "allow": ["Read", "Edit(src/**)", "Bash(git:status,git:diff)"],    "ask": ["WebFetch", "Bash(curl:*)"],    "deny": [      "Edit(**/*.env)",      "Edit(**/*.key)",      "Edit(**/*.pem)",      "Bash(wget:*)",      "Read(/etc/**)",      "Read(~/.ssh/**)"    ],    "defaultMode": "default"  }}

沙箱安全配置

启用沙箱并配置文件系统和网络访问：

{  "sandbox": {    "enabled": true,    "autoAllowBashIfSandboxed": true,    "excludedCommands": ["docker", "git"],    "network": {      "allowUnixSockets": ["/var/run/docker.sock"],      "allowLocalBinding": true    }  },  "permissions": {    "allow": [      "Edit(src/**)",      "WebFetch(https://api.github.com/**)"    ],    "deny": [      "Read(.envrc)",      "Read(~/.aws/**)",      "Edit(**/*.env)"    ]  }}