设置配置

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

配置文件

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

用户设置 定义在 ~/.codebuddy/settings.json，应用于所有项目
项目设置 保存在项目目录中：
- .codebuddy/settings.json 用于检入源代码控制并与团队共享的设置
- .codebuddy/settings.local.json 用于不检入的设置，适合个人偏好和实验。CodeBuddy Code 会自动配置 git 忽略此文件

完整配置示例

json

{
  "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",
  "cleanupPeriodDays"：30,
  "includeCoAuthoredBy": false,
  "statusLine": {
    "type": "command",
    "command": "~/.codebuddy/statusline.sh"
  }
}

可用设置

settings.json 支持以下选项：

配置键	描述	示例
`apiKeyHelper`	自定义脚本,在 `/bin/sh` 中执行,生成认证值。此值将作为模型请求的 `X-Api-Key` 和 `Authorization: Bearer` 头发送	`/bin/generate_temp_api_key.sh`
`cleanupPeriodDays`	根据最后活动日期本地保留聊天记录的时长(默认:30 天)	`20`
`env`	应用于每个会话的环境变量	`{"FOO": "bar"}`
`includeCoAuthoredBy`	是否在 git 提交和拉取请求中包含 `co-authored-by CodeBuddy` 署名(默认:`true`）	`false`
`permissions`	权限配置，见下表
`hooks`	配置在工具执行前后运行的自定义命令。见 hooks 文档	`{"PreToolUse": {"Bash": "echo 'Running command...'"}}`
`disableAllHooks`	禁用所有 hooks	`true`
`model`	覆盖 CodeBuddy Code 使用的默认模型	`"gpt-5"`
`statusLine`	配置自定义状态行以显示上下文。见 [statusLine 文档](#状态行配置）	`{"type": "command", "command": "~/.codebuddy/statusline.sh"}`
`enableAllProjectMcpServers`	自动批准项目 `.mcp.json` 文件中定义的所有 MCP 服务器	`true`
`enabledMcpjsonServers`	从 `.mcp.json` 文件批准的特定 MCP 服务器列表	`["memory", "github"]`
`disabledMcpjsonServers`	从 `.mcp.json` 文件拒绝的特定 MCP 服务器列表	`["filesystem"]`
`autoCompactEnabled`	开启自动压缩功能	`true`
`autoUpdates`	自动更新设置	`false`
`alwaysThinkingEnabled`	始终启用思考模式	`true`
`showTokensCounter`	是否在界面中显示 Tokens 计数器	`false`
`endpoint`	自定义服务端点地址	`"https://api.example.com"`
`envRouteMode`	环境路由模式配置	`"production"`
`sandbox`	Bash 沙箱配置,见[Bash 沙箱设置](#bash 沙箱设置)	`{"enabled": true}`

权限设置

配置键	描述	示例
`allow`	权限规则数组,允许工具使用。注意: Bash 规则使用前缀匹配,不是正则表达式	`[ "Bash(git diff:*)" ]`
`ask`	权限规则数组,在工具使用时询问确认	`[ "Bash(git push:*)" ]`
`deny`	权限规则数组,拒绝工具使用。用于排除 CodeBuddy Code 访问敏感文件。注意: Bash 模式是前缀匹配,可以被绕过(参见 Bash 权限限制)	`[ "WebFetch", "Bash(curl:)", "Read(./.env)", "Read(./secrets/*)" ]`
`additionalDirectories`	CodeBuddy 可以访问的额外[工作目录](iam.md#工作目录）	`[ "../docs/" ]`
`defaultMode`	打开 CodeBuddy Code 时的默认[权限模式](iam.md#权限模式）	`"acceptEdits"`
`disableBypassPermissionsMode`	设置为 `"disable"` 以防止激活 `bypassPermissions` 模式。这会禁用 `-y` 和 `--dangerously-skip-permissions` 命令行标志	`"disable"`

Bash沙箱设置

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

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

配置键	描述	示例
`enabled`	启用 bash 沙箱(仅限 macOS/Linux)。默认:false	`true`
`autoAllowBashIfSandboxed`	在沙箱环境中自动批准 bash 命令。默认:true	`true`
`excludedCommands`	应在沙箱外运行的命令	`["git", "docker"]`
`allowUnsandboxedCommands`	允许通过 `dangerouslyDisableSandbox` 参数在沙箱外运行命令。设置为 `false` 时，完全禁用
`network.allowUnixSockets`	沙箱中可访问的 Unix 套接字路径（用于 SSH 代理等）	`["~/.ssh/agent-socket"]`
`network.allowLocalBinding`	允许绑定到 localhost 端口(仅限 macOS)。默认: false	`true`
`network.httpProxyPort`	如果您希望使用自己的代理,使用的 HTTP 代理端口。如果未指定,CodeBuddy 将运行自己的代理	`8080`
`network.socksProxyPort`	如果您希望使用自己的代理,使用的 SOCKS5 代理端口。如果未指定,CodeBuddy 将运行自己的代理	`8081`
`enableWeakerNestedSandbox`	为无特权的 Docker 环境启用较弱的沙箱(仅限 Linux)。降低安全性。默认:false	`true`

配置示例：

json

{
  "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 规则阻止允许路径内的写入

网络访问通过 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 设置：

json

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

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

子代理配置

CodeBuddy Code 支持可在用户和项目级别配置的自定义 AI 子代理。这些子代理存储为带有 YAML frontmatter 的 Markdown 文件：

用户子代理：~/.codebuddy/agents/ - 在所有项目中可用
项目子代理：.codebuddy/agents/ - 特定于项目，可与团队共享

子代理文件定义具有自定义提示和工具权限的专用 AI 助手。详见子代理文档。

插件配置

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

插件设置

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

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)：每台机器的覆盖（不提交）

示例:

json

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

`extraKnownMarketplaces`

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

当项目包含 extraKnownMarketplaces 时:

团队成员在信任文件夹时被提示安装市场
然后团队成员被提示从该市场安装插件
用户可以跳过不需要的市场或插件（存储在用户设置中）
安装遵守信任边界并需要明确同意

示例:

json

{
  "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](#可用设置）中配置。这对于自动为每个会话设置环境变量，或为整个团队或组织推出一组环境变量很有用。

认证相关

环境变量	描述
`CODEBUDDY_API_KEY`	推荐使用。API 密钥，可以是 CodeBuddy 平台的 API Key，也可以是第三方模型提供商（如 OpenRouter）的 API Key。仅用于模型接口调用，大部分情况下配置此项即可
`CODEBUDDY_AUTH_TOKEN`	CodeBuddy 平台认证令牌，用于所有 CodeBuddy 平台接口调用（包括模型接口、Token 刷新接口、计费接口、配置下发接口、admin 管控接口等）。如果希望获得与本地登录认证后使用 CLI 等价的完整功能，可以配置此项
`CODEBUDDY_CUSTOM_HEADERS`	自定义 HTTP 请求头。多个 header 使用 `\n` 或换行符分隔,格式:`Header1: value1\nHeader2: value2`

使用场景说明：

CODEBUDDY_API_KEY：大部分场景推荐使用，仅用于模型接口调用，不会调用 Token 刷新、计费查询等其他平台接口。可以配置 CodeBuddy 平台的 API Key，也可以配合 CODEBUDDY_BASE_URL 使用第三方模型服务
CODEBUDDY_AUTH_TOKEN：如果需要 CodeBuddy 平台的完整功能（Token 刷新、计费查询、配置下发、admin 管控等），可以使用此环境变量，效果等价于本地登录认证后使用 CLI。配置的必须是 CodeBuddy 平台的 API Key

运行环境

环境变量	描述
`CODEBUDDY_BASE_URL`	自定义模型服务的基础 URL 地址,通常与 `CODEBUDDY_API_KEY` 配合使用。要求：兼容 OpenAI 接口协议
`CODEBUDDY_INTERNET_ENVIRONMENT`	网络环境配置（`internal` 用于中国版,`iOA` 用于 iOA 账号）
`ENV_PRODUCT_CLI_ACCOUNT_TYPE`	CLI 账户类型

Bash 工具配置

环境变量	描述
`BASH_DEFAULT_TIMEOUT_MS`	长时间运行的 bash 命令的默认超时（默认：120000）
`BASH_MAX_OUTPUT_LENGTH`	bash 输出在中间截断之前的最大字符数（默认：50000）
`BASH_MAX_TIMEOUT_MS`	模型可以为长时间运行的 bash 命令设置的最大超时（默认：600000）
`CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR`	每个 Bash 命令后返回原始工作目录 ⚠️ 暂未支持

其他配置

环境变量	描述
`CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS`	刷新凭据的间隔（毫秒）（使用 `apiKeyHelper` 时）（默认：300000）
`CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE`	设置为 `1` 以禁用基于对话上下文的自动终端标题更新
`CODEBUDDY_CODE_IDE_SKIP_AUTO_INSTALL`	跳过 IDE 扩展的自动安装 ⚠️ 暂未支持
`CODEBUDDY_CODE_MAX_OUTPUT_TOKENS`	设置大多数请求的最大输出 token 数
`DISABLE_AUTOUPDATER`	设置为 `1` 以禁用自动更新
`DISABLE_COST_WARNINGS`	设置为 `1` 以禁用成本警告消息 ⚠️ 暂未支持
`HTTP_PROXY` / `http_proxy`	HTTP 代理服务器地址（例如：`http://proxy.example.com:8080`）
`HTTPS_PROXY` / `https_proxy`	HTTPS 代理服务器地址（例如：`https://proxy.example.com:8080`）
`MAX_MCP_OUTPUT_TOKENS`	MCP 工具响应中允许的最大 token 数。当输出超过 10,000 个 token 时，CodeBuddy Code 会显示警告（默认：25000）
`MCP_TIMEOUT`	MCP 服务器连接的超时时间（毫秒）。适用于所有传输类型（stdio/sse/http）
`MCP_TOOL_TIMEOUT`	MCP 工具执行的超时（毫秒）
`NO_PROXY` / `no_proxy`	将直接发出请求的域和 IP 列表,绕过代理(支持逗号分隔,如:`localhost,.example.com`）
`SLASH_COMMAND_TOOL_CHAR_BUDGET`	显示给 [SlashCommand 工具](slash-commands.md#slashcommand-工具）的斜杠命令元数据的最大字符数（默认：15000）
`USE_BUILTIN_RIPGREP`	设置为 `0` 以使用系统安装的 `rg` 而不是 CodeBuddy Code 附带的 `rg`

mTLS 认证配置

环境变量	描述
`CODEBUDDY_CODE_CLIENT_CERT`	mTLS 客户端证书文件路径 ⚠️ 暂未支持
`CODEBUDDY_CODE_CLIENT_KEY`	mTLS 客户端私钥文件路径 ⚠️ 暂未支持
`CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASE`	mTLS 加密私钥的密码（可选） ⚠️ 暂未支持

Shell 配置

环境变量	描述
`CODEBUDDY_CODE_SHELL`	覆盖自动 shell 检测。当登录 shell 与首选工作 shell 不同时很有用（例如 `bash` vs `zsh`） ⚠️ 暂未支持
`CODEBUDDY_CODE_SHELL_PREFIX`	包装所有 bash 命令的命令前缀（例如用于日志或审计）。示例：`/path/to/logger.sh` 将执行 `/path/to/logger.sh <command>` ⚠️ 暂未支持
`CODEBUDDY_CODE_GIT_BASH_PATH`	Windows 下显式指定 Git Bash 路径

模型配置

环境变量	描述
`CODEBUDDY_MODEL`	模型设置名称 ⚠️ 暂未支持
`CODEBUDDY_SMALL_FAST_MODEL`	后台任务使用的小型快速模型 ⚠️ 暂未支持
`CODEBUDDY_BIG_SLOW_MODEL`	复杂推理任务使用的大型模型 ⚠️ 暂未支持
`CODEBUDDY_CODE_SUBAGENT_MODEL`	子代理使用的模型 ⚠️ 暂未支持
`MAX_THINKING_TOKENS`	启用扩展思考并设置思考过程的 token 预算。扩展思考可以提升复杂推理和编码任务的表现，但会影响提示缓存效率。默认禁用 ⚠️ 暂未支持

提示缓存配置

环境变量	描述
`DISABLE_PROMPT_CACHING`	设置为 `1` 以禁用所有模型的提示缓存（优先于单个模型设置） ⚠️ 暂未支持

遥测和报告配置

环境变量	描述
`CODEBUDDY_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	等同于同时设置 `DISABLE_AUTOUPDATER`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` ⚠️ 暂未支持
`DISABLE_ERROR_REPORTING`	设置为 `1` 以禁用错误报告 ⚠️ 暂未支持
`DISABLE_TELEMETRY`	设置为 `1` 以禁用遥测（遥测事件不包含用户数据如代码、文件路径或 bash 命令） ⚠️ 暂未支持
`DISABLE_NON_ESSENTIAL_MODEL_CALLS`	设置为 `1` 以禁用非关键路径的模型调用（如装饰性文本） ⚠️ 暂未支持
`DISABLE_BUG_COMMAND`	设置为 `1` 以禁用 `/bug` 命令 ⚠️ 暂未支持

界面配置

环境变量	描述
`CODEBUDDY_CODE_HIDE_ACCOUNT_INFO`	设置为 `1` 以在 CodeBuddy Code 界面中隐藏您的邮箱地址和组织名称。在直播或录屏时很有用 ⚠️ 暂未支持

文件读取配置

环境变量	描述
`CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS`	覆盖文件读取的默认 token 限制。当您需要完整读取大文件时很有用 ⚠️ 暂未支持

其他环境变量（补充）

环境变量	描述
`CODEBUDDY_CONFIG_DIR`	自定义 CodeBuddy Code 存储配置和数据文件的位置 ⚠️ 暂未支持
`CODEBUDDY_INTERNET_ENVIROMENT`	`CODEBUDDY_INTERNET_ENVIRONMENT` 的旧拼写（兼容保留）
`CODEBUDDY_CODE_DEBUG_LOGS_DIR`	调试日志目录（覆盖默认目录）
`CODEBUDDY_SANDBOX_IMAGE`	容器沙箱镜像（默认：`node:20-alpine`）
`SERVER__HOST`	`--serve` 模式监听地址（默认：`127.0.0.1`）
`SERVER__PORT`	`--serve` 模式监听端口

使用示例

基础认证配置

bash

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

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

# 设置代理服务器（支持大小写格式）
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"

# 设置代理绕过列表（可选）
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

# 设置自定义请求头（多个 header 使用 \n 分隔）
export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1\nX-Another-Header: value2"

# 启动 CodeBuddy
codebuddy

海外版使用 API KEY

海外版用户可以直接使用 API KEY 方式使用 CodeBuddy Code,无需设置 CODEBUDDY_INTERNET_ENVIRONMENT 变量：

bash

# 设置 API KEY （推荐方式，大部分情况下配置此项即可）
export CODEBUDDY_API_KEY="your-api-key"

# 启动 CodeBuddy
codebuddy

获取 API KEY: 海外版用户可以访问 https://www.codebuddy.ai/profile/keys 获取 API KEY。

中国版使用 API KEY

中国版用户需要配置 CODEBUDDY_INTERNET_ENVIRONMENT=internal 环境变量：

bash

# 设置中国版环境标识
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

# 设置 API KEY （推荐方式，大部分情况下配置此项即可）
export CODEBUDDY_API_KEY="your-api-key"

# 启动 CodeBuddy
codebuddy

也可以在一行命令中完成配置：

bash

CODEBUDDY_INTERNET_ENVIRONMENT=internal \
CODEBUDDY_API_KEY="your-api-key" \
codebuddy

获取 API KEY: 中国版用户可以访问 https://copilot.tencent.com/profile/ 获取 API KEY。

iOA 账号使用 API KEY

iOA 账号用户可以通过 API KEY 方式使用 CodeBuddy Code,需要配置以下环境变量：

bash

# 设置 iOA 环境标识
export CODEBUDDY_INTERNET_ENVIRONMENT=iOA

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

# 启动 CodeBuddy
codebuddy

也可以在一行命令中完成配置：

bash

CODEBUDDY_INTERNET_ENVIRONMENT=iOA \
CODEBUDDY_API_KEY="your-api-key" \
codebuddy

获取 API KEY: iOA 账号用户可以访问 https://tencent.sso.copilot.tencent.com/profile/keys 获取 API KEY。
注意：请妥善保管您的 API KEY,不要在代码仓库或公开场所泄露。

使用 OpenRouter 自定义模型

bash

# 使用 OpenRouter 服务，一行命令启动自定义模型
CODEBUDDY_API_KEY=sk-or-v1-9a951951428092casdffs702bsdf2513c292680cd621b9d0e39cf \
CODEBUDDY_BASE_URL=https://openrouter.ai/api/v1 \
codebuddy --model openai/gpt-5-codex

# 或者先设置环境变量
export CODEBUDDY_API_KEY="sk-or-v1-your-openrouter-api-key"
export CODEBUDDY_BASE_URL="https://openrouter.ai/api/v1"
codebuddy --model openai/gpt-5-codex

说明：当配置 CODEBUDDY_API_KEY 后：
仅会用于模型接口调用
不再调用 Token 刷新接口、计费接口等其他服务接口
可以配置 CodeBuddy 平台的 API Key,也可以配合 CODEBUDDY_BASE_URL 使用第三方模型服务
CODEBUDDY_BASE_URL 配置的模型服务需兼容 OpenAI 接口协议

使用 DeepSeek 模型

bash

# 使用 DeepSeek Chat 模型（标准对话模型）
CODEBUDDY_API_KEY=sk-your-deepseek-api-key \
CODEBUDDY_BASE_URL=https://api.deepseek.com/v1 \
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS=8000 \
codebuddy --model deepseek-chat

# 使用 DeepSeek Reasoner 模型（推理模型，支持更长输出）
CODEBUDDY_API_KEY=sk-your-deepseek-api-key \
CODEBUDDY_BASE_URL=https://api.deepseek.com/v1 \
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS=64000 \
codebuddy --model deepseek-reasoner

说明：
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS 用于设置最大输出 token 数，不同模型支持的最大值不同
DeepSeek Chat 建议设置为 8000
DeepSeek Reasoner 作为推理模型，支持更长输出，可设置为 64000

状态行配置

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

配置键	类型	描述
`statusLine.type`	string	状态行类型，目前支持 "command"
`statusLine.command`	string	执行的命令路径，支持 ~ 路径扩展

json

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

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

session_id：会话 ID
model：当前模型信息
workspace：工作空间路径信息
cost：成本统计信息
version：应用版本

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

配置管理命令

使用 codebuddy config 命令管理配置：

基本语法

bash

codebuddy config [command] [options]

可用命令

命令	语法	描述
`get`	`codebuddy config get <key>`	获取配置值
`set`	`codebuddy config set [options] <key> <value>`	设置配置值
`list`	`codebuddy config list`(别名:`ls`）	列出所有配置
`add`	`codebuddy config add <key> <values...>`	向数组配置添加项目
`remove`	`codebuddy config remove <key> [values...]`(别名:`rm`）	移除配置或数组项

选项

选项	描述	适用命令
`-g, --global`	设置全局配置	`set`

使用示例

查看配置

bash

# 列出所有配置
codebuddy config list

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

设置配置

bash

# 设置项目级模型（不需要 -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 可以访问一组强大的工具，帮助它理解和修改您的代码库：

工具	描述	需要权限
AskUserQuestion	向用户询问多选问题以收集信息或澄清歧义	否
Bash	在您的环境中执行 shell 命令	是
BashOutput	从后台 bash shell 检索输出	否
Edit	对特定文件进行有针对性的编辑	是
MultiEdit	在单个操作中对单个文件进行多次编辑	是
ExitPlanMode	提示用户退出计划模式并开始编码	是
Glob	基于模式匹配查找文件	否
Grep	在文件内容中搜索模式	否
KillShell	通过 ID 终止正在运行的后台 bash shell	否
NotebookEdit	修改 Jupyter notebook 单元格	是
Read	读取文件内容	否
Skill	在主对话中执行技能	是
SlashCommand	运行[自定义斜杠命令](slash-commands.md#slashcommand-工具）	是
Task	运行子代理以处理复杂的多步骤任务	否
TodoWrite	创建和管理结构化任务列表	否
WebFetch	从指定 URL 获取内容	是
WebSearch	执行带域过滤的网络搜索	是
Write	创建或覆盖文件	是

权限规则可以使用 /permissions 或在[权限设置](#权限设置）中配置。另见[工具特定的权限规则](iam.md#工具特定的权限规则）。

使用 hooks 扩展工具

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

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

常见配置场景

团队协作配置

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

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）：

json

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

安全配置

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

json

{
  "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"
  }
}

沙箱安全配置

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

json

{
  "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)"
    ]
  }
}

另见

[身份和访问管理](iam.md#配置权限） - 了解 CodeBuddy Code 的权限系统
Bash 沙箱 - 了解沙箱隔离功能
故障排除 - 常见配置问题的解决方案

合适的配置让 CodeBuddy Code 更懂您的需求 ⚙️

设置配置 ​

配置文件 ​

完整配置示例 ​

可用设置 ​

权限设置 ​

Bash沙箱设置 ​

设置优先级 ​

配置系统要点 ​

排除敏感文件 ​

子代理配置 ​

插件配置 ​

插件设置 ​

enabledPlugins ​

extraKnownMarketplaces ​

管理插件 ​

环境变量 ​

认证相关 ​

运行环境 ​

Bash 工具配置 ​

其他配置 ​

mTLS 认证配置 ​

Shell 配置 ​

模型配置 ​

提示缓存配置 ​

遥测和报告配置 ​

界面配置 ​

文件读取配置 ​

其他环境变量（补充） ​

使用示例 ​

基础认证配置 ​

海外版使用 API KEY ​

中国版使用 API KEY ​

iOA 账号使用 API KEY ​

使用 OpenRouter 自定义模型 ​

使用 DeepSeek 模型 ​

状态行配置 ​

配置管理命令 ​

基本语法 ​

可用命令 ​

选项 ​

使用示例 ​

查看配置 ​

设置配置 ​

CodeBuddy 可用的工具 ​

使用 hooks 扩展工具 ​

常见配置场景 ​

团队协作配置 ​

安全配置 ​

沙箱安全配置 ​

另见 ​

设置配置

配置文件

完整配置示例

可用设置

权限设置

Bash沙箱设置

设置优先级

配置系统要点

排除敏感文件

子代理配置

插件配置

插件设置

`enabledPlugins`

`extraKnownMarketplaces`

管理插件

环境变量

认证相关

运行环境

Bash 工具配置

其他配置

mTLS 认证配置

Shell 配置

模型配置

提示缓存配置

遥测和报告配置

界面配置

文件读取配置

其他环境变量（补充）

使用示例

基础认证配置

海外版使用 API KEY

中国版使用 API KEY

iOA 账号使用 API KEY

使用 OpenRouter 自定义模型

使用 DeepSeek 模型

状态行配置

配置管理命令

基本语法

可用命令

选项

使用示例

查看配置

设置配置

CodeBuddy 可用的工具

使用 hooks 扩展工具

常见配置场景

团队协作配置

安全配置

沙箱安全配置

另见