跳转到内容
Chord

环境变量

Chord 读取的所有环境变量，按用途分组，附优先级规则。

优先级

路径与 API 基础地址按以下顺序解析最终值：

  1. CLI flag（如 --state-dir /tmp/chord-state）
  2. Chord 自有环境变量（如 CHORD_STATE_DIR）
  3. config.yaml 中的 paths: 字段（如 paths.state_dir）
  4. XDG 标准环境变量（如 XDG_STATE_HOME）
  5. 内置默认值（如 ~/.local/state/chord）

auth.yaml 中的凭据变量仅在标量以 $ 或 ${...} 开头时展开。详见 配置与认证 — auth.yaml 中的环境变量。

路径覆盖

变量作用未设置时的默认
CHORD_CONFIG_HOME配置主目录（provider 配置、agent、skill、自定义命令、auth.yaml）已有 $XDG_CONFIG_HOME 时取 $XDG_CONFIG_HOME/chord，否则 ~/.config/chord
CHORD_STATE_DIR持久运行时状态根目录（sessions、exports、logs、projects、worktrees）已有 $XDG_STATE_HOME 时取 $XDG_STATE_HOME/chord，否则 ~/.local/state/chord
CHORD_CACHE_DIR可重建缓存根已有 $XDG_CACHE_HOME 时取 $XDG_CACHE_HOME/chord，否则 ~/.cache/chord
CHORD_SESSIONS_DIR仅覆盖 sessions 根<state-dir>/sessions
CHORD_LOGS_DIR仅覆盖 logs 目录<state-dir>/logs
XDG_CONFIG_HOMEXDG 标准配置根~/.config
XDG_STATE_HOMEXDG 标准 state 根~/.local/state
XDG_CACHE_HOMEXDG 标准 cache 根~/.cache

具体目录布局见 目录与路径。

auth.yaml 引用的凭据

Chord 不直接从环境读取 provider key——它读 auth.yaml，展开其中的 $VAR / ${VAR} 占位符。惯例是用 <PROVIDER>_API_KEY 风格命名，但变量名随意。

~/.config/chord/auth.yaml
anthropic:
  - "$ANTHROPIC_API_KEY"
openai:
  - "${OPENAI_API_KEY}"
gemini:
  - "$GEMINI_API_KEY"
my-gateway:
  - "$MY_GATEWAY_KEY"        # 任意变量名都可以
常见命名作用
ANTHROPIC_API_KEY配 anthropic provider 时在 auth.yaml 引用
OPENAI_API_KEYopenai 或 openai-compatible provider
GEMINI_API_KEYGoogle Gemini provider
任意自定义 *_API_KEY对应 auth.yaml 中绑的那个 provider 名

注意事项：

  • 未设置的变量会展开为空字符串并被过滤；除非 YAML 值本身就是字面空字符串。
  • 该展开仅作用于 auth.yaml，不会作用于 config.yaml 的所有字段。

网络代理

所在网络无法直连 Anthropic、OpenAI、Google 等官方 API 时，需要给 Chord 配代理，否则 provider 请求会超时或连接失败。可用标准环境变量，也可在 config.yaml 中配全局或 provider 级 proxy。

Chord 使用 Go 标准的 http.ProxyFromEnvironment 解析出站 HTTP 代理，标准变量直接生效：

变量用途
HTTP_PROXYhttp:// 请求的代理
HTTPS_PROXYhttps:// 请求的代理
NO_PROXY用逗号分隔的不走代理的主机模式
http_proxy / https_proxy / no_proxy小写变体也会识别

只想给某个工具单独设代理（如只让 WebFetch 走 SOCKS5），见 配置与认证 — WebFetch。

终端检测（只读）

下面是标准变量，Chord 只读不写，通常不需主动设置。

变量用途
TERM识别终端类型，做能力协商
TERM_PROGRAM识别终端模拟器（iTerm2、WezTerm、Ghostty 等），选择图片协议与通知协议
TERM_PROGRAM_VERSION与 TERM_PROGRAM 配合使用
TMUX检测 Chord 跑在 tmux 内
CMUX_SOCKET / CMUX_SOCKET_PATH检测 Chord 跑在 cmux 内；影响图片协议管线
NO_COLOR任意非空值会禁用启动时 stderr 的 ANSI 颜色
USER / USERNAME部分诊断输出会用到

终端能力覆盖（图片）

以下变量仅在排查或强制覆盖自动检测时使用：

变量用途
CHORD_IMAGE_BACKEND强制图片后端：kitty / iterm2 / none / auto（默认自动检测）
CHORD_IMAGE_INLINE强制是否启用 inline 图片：1 / 0
CHORD_IMAGE_FULLSCREEN强制是否启用全屏图片查看：1 / 0

说明：

  • tmux / zellij 内默认会保守禁用图片预览；这些变量主要用于调试或已知兼容环境下的手动覆盖。
  • WezTerm 当前会自动走 iTerm2 图片协议；Ghostty / kitty 自动走 Kitty graphics。

开发与调试

变量用途
CHORD_HOOK_DEBUG设为 1 时记录每次 hook 调用（输入/输出/退出码/耗时）。输出较多，只在排查 hook 行为时用。
CHORD_PPROF_PORT设为端口号（如 6060）会在 127.0.0.1 暴露 Go pprof。默认关闭。

这些用于开发、排障、上报 bug，不建议日常常开。

关于 CHORD_API_BASE

chord --help 中 --api-base flag 描述提到了 CHORD_API_BASE。flag 本身生效，但当前构建并未真正从环境读取 CHORD_API_BASE——只有 --api-base CLI flag 生效（或直接给每个 provider 配 api_url）。需要全局覆盖 API base 时，建议在 config.yaml 各 provider 上单独设 api_url。

相关