环境变量参考 ​

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

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

认证相关 ​

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

API 端点和代理 ​

环境变量说明
CODEBUDDY_BASE_URL覆盖 API 端点地址，通常与 CODEBUDDY_API_KEY 配合使用
CODEBUDDY_INTERNET_ENVIRONMENT网络环境配置（internal 用于中国版，ioa 用于 iOA 企业版）
HTTP_PROXY / http_proxyHTTP 代理服务器地址
HTTPS_PROXY / https_proxyHTTPS 代理服务器地址
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_LENGTHbash 输出在内存中保留的最大字符数（默认：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_TIMEOUTMCP 服务器连接的超时时间（毫秒）
MCP_TOOL_TIMEOUTMCP 工具执行的超时时间（毫秒）
MAX_MCP_OUTPUT_TOKENSMCP 工具响应中允许的最大 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_PATHWindows 下显式指定 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_CERTmTLS 客户端证书文件路径 ⚠️ 暂未支持
CODEBUDDY_CODE_CLIENT_KEYmTLS 客户端私钥文件路径 ⚠️ 暂未支持
CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASEmTLS 加密私钥的密码（可选）⚠️ 暂未支持

遥测和报告 ​

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

任务和后台工作 ​

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

Gateway 和远程访问 ​

环境变量说明
CODEBUDDY_GATEWAY_AUTHGateway 认证模式（password 或 none）
CODEBUDDY_GATEWAY_PASSWORDGateway 访问密码
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_LENGTHBash 工具内存保留量，超出则截断并触发磁盘外部化30000
CODEBUDDY_TOOL_RESULT_THRESHOLD_KB非 bash 工具（如 MCP）在 session 层的外部化阈值50

另见 ​