WorkBuddy models.json 配置适合在多个模型和项目环境之间切换，比反复点击界面更容易复用和审计。推荐把模型 ID、接口地址和能力参数写入配置，把 API Key 放在环境变量或本地密码管理器中；项目文件只保留环境变量引用，不提交真实密钥。完整的单模型接入流程可先阅读 WorkBuddy 自定义模型教程，同类内容收录在 AI 与效率专题。
本文以 WorkBuddy 官方 models.json 配置说明为配置依据；OpenAI 兼容接口的认证与密钥管理原则可参考 OpenAI API 快速开始。
先理解两层配置
| 配置位置 | 适用范围 | 建议用途 |
|---|---|---|
用户级 ~/.codebuddy/models.json |
当前用户的所有项目 | 个人常用模型和默认网关 |
项目级 .codebuddy/models.json |
单个项目 | 团队约定、项目专用模型或测试网关 |
| 可视化设置 | 当前 WorkBuddy 配置界面 | 临时验证和不需要提交的本地配置 |
相同 id 的项目级定义可能覆盖用户级定义。团队项目中应先约定模型 ID 和能力字段，再决定哪些字段允许项目覆盖。
一、准备目录与环境变量
Windows 用户级路径通常为：
C:\Users\<用户名>\.codebuddy\models.json
macOS/Linux 用户级路径通常为：
~/.codebuddy/models.json
项目级路径为项目目录下的 .codebuddy/models.json。先创建目录，再设置变量：
$env:OPENAI_API_KEY = "sk-your-openai-key"
$env:DEEPSEEK_API_KEY = "sk-your-deepseek-key"
当前终端中的 $env: 变量只对从该终端启动的 WorkBuddy 进程有效。使用 setx 后需要完全退出并重新打开应用，且不要把变量值写入脚本、截图或 Git。
二、编写最小可用配置
先只配置一个文本模型，确认 JSON、路径和变量展开均正常，再增加其他模型：
{
"models": [
{
"id": "your-model-id",
"name": "OpenAI Compatible",
"vendor": "Custom",
"url": "https://gateway.invalid/v1/chat/completions",
"apiKey": "${OPENAI_API_KEY}",
"maxInputTokens": 128000,
"maxOutputTokens": 8192,
"supportsToolCall": false,
"supportsImages": false
}
],
"availableModels": ["your-model-id"]
}
url 应指向完整的 /v1/chat/completions。不要只填写域名或 /v1，也不要把 Anthropic 原生 /v1/messages 填入 OpenAI 兼容模型配置。
三、按环境拆分配置
可以为开发和生产网关使用不同模型 ID，但不要复制真实 Key：
{
"models": [
{
"id": "deepseek-dev",
"name": "DeepSeek Dev",
"vendor": "DeepSeek",
"url": "https://api.deepseek.com/v1/chat/completions",
"apiKey": "${DEEPSEEK_API_KEY}",
"supportsToolCall": true,
"supportsImages": false
},
{
"id": "gateway-readonly",
"name": "Team Readonly Gateway",
"vendor": "Internal Gateway",
"url": "${TEAM_GATEWAY_URL}/v1/chat/completions",
"apiKey": "${TEAM_GATEWAY_KEY}",
"supportsToolCall": false,
"supportsImages": false
}
],
"availableModels": ["deepseek-dev", "gateway-readonly"]
}
生产网关的环境变量应由操作系统凭据、密码管理器或受控启动脚本提供。不要把 Key 直接写入项目级 JSON，也不要把包含 Key 的文件上传到工单、聊天或代码仓库。
需要验证 DeepSeek 官方接口时，可结合 Claude Code 接入 DeepSeek 教程中的基础请求检查方法；先确认 Key、模型 ID 和 Base URL，再排查 WorkBuddy 配置层。
四、验证与回滚
保存后按以下顺序验证：
- 完全退出并重启 WorkBuddy，确认模型出现在选择器；
- 发送“只回复 OK”的最小请求；
- 进行一次连续追问，确认上下文正常；
- 仅对明确支持的模型测试 Tool Call 或图片输入；
- 查看服务端用量记录，确认请求命中了预期模型和环境。
出现问题时，先把项目级文件改名为 models.json.disabled，重启后验证用户级配置。若恢复正常，再逐项比较 URL、模型 ID、环境变量和能力开关；不要直接删除唯一配置文件。
五、常见问题
模型不显示
检查文件路径、JSON 语法、availableModels 是否包含精确 ID，并确认 WorkBuddy 是在变量已存在的环境中启动。
返回 401
确认变量已被进程继承，Key 没有多余空格且仍有效；不要因为 401 就连续创建新 Key。
返回 404 或 Unsupported field
核对完整接口路径和模型 ID；如果是 Claude 原生接口，改用 Anthropic 预设或协议转换网关，不要只切换 URL。
结论
多环境配置的核心是“配置可复用，密钥不落盘，能力逐项验证”。先用最小文本请求确认链路，再按项目需要启用工具调用、图片和长上下文，遇到异常优先回滚到上一个可验证配置。
评论