配置参考¶
配置文件¶
zhi 将配置存储在平台特定路径的 YAML 文件中：
| 平台 | 路径 |
|---|---|
| macOS | ~/Library/Application Support/zhi/config.yaml |
| Linux | ~/.config/zhi/config.yaml |
| Windows | %APPDATA%\zhi\config.yaml |
配置文件由设置向导（zhi --setup）自动创建，权限设为 0o600（仅所有者可读写）以保护 API 密钥。
配置字段¶
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
api_key |
string | "" |
智谱 API 密钥（所有操作必需） |
default_model |
string | "glm-5" |
交互对话的默认模型 |
skill_model |
string | "glm-4-flash" |
技能执行的默认模型 |
output_dir |
string | "zhi-output" |
file_write 工具的输出目录 |
max_turns |
int | 30 |
每次请求的最大代理循环轮次（范围：1-100） |
log_level |
string | "INFO" |
日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL） |
language |
string | "auto" |
界面语言（auto、en、zh） |
示例 config.yaml¶
api_key: "your-zhipu-api-key-here"
default_model: glm-5
skill_model: glm-4-flash
output_dir: zhi-output
max_turns: 30
log_level: INFO
language: auto
环境变量¶
环境变量覆盖配置文件的值。优先级顺序为：
环境变量 > 配置文件 > 默认值
| 变量 | 对应字段 | 示例 |
|---|---|---|
ZHI_API_KEY |
api_key |
export ZHI_API_KEY="your-key" |
ZHI_DEFAULT_MODEL |
default_model |
export ZHI_DEFAULT_MODEL="glm-4-flash" |
ZHI_OUTPUT_DIR |
output_dir |
export ZHI_OUTPUT_DIR="output" |
ZHI_LOG_LEVEL |
log_level |
export ZHI_LOG_LEVEL="DEBUG" |
ZHI_LANGUAGE |
language |
export ZHI_LANGUAGE="zh" |
NO_COLOR |
（禁用颜色） | export NO_COLOR=1 |
语言检测¶
当 language 设为 auto（默认值）时，zhi 按以下顺序检测界面语言：
ZHI_LANGUAGE环境变量LANG或LC_ALL环境变量（检查zh前缀）- 回退到
en（英文）
语言前导指令
无论界面语言如何设置，所有技能提示都会附加语言前导指令，要求 LLM 以输入文档的语言进行回复。这确保中文文档得到中文回复，英文文档得到英文回复。
设置向导¶
运行设置向导进行首次配置或重新配置：
向导包含三个步骤：
第 1 步：API 密钥¶
粘贴您的智谱 API 密钥（在 open.bigmodel.cn 获取）。
第 2 步：默认设置¶
配置可选项：
| 设置 | 提示 | 默认值 |
|---|---|---|
| 对话模型 | 对话默认模型 [glm-5]： |
glm-5 |
| 技能模型 | 技能默认模型 [glm-4-flash]： |
glm-4-flash |
| 输出目录 | 输出目录 [zhi-output]： |
zhi-output |
| 语言 | 界面语言 [auto]： |
auto |
第 3 步：快速演示¶
可选的示例技能演示（按 Enter 或 y 尝试，n 跳过）。
验证¶
加载时，配置会进行验证：
| 检查项 | 行为 |
|---|---|
| 缺少 API 密钥 | 记录警告，需要 API 的命令将失败 |
max_turns 超出范围（1-100） |
自动修正到有效范围并警告 |
未知 log_level |
重置为 INFO 并警告 |
| 未知配置字段 | 静默忽略 |
| YAML 格式错误 | 回退到默认值并警告 |
文件权限¶
配置文件以 0o600 权限保存（仅所有者可读写）。如果无法设置权限（例如在 Windows 上），会记录警告：
保护您的 API 密钥
配置文件以纯文本存储您的智谱 API 密钥。请确保文件不可被其他用户读取。在共享系统上，使用 ZHI_API_KEY 环境变量是更安全的选择。