# 环境变量参考

CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以在启动前设置，也可以在 [`settings.json`](./settings.md#可用设置) 的 `env` 字段中配置以应用到每个会话。

> **提示**：所有环境变量也可以在 `settings.json` 的 `env` 字段中设置，这样可以自动为每个会话应用，或为整个团队推出配置。

## 认证相关

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_API_KEY` | API 密钥。设置此密钥用于模型接口调用。在非交互模式 (`-p`) 下始终使用此密钥 |
| `CODEBUDDY_AUTH_TOKEN` | CodeBuddy 平台认证令牌，用于所有平台接口调用 |
| `CODEBUDDY_CUSTOM_HEADERS` | 自定义 HTTP 请求头。格式：`Name: Value`，多个请求头用换行符或 `\n` 分隔 |

## API 端点和代理

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_BASE_URL` | 覆盖 API 端点地址，通常与 `CODEBUDDY_API_KEY` 配合使用 |
| `CODEBUDDY_INTERNET_ENVIRONMENT` | 网络环境配置（`internal` 用于中国版，`ioa` 用于 iOA 企业版） |
| `HTTP_PROXY` / `http_proxy` | HTTP 代理服务器地址 |
| `HTTPS_PROXY` / `https_proxy` | HTTPS 代理服务器地址 |
| `NO_PROXY` / `no_proxy` | 绕过代理的域和 IP 列表（逗号分隔，如 `localhost,.example.com`） |

## 模型配置

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_MODEL` | 覆盖默认代理模型 |
| `CODEBUDDY_SMALL_FAST_MODEL` | 后台任务使用的小型快速模型 |
| `CODEBUDDY_BIG_SLOW_MODEL` | 复杂推理任务使用的大型模型 |
| `CODEBUDDY_CODE_SUBAGENT_MODEL` | 子代理使用的模型 |
| `MAX_THINKING_TOKENS` | 启用扩展思考并设置思考过程的 token 预算。默认禁用 |

## Bash 工具配置

| 环境变量 | 说明 |
|---------|------|
| `BASH_DEFAULT_TIMEOUT_MS` | 长时间运行 bash 命令的默认超时（默认：120000） |
| `BASH_MAX_OUTPUT_LENGTH` | bash 输出在内存中保留的最大字符数（默认：30000，上限：150000）。超出部分会被中间截断（保留 head 20% + tail 80%），完整输出会自动保存到磁盘 |
| `BASH_MAX_TIMEOUT_MS` | 模型可为长时间运行的 bash 命令设置的最大超时（默认：600000） |

## 工具输出外部化

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | 工具结果外部化的大小阈值（KB），超过此阈值的非 bash 工具结果会被保存到磁盘并替换为占位符（默认：50）|

> **说明**：Bash 工具的输出外部化由 `BASH_MAX_OUTPUT_LENGTH` 控制，当输出超过该值发生截断时，完整输出自动流式写入磁盘。`CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` 主要影响其他工具（如 MCP 工具）的大输出处理。详见[工具输出外部化](#工具输出外部化机制)章节。

## 工具和功能开关

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_DISABLE_HOT_RELOAD` | 设置为 `1` 禁用热更新系统 |
| `CODEBUDDY_SKIP_BUILTIN_MARKETPLACE` | 设置为 `1` 跳过内置插件市场加载 |
| `CODEBUDDY_IMAGE_GEN_ENABLED` | 设置为 `false` 或 `0` 禁用图片生成功能 |
| `CODEBUDDY_IMAGE_EDIT_ENABLED` | 设置为 `false` 或 `0` 禁用图片编辑功能 |
| `CODEBUDDY_DEFER_TOOL_LOADING` | 设置为 `false` 或 `0` 禁用 MCP 工具延迟加载 |
| `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | 设置为 `true` 或 `1` 显示所有延迟工具的完整描述 |
| `CODEBUDDY_DISABLE_CRON` | 设置为 `1` 禁用计划任务 |

## 上下文和内存

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_AUTOCOMPACT_PCT_OVERRIDE` | 设置自动压缩触发的上下文容量百分比（1-100）。默认由产品配置决定（通常 70-92%）。使用更低的值（如 `50`）来更早压缩 |
| `CODEBUDDY_DISABLE_AUTO_MEMORY` | 设置为 `1` 禁用自动内存，设置为 `0` 启用 |
| `CODEBUDDY_MEMORY_ENABLED` | 设置为 `true` 或 `1` 启用记忆功能 |
| `CODEBUDDY_TYPED_MEMORY_ENABLED` | 设置为 `true` 或 `1` 启用分类记忆模式 |
| `CODEBUDDY_TEAM_MEMORY_ENABLED` | 设置为 `true` 或 `1` 启用团队记忆模式 |
| `CODEBUDDY_USER_ID` | 团队记忆模式下的用户 ID |

## MCP (Model Context Protocol)

| 环境变量 | 说明 |
|---------|------|
| `MCP_TIMEOUT` | MCP 服务器连接的超时时间（毫秒） |
| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间（毫秒） |
| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大 token 数（默认：20000） |

## 性能和输出

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出 token 数 |
| `CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆盖文件读取的默认 token 限制（默认：20000） |
| `CODEBUDDY_STREAM_TIMEOUT_MS` | 流式响应中两个数据块之间允许的最大静默时间（毫秒）（默认：120000） |
| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | 等待第一个模型输出的最大时间（毫秒）（默认：120000） |

## 文件系统和配置

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_CONFIG_DIR` | 自定义 CodeBuddy Code 存储配置和数据文件的位置 |
| `CODEBUDDY_CODE_DEBUG_LOGS_DIR` | 调试日志目录 |
| `CODEBUDDY_SANDBOX_IMAGE` | 容器沙箱镜像（默认：`node:20-alpine`） |
| `USE_BUILTIN_RIPGREP` | 设置为 `0` 使用系统安装的 `rg` 而不是 CodeBuddy Code 附带的 `rg` |

## Shell 配置

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_CODE_SHELL` | 覆盖自动 shell 检测。支持的值：`bash`、`zsh`、`sh`、`powershell`、`cmd` |
| `CODEBUDDY_CODE_SHELL_PREFIX` | 包装所有 shell 命令的命令前缀（如用于日志或审计） |
| `CODEBUDDY_CODE_GIT_BASH_PATH` | Windows 下显式指定 Git Bash 路径 |
| `CODEBUDDY_ENV_FILE` | 在执行每个 shell 命令前自动 source 的环境文件路径 |

## UI 和交互

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 禁用自动终端标题更新 |
| `CODEBUDDY_PROMPT_SUGGESTION_DISABLED` | 设置为 `true` 禁用提示建议 |
| `IS_DEMO` | 设置为 `true` 启用演示模式：隐藏邮箱和组织 |

## 安全和认证

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

## 遥测和报告

| 环境变量 | 说明 |
|---------|------|
| `DISABLE_TELEMETRY` | 设置为 `1` 禁用遥测 |
| `DISABLE_ERROR_REPORTING` | 设置为 `1` 禁用错误报告 |
| `DISABLE_AUTOUPDATER` | 设置为 `1` 禁用自动更新 |
| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 禁用 `/feedback` 命令 |

## 任务和后台工作

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 禁用所有后台任务功能 |

## Agent 执行控制

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_CODE_MAX_TURNS` | 主 Agent 的最大执行轮次。优先级：CLI `--max-turns` > 此环境变量 > 默认值 (500) |
| `CODEBUDDY_CODE_SUBAGENT_MAX_TURNS` | 子 Agent 的最大执行轮次。优先级：CLI `--max-turns` > 此环境变量 > 模型动态传入的 `max_turns` > 默认值 (500) |

## Gateway 和远程访问

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_GATEWAY_AUTH` | Gateway 认证模式（`password` 或 `none`） |
| `CODEBUDDY_GATEWAY_PASSWORD` | Gateway 访问密码 |
| `CODEBUDDY_GATEWAY_FORCE_TUNNEL` | 设置为 `1` 强制使用 tunnel 模式 |
| `SERVER__HOST` | `--serve` 模式监听地址（默认：`127.0.0.1`） |
| `SERVER__PORT` | `--serve` 模式监听端口 |

## 企业微信集成

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN` | 企业微信客服 Token |
| `CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY` | 企业微信客服加密密钥 |
| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID` | 企业微信客服企业 ID |
| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET` | 企业微信客服企业密钥 |
| `CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME` | 企业微信客服账户名 |
| `CODEBUDDY_GATEWAY_WECOM_TOKEN` | 企业微信 Token |
| `CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY` | 企业微信加密密钥 |
| `CODEBUDDY_GATEWAY_WECOM_CORP_ID` | 企业微信企业 ID |
| `CODEBUDDY_GATEWAY_WECOM_CORP_SECRET` | 企业微信企业密钥 |
| `CODEBUDDY_GATEWAY_WECOM_AGENT_ID` | 企业微信应用 ID |

## 调试和诊断

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_DEBUG` | 设置为 `1` 启用调试模式 |
| `CODEBUDDY_DEBUG_REQUEST` | 设置为 `1` 启用请求调试 |
| `CODEBUDDY_STARTUP_PROFILE` | 设置为 `1` 启用启动性能分析 |

## 其他

| 环境变量 | 说明 |
|---------|------|
| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 斜杠命令工具元数据的最大字符数（默认：15000） |
| `CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS` | 刷新凭证的间隔（毫秒）（默认：300000） |

## 使用示例

### 基础认证配置

```bash
# 设置 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
```

### 使用第三方模型服务

```bash
# 使用自定义 API 端点
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_BASE_URL="https://api.example.com/v1"
codebuddy --model your-model-name
```

### 中国版配置

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

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

# 启动 CodeBuddy
codebuddy
```

### 启用高级功能

```bash
# 启用自动内存
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

# 启用扩展思考
export MAX_THINKING_TOKENS="10000"

# 非交互模式运行
codebuddy -p -y "你的查询"
```

### 调试和性能分析

```bash
# 启用调试模式
export CODEBUDDY_DEBUG="1"

# 启用启动性能分析
export CODEBUDDY_STARTUP_PROFILE="1"

# 启动 CodeBuddy
codebuddy
```

## 在 settings.json 中配置

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

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

## 工具输出外部化机制

当工具执行产生的输出超过阈值时，CodeBuddy Code 会自动将完整输出保存到磁盘，给模型只发送截断后的内容和文件路径指针，模型可按需读取完整内容。

### 数据流

```
Shell 输出
  ├─→ OutputSpiller（完整输出流式写入磁盘）
  └─→ TruncateBuffer（内存中保留 head + tail，约 30KB）
                          ↓
                  检测到截断 → 生成 placeholder（~2KB preview + 文件路径）
                          ↓
                  模型收到 placeholder，可通过 Read 工具按需读取完整文件
```

### 各阶段数据大小（以 1.3MB 输出为例）

| 阶段 | 内容 | 大小 |
|------|------|------|
| 磁盘文件（OutputSpiller） | 完整原始输出 | 1,355,099 bytes |
| 内存缓冲（TruncateBuffer） | head 6KB + tail 24KB | ~30KB |
| 发给模型（placeholder） | 文件路径 + preview | ~2KB |

### 存储目录

工具输出文件存储在项目数据目录中：

```
~/.codebuddy/projects/{projectDir}/
  └── {sessionId}/
      ├── tool-results/                          ← 主 session 的工具结果
      │   ├── {callId}.txt
      │   └── ...
      └── subagents/                             ← 子代理数据
          ├── agent-{agentId}.jsonl              ← 子代理对话历史
          └── agent-{agentId}/
              └── tool-results/                  ← 子代理的工具结果
                  ├── {callId}.txt
                  └── ...
```

### 相关环境变量

| 环境变量 | 影响范围 | 默认值 |
|---------|---------|--------|
| `BASH_MAX_OUTPUT_LENGTH` | Bash 工具内存保留量，超出则截断并触发磁盘外部化 | 30000 |
| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | 非 bash 工具（如 MCP）在 session 层的外部化阈值 | 50 |

## 另见

- [Settings](./settings.md) - 在 `settings.json` 中配置环境变量和其他设置
- [CLI Reference](./cli-reference.md) - 命令行参数完整列表
- [MCP Setup](./mcp.md) - MCP 服务器配置
- [子代理](./sub-agents.md) - 子代理存储目录说明
