# 设置配置

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

## 配置文件

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

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

### 完整配置示例

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

## 可用设置

`settings.json` 支持以下选项：

| 配置键 | 描述 | 示例 |
|:------|:-----|:-----|
| `language` | 首选响应语言，设置后 CodeBuddy Code 将使用指定语言进行回复。留空则自动根据用户输入判断语言 | `"简体中文"` |
| `apiKeyHelper` | 自定义脚本，在 `/bin/sh` 中执行，生成认证值。此值将作为模型请求的 `X-Api-Key` 和 `Authorization: Bearer` 头发送 | `/bin/generate_temp_api_key.sh` |
| `textToImageModel` | 文生图功能使用的模型 ID | `"your-image-model"` |
| `imageToImageModel` | 图生图功能使用的模型 ID | `"your-edit-model"` |
| `cleanupPeriodDays` | 根据最后活动日期本地保留聊天记录的时长(默认:30 天) | `20` |
| `env` | 应用于每个会话的环境变量 | `{"FOO": "bar"}` |
| `includeCoAuthoredBy` | 是否在 git 提交和拉取请求中包含 `co-authored-by CodeBuddy` 署名(默认:`true`） | `false` |
| `permissions` | 权限配置，见下表 | |
| `hooks` | 配置在工具执行前后运行的自定义命令。见 [hooks 文档](hooks.md) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |
| `disableAllHooks` | 禁用所有 [hooks](hooks.md) | `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}` |
| `promptSuggestionEnabled` | 启用 Prompt 建议功能，在 Agent 完成对话后自动预测下一步操作（默认：`true`） | `false` |
| `reasoningEffort` | Reasoning effort 级别配置，控制模型推理的深度。可选值：`low`、`medium`、`high`、`xhigh`。留空时使用产品配置默认值。可通过 `/config` 面板切换，选择 `auto` 等效于清除此设置 | `"high"` |
| `memory` | [Experimental] 记忆功能配置，见[记忆功能配置](#记忆功能配置experimental) | `{"enabled": true}` |

### 权限设置

| 配置键 | 描述 | 示例 |
|:------|:-----|:-----|
| `allow` | [权限规则](iam.md#配置权限)数组,允许工具使用。**注意:** Bash 规则使用前缀匹配,不是正则表达式 | `[ "Bash(git diff:*)" ]` |
| `ask` | [权限规则](iam.md#配置权限)数组,在工具使用时询问确认 | `[ "Bash(git push:*)" ]` |
| `deny` | [权限规则](iam.md#配置权限)数组,拒绝工具使用。用于排除 CodeBuddy Code 访问敏感文件。**注意:** Bash 模式是前缀匹配,可以被绕过(参见 [Bash 权限限制](iam.md#工具特定的权限规则)) | `[ "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"` |

### 记忆功能配置（Experimental）

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

| 配置键 | 描述 | 示例 |
|:------|:-----|:-----|
| `enabled` | 是否启用记忆功能（默认：`false`） | `true` |
| `autoMemoryEnabled` | 是否启用 Auto Memory 功能（默认：`true`）。Auto Memory 允许 CodeBuddy 自动管理跨会话的持久化记忆，存储在 `~/.codebuddy/memories/` 目录 | `true` |
| `typedMemory` | [Experimental] 是否启用 Typed Memory 模式（默认：`false`）。启用后使用 4 种记忆类型（user/feedback/project/reference）+ YAML frontmatter 格式管理记忆 | `true` |
| `teamMemory.enabled` | 是否启用团队记忆模式（默认：`false`）。启用后，项目记忆存储在项目目录下，便于团队共享 | `true` |
| `teamMemory.userId` | 团队用户 ID，用于隔离不同用户的记忆。默认自动获取（git user.name > 系统用户名） | `"yangsubo"` |

**配置示例：**

```json
{
  "memory": {
    "enabled": true,
    "autoMemoryEnabled": true,
    "typedMemory": false,
    "teamMemory": {
      "enabled": true,
      "userId": "yangsubo"
    }
  }
}
```

**记忆存储位置：**

- **个人模式**（默认）：`~/.codebuddy/memories/{project-id}/`
- **团队模式**：`{project}/.codebuddy/memories/@{user-id}/`
- **全局记忆**：`~/.codebuddy/memories/global/`

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

### Bash沙箱设置

配置高级沙箱行为。沙箱将 bash 命令与您的文件系统和网络隔离。详见 [Bash 沙箱文档](bash-sandboxing.md)。

**文件系统和网络限制**通过 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 规则阻止允许路径内的写入

> **注意**：沙箱默认将 CodeBuddy 配置文件（`settings.json`、`settings.local.json`）加入写保护列表，防止沙箱内的命令或工具篡改配置。详见 [Bash 沙箱 - 配置文件保护](bash-sandboxing.md#配置文件保护)。

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

* WebFetch allow 规则允许网络域
* WebFetch deny 规则阻止网络域

### 设置优先级

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

1. **命令行参数**
   * 特定会话的临时覆盖

2. **本地项目设置** (`.codebuddy/settings.local.json`)
   * 个人项目特定设置

3. **共享项目设置** (`.codebuddy/settings.json`)
   * 源代码控制中的团队共享项目设置

4. **用户设置** (`~/.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 助手。详见 [子代理文档](sub-agents.md)。

## 插件配置

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` 时**:

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

**示例**:

```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)
* 添加/删除市场

详见 [插件文档](plugins.md)。

## 环境变量

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

完整的环境变量参考文档请参见 [**环境变量参考**](./env-vars.md)。

### 快速入门

**基础认证配置**：

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

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

**设置代理**：

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

**启用高级功能**：

```bash
# 扩展思考
export MAX_THINKING_TOKENS="10000"

# 自动内存
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

codebuddy -p "你的查询"
```

### 在 settings.json 中配置

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

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

更多配置示例和高级用法，请参见 [**环境变量参考**](./env-vars.md) 和 [**使用示例**](./env-vars.md#使用示例)。

## 状态行配置

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

| 配置键 | 类型 | 描述 |
|--------|------|------|
| `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 命令 | 是 |
| **TaskOutput** | 从正在运行或已完成的后台任务检索输出 | 否 |
| **Edit** | 对特定文件进行有针对性的编辑 | 是 |
| **MultiEdit** | 在单个操作中对单个文件进行多次编辑 | 是 |
| **ExitPlanMode** | 提示用户退出计划模式并开始编码 | 是 |
| **Glob** | 基于模式匹配查找文件 | 否 |
| **Grep** | 在文件内容中搜索模式 | 否 |
| **TaskStop** | 通过 ID 终止正在运行的后台任务 | 否 |
| **LSP** | 与 LSP 服务器交互获取代码智能功能（跳转定义、查找引用、悬停信息等） | 否 |
| **NotebookEdit** | 修改 Jupyter notebook 单元格 | 是 |
| **Read** | 读取文件内容 | 否 |
| **Skill** | 在主对话中执行技能 | 是 |
| **SlashCommand** | 运行[自定义斜杠命令](slash-commands.md#slashcommand-工具） | 是 |
| **Task** | 运行子代理以处理复杂的多步骤任务 | 否 |
| **TaskOutput** | 从正在运行或已完成的后台任务检索输出 | 否 |
| **TaskCreate** | 创建任务以跟踪工作进度 | 否 |
| **TaskUpdate** | 更新任务状态（pending/in_progress/completed） | 否 |
| **TaskList** | 列出当前任务 | 否 |
| **TaskGet** | 获取特定任务详情 | 否 |
| **WebFetch** | 从指定 URL 获取内容 | 是 |
| **WebSearch** | 执行带域过滤的网络搜索 | 是 |
| **Write** | 创建或覆盖文件 | 是 |

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

### 使用 hooks 扩展工具

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

例如，您可以在 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 沙箱](bash-sandboxing.md) - 了解沙箱隔离功能
* [故障排除](troubleshooting.md) - 常见配置问题的解决方案

---

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