E2 · 进阶深入

自定义模型配置：chatLanguageModels.json 详解

2026-07-27

WorkBuddy 默认使用腾讯混元大模型，但它的模型层是可插拔的——通过 chatLanguageModels.json 配置文件，你可以接入任何兼容 OpenAI API 格式的大模型，包括 DeepSeek、Qwen、GLM、Llama 以及各类私有部署模型。本文将详解配置文件的每个字段、支持的模型生态、API Key 管理以及多模型切换策略。

📄配置文件位置与格式

配置文件位于 WorkBuddy 用户数据目录：

# macOS/Linux
~/.workbuddy/config/chatLanguageModels.json

# Windows
%USERPROFILE%\.workbuddy\config\chatLanguageModels.json

基本结构：

{
  "default": "hunyuan-pro",
  "models": [
    {
      "id": "hunyuan-pro",
      "name": "混元 Pro",
      "provider": "tencent",
      "apiBase": "https://hunyuan.tencentcloudapi.com/v1",
      "apiKey": "${HUNYUAN_API_KEY}",
      "model": "hunyuan-pro",
      "maxTokens": 32768,
      "contextWindow": 128000,
      "capabilities": ["chat", "code", "vision", "function_call"],
      "pricing": { "input": 0.015, "output": 0.06 },
      "tags": ["default", "recommended"]
    }
  ]
}

🔑字段详解

顶层字段

default：默认模型 ID，对话启动时自动选用，可通过 /model 临时切换
models：模型定义数组，可配置多个模型

模型定义字段

字段	类型	必需	说明
`id`	string	是	模型唯一标识，用于切换和引用
`name`	string	是	显示名称，出现在模型选择器中
`provider`	string	是	提供商标识：tencent/openai/deepseek/ali/zhipu/ollama/custom
`apiBase`	string	是	API 基础 URL，需兼容 OpenAI Chat Completions 格式
`apiKey`	string	是	API Key，支持环境变量引用 `${VAR}`
`model`	string	是	模型实际名称，发送给 API 的 model 参数
`maxTokens`	number	否	单次生成最大 token 数，默认 4096
`contextWindow`	number	否	上下文窗口大小，超出自动截断
`capabilities`	array	否	能力标签：chat/code/vision/function_call/embedding
`pricing`	object	否	价格信息（元/千token），用于成本估算
`tags`	array	否	自定义标签，用于筛选和分组
`extra`	object	否	扩展参数，直接传递给 API 请求

🌐支持的模型与配置示例

DeepSeek

{
  "id": "deepseek-v3",
  "name": "DeepSeek V3",
  "provider": "deepseek",
  "apiBase": "https://api.deepseek.com/v1",
  "apiKey": "${DEEPSEEK_API_KEY}",
  "model": "deepseek-chat",
  "maxTokens": 8192,
  "contextWindow": 64000,
  "capabilities": ["chat", "code", "function_call"],
  "pricing": { "input": 0.001, "output": 0.002 }
}

通义千问（Qwen）

{
  "id": "qwen-max",
  "name": "通义千问 Max",
  "provider": "ali",
  "apiBase": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "${DASHSCOPE_API_KEY}",
  "model": "qwen-max",
  "maxTokens": 8192,
  "contextWindow": 32000,
  "capabilities": ["chat", "code", "vision", "function_call"],
  "pricing": { "input": 0.02, "output": 0.06 }
}

智谱 GLM

{
  "id": "glm-4",
  "name": "GLM-4",
  "provider": "zhipu",
  "apiBase": "https://open.bigmodel.cn/api/paas/v4",
  "apiKey": "${ZHIPU_API_KEY}",
  "model": "glm-4",
  "maxTokens": 4096,
  "contextWindow": 128000,
  "capabilities": ["chat", "code", "vision", "function_call"],
  "pricing": { "input": 0.1, "output": 0.1 }
}

本地模型（Ollama）

{
  "id": "local-llama3",
  "name": "Llama 3 (本地)",
  "provider": "ollama",
  "apiBase": "http://localhost:11434/v1",
  "apiKey": "ollama",
  "model": "llama3",
  "maxTokens": 4096,
  "contextWindow": 8192,
  "capabilities": ["chat", "code"],
  "tags": ["local", "free"]
}

私有部署

{
  "id": "private-model",
  "name": "内部模型",
  "provider": "custom",
  "apiBase": "https://llm.internal.company.com/v1",
  "apiKey": "${INTERNAL_LLM_KEY}",
  "model": "company-v2",
  "maxTokens": 8192,
  "contextWindow": 32000,
  "capabilities": ["chat", "code", "function_call"],
  "extra": {
    "headers": { "X-Tenant": "engineering" },
    "timeout": 120000
  }
}

🔐API Key 管理

环境变量引用（推荐）

在 apiKey 字段中使用 ${ENV_VAR} 语法引用环境变量，避免密钥明文写入配置文件：

# 设置环境变量
# macOS/Linux (.bashrc / .zshrc)
export DEEPSEEK_API_KEY="sk-xxxxxxxx"

# Windows (PowerShell)
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-xxxxxxxx", "User")

WorkBuddy 密钥管理

也可以在 WorkBuddy 设置界面中直接配置 API Key，密钥会加密存储在本地密钥链中：

/settings api-keys
# 交互式配置各模型的 API Key

多环境管理

支持按环境加载不同配置：

chatLanguageModels.json        # 默认
chatLanguageModels.dev.json    # 开发环境
chatLanguageModels.prod.json   # 生产环境

通过环境变量 WORKBUDDY_ENV 控制加载哪个配置。

🔀多模型切换策略

手动切换

# 查看可用模型
/model list

# 切换模型
/model deepseek-v3

# 临时使用（仅当前对话）
/model --temp glm-4

按场景自动路由

WorkBuddy 支持配置路由规则，根据任务类型自动选择最优模型：

{
  "routing": [
    {
      "match": { "tags": ["code"], "complexity": "high" },
      "model": "deepseek-v3",
      "reason": "DeepSeek 代码能力突出，适合复杂编程任务"
    },
    {
      "match": { "tags": ["vision"] },
      "model": "qwen-max",
      "reason": "通义千问视觉理解能力强"
    },
    {
      "match": { "tags": ["chat"], "complexity": "low" },
      "model": "local-llama3",
      "reason": "简单对话使用本地模型，零成本"
    },
    {
      "match": { "tags": ["data"], "sensitivity": "high" },
      "model": "private-model",
      "reason": "敏感数据使用内部模型，确保合规"
    }
  ]
}

降级策略

当首选模型不可用时，自动降级到备选：

{
  "id": "hunyuan-pro",
  "fallback": ["deepseek-v3", "qwen-max", "local-llama3"]
}

WorkBuddy 会按顺序尝试备选模型，确保服务连续性。

📊模型性能对比参考

模型	代码	推理	中文	速度	成本	上下文
混元 Pro	★★★★	★★★★	★★★★★	快	中	128K
DeepSeek V3	★★★★★	★★★★	★★★★	快	低	64K
Qwen Max	★★★★	★★★★	★★★★★	中	中	32K
GLM-4	★★★★	★★★★★	★★★★★	中	高	128K
Llama 3 本地	★★★	★★★	★★	慢	免费	8K

⚠️注意事项

API 兼容性：WorkBuddy 依赖 OpenAI Chat Completions API 格式，非兼容接口需通过中间层转换
Function Call：不是所有模型都支持 function_call，不支持时 WorkBuddy 会降级为纯文本提示方式调用工具
上下文窗口：超出 contextWindow 的对话会自动截断早期消息，可通过 /context strategy 调整截断策略
费用控制：在配置中设置 budget 字段可限制每日/每月 token 消耗上限
流式输出：所有配置的模型默认启用流式输出，如模型不支持需设置 "streaming": false

📚 参考资料

💬 你对 WorkBuddy 有什么疑问？或者已经在用了，有什么心得想分享？欢迎在下方留言讨论！