CodeBuddy CLI 设置配置

CodeBuddy Code 使用分层配置系统，让您能够在不同级别进行个性化定制，从个人偏好到团队标准，再到项目特定需求。

️ 配置层次结构 ​

CodeBuddy Code 使用分层配置系统，设置按以下优先级合并（后者覆盖前者）：

命令行参数 (最高优先级)
├── 项目本地设置 (./.codebuddy/settings.local.json)
├── 项目共享设置 (./.codebuddy/settings.json)  
└── 用户设置 (~/.codebuddy/settings.json) (最低优先级)

配置文件位置 ​

配置作用域说明 ​

• 用户级配置: 影响所有项目的默认行为
• 项目共享配置: 团队成员共享的项目标准
• 项目本地配置: 个人在特定项目中的自定义设置

⚙️ 配置选项参考 ​

完整配置示例 ​

{
  "model": "gpt-5",
  "cleanupPeriodDays": 30,
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  },
  "includeCoAuthoredBy": false,
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git:*)"],
    "deny": ["Bash(rm:*)", "Bash(sudo:*)"],
    "additionalDirectories": ["/tmp", "/var/log"],
    "defaultMode": "default"
  },
  "hooks": {
    "PreToolUse": "echo 'About to use tool: $TOOL_NAME'"
  },
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["filesystem", "git"],
  "disabledMcpjsonServers": ["dangerous-tool"],
  "autoCompactEnabled": true,
  "autoUpdates": true,
  "apiKeyHelper": "/usr/local/bin/get-api-key.sh"
}

配置选项详细说明 ​

环境变量配置 ​

通过 env 对象为每个会话设置环境变量：

{
  "env": {
    "NODE_ENV": "development",
    "API_URL": "https://api.example.com",
    "DEBUG": "codebuddy:*"
  }
}

权限系统 ​

CodeBuddy Code 使用细粒度权限系统控制工具访问：

权限配置选项 ​

权限规则语法 ​

{
  "permissions": {
    "allow": [
      "Read",                           // 允许读取文件
      "Edit",                          // 允许编辑文件
      "Bash(git:*)",                   // 允许所有 git 命令
      "Bash(npm:install,npm:test)",    // 允许特定 npm 命令
      "Edit(src/**/*.js)"              // 只允许编辑 src 目录下的 JS 文件
    ],
    "ask": [
      "Bash(curl:*)",                  // 询问后允许 curl 命令
      "WebFetch",                      // 询问后允许网络请求
      "Bash(docker:*)"                 // 询问后允许 Docker 命令
    ],
    "deny": [
      "Bash(rm:*)",                    // 禁止删除命令
      "Bash(sudo:*)",                  // 禁止 sudo 命令
      "Edit(**/*.env)",                // 禁止编辑环境变量文件
      "Read(/etc/**)"                  // 禁止读取系统配置文件
    ],
    "additionalDirectories": ["/tmp", "/var/log"],
    "defaultMode": "default"
  }
}

权限模式 ​

动态权限模式管理 ​

从当前版本开始，权限模式支持会话级动态切换：

• CLI 启动时设置: 使用 --permission-mode 参数指定初始权限模式
• 运行时动态更新: 权限模式会在会话中动态更新，并在UI中实时显示当前状态
• 优先级顺序: CLI参数 > 设置文件中的 defaultMode > 系统默认值(default)
• UI 状态显示: 当权限模式不是 default 时，会在界面中显示当前权限模式状态

# 启动时设置权限模式
codebuddy --permission-mode acceptEdits

# 权限模式会在会话中保持，并可通过UI查看当前状态

MCP 服务器管理 ​

控制 Model Context Protocol (MCP) 服务器的启用和禁用：

{
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["filesystem", "git"],
  "disabledMcpjsonServers": ["experimental-tool"]
}

环境变量 ​

CodeBuddy Code 支持通过环境变量进行配置。

认证相关 ​

运行环境 ​

使用示例 ​

# 设置认证令牌
export CODEBUDDY_AUTH_TOKEN="your-auth-token"

# 设置 API 密钥
export CODEBUDDY_API_KEY="your-api-key"

# 设置自定义请求头
export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1
X-Another-Header: value2"

# 启动 CodeBuddy
codebuddy

配置管理命令 ​

使用 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 config add env ‘{“DEBUG”: “true”}’

# 移除配置

codebuddy config remove model

支持的配置键 ​

根据代码实现，配置键按作用域分为两类：

全局配置键（需要 -g/--global 标志） ​

项目配置键（可在项目级设置） ​

注意:

• 全局配置键只能使用 -g/--global 标志设置到用户级配置
• 项目配置键可以在项目级设置，不需要 -g 标志
• 如果尝试在错误的作用域设置配置键，会收到相应的错误提示

完整示例 ​

# 查看当前所有配置
codebuddy config list

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

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

# 配置全局权限系统（需要 -g 标志）
codebuddy config set -g permissions '{
  "allow": ["Read", "Edit", "Bash(git:*)"],
  "deny": ["Bash(rm:*)", "Bash(sudo:*)"],
  "defaultMode": "default"
}'

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

# 设置全局环境变量（需要 -g 标志）
codebuddy config set -g env '{
  "DEBUG": "codebuddy:*",
  "API_URL": "https://api.example.com"
}'

# 设置全局配置项（需要 -g 标志）
codebuddy config set -g cleanupPeriodDays 7
codebuddy config set -g includeCoAuthoredBy true
codebuddy config set -g autoUpdates false

# 验证设置
codebuddy config get model
codebuddy config get permissions

常见配置场景 ​

团队协作配置 ​

项目共享配置 (./.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"
  }
}

开发环境配置 ​

针对不同开发阶段的配置：

{
  "model": "gpt-5",
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": [
      "Read", "Edit", 
      "Bash(npm:*)", "Bash(yarn:*)",
      "Bash(git:*)", "Bash(docker:ps,docker:logs)"
    ],
    "additionalDirectories": ["/tmp", "./logs"]
  },
  "enabledMcpjsonServers": ["filesystem", "git"]
}