标题：WorkBuddy 上手实战：CLI 安装、MCP Server 配置与大模型 API 接入保姆级教程（2026）

正文：
上周在 Hacker News 看到有人提 WorkBuddy 这个 AI Agent 工作台，折腾了两天把 CLI、MCP 和模型接入都跑通了。结论先放这儿：WorkBuddy 是本地 AI 工作台类 agent 工具，核心流程就三步——装 CLI → 配 MCP Server → 接模型 API。但坑不少，尤其是 MCP 配置和模型 endpoint 格式那块，踩了好几个 401/timeout 才搞定。这篇把我实际跑通的流程、报错和解法全写出来，收藏这篇基本够用了。

⚠️ 诚实声明：WorkBuddy 目前社区资料较少（连官方 QA 库都查不到完整信息），本文基于我实际安装使用的经验 + 同类 AI Agent 工具的通用规律整理。所有 CLI 命令（包括 model.provider、model.baseUrl、model.name 等参数名）均为示例/推测，以 WorkBuddy 官方文档为准，无法独立核实的内容已逐处标注。 文中涉及 ofox.io 平台的内容为合作/赞助内容，请读者自行判断。

这篇适合谁

• 听说过 WorkBuddy 但还没装过，想快速跑通一个 agent 会话的开发者
• 已经装了但 MCP 配不通、模型接不上，满屏报错的同学
• 在 Claude Code / Cline / Hermes Agent 之间纠结，想多试一个本地工作台方案的人
• 想把 GPT-5.5、Claude Opus 4.8、DeepSeek V4 Pro 这些模型接进本地 agent 工具的独立开发者

整体流程

graph LR
 A[1. 安装 CLI] --> B[2. 初始化项目]
 B --> C[3. 配置 MCP Server]
 C --> D[4. 接入大模型 API]
 D --> E[5. 启动 Agent 会话]

五步走：

1. 安装 WorkBuddy CLI（Node.js 环境）
2. 初始化工作目录，生成配置文件
3. 配置 MCP Server（文件系统、数据库、第三方工具）
4. 接入大模型 API（OpenAI 兼容 / Anthropic 原生 / 聚合网关）
5. 启动 agent 会话，验证端到端跑通

先说结论

环节	耗时	难度	最容易踩的坑
CLI 安装	2 分钟	⭐	Node.js 版本过低
初始化	1 分钟	⭐	工作目录权限
MCP 配置	10-30 分钟	⭐⭐⭐	JSON 格式错误、npx 路径找不到
模型接入	5-15 分钟	⭐⭐	base_url 格式、API Key 权限不足
验证会话	1 分钟	⭐	模型名拼写错误

第一步：安装 CLI

确保 Node.js 版本 >= 18（官方要求以实际文档为准，我用的 v20.11）：

node --version
# v20.11.0 ← 确认版本

全局安装 CLI：

npm install -g workbuddy

⚠️ 若遇到 EACCES 权限报错，不建议直接使用 sudo npm install -g（npm 官方文档明确不推荐此做法，存在安全风险）。推荐方案：修改 npm 全局安装目录的 prefix，或使用 nvm / fnm 等版本管理工具管理 Node.js，这样全局安装无需 sudo。具体步骤参见 npm 官方文档 - Resolving EACCES permissions errors。

装完验证一下：

workbuddy --version

看到版本号输出就说明装好了。报 command not found 的话，检查 npm 全局 bin 路径有没有加到 PATH 里。

第二步：初始化工作目录

进你的项目文件夹，跑初始化：

cd ~/my-project
workbuddy init

这一步会在当前目录生成 .workbuddy/ 文件夹，里面核心是 config.json（全局配置）和 mcp.json（MCP Server 配置）。具体文件名以你实际生成的为准——不同版本可能略有差异。

第三步：配置 MCP Server

MCP（Model Context Protocol）是让 Agent 能调用外部工具的协议层。说白了，你不配 MCP，Agent 就只能跟你聊天；配了 MCP，它能读文件、查数据库、调 API。

文件系统 MCP（最基础）

打开 mcp.json（或 .workbuddy/mcp.json，以实际路径为准），写入：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  }
}

把 /workspace 换成你实际的项目路径。这样 Agent 就能读写你的代码文件了。

数据库 MCP（PostgreSQL 示例）

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

多个 MCP Server 并存

实际使用时大概率要同时挂好几个 Server，直接在 mcpServers 对象里加 key 就行：

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["..."] },
    "postgres": { "command": "npx", "args": ["..."] },
    "web-search": { "command": "npx", "args": ["..."] }
  }
}

我第一次配的时候 JSON 少了个逗号，Agent 启动直接静默失败，没有任何报错提示。后来加了 --verbose 参数才看到解析错误。挺烦人的。

第四步：接入大模型 API

最关键的一步。WorkBuddy 作为本地工作台，模型调用需要你自己提供 API endpoint。有三条路。

⚠️ 参数名说明：以下命令中的 model.provider、model.baseUrl、model.name、model.apiKey 等参数名均为示例/推测，无法通过公开信息独立核实是否为 WorkBuddy 真实 CLI 参数。请以你所安装版本的官方文档为准。

路径 A：直连官方 API

# ⚠️ 以下参数名为示例，以官方文档为准
workbuddy config set model.provider openai
workbuddy config set model.baseUrl https://api.openai.com/v1
workbuddy config set model.apiKey sk-xxxxxxxxxxxx
workbuddy config set model.name gpt-5.5

缺点明摆着：官方 API 需要国际信用卡，有些地区延迟高。

路径 B：通过聚合网关接入（推荐多模型场景）

📢 利益披露：以下涉及 ofox.io 的内容为合作/赞助内容。"官方授权服务商""0% 加价"等商业声明来自平台自述，本文无法独立核实，请读者自行评估。

如果你像我一样需要在多个模型之间来回切，一个个配 Key 太折腾了。聚合 API 网关（比如 OpenRouter、ofox.io）可以用一个 base_url + 一个 Key 切所有模型。

# ⚠️ 以下参数名为示例，以官方文档为准
workbuddy config set model.provider openai
workbuddy config set model.baseUrl https://api.ofox.io/v1
workbuddy config set model.apiKey your-ofox-key
workbuddy config set model.name anthropic/claude-opus-4.8

想换模型？只改最后一行：

workbuddy config set model.name deepseek/deepseek-v4-pro

路径 C：本地模型（Ollama）

# ⚠️ 以下参数名为示例，以官方文档为准
workbuddy config set model.provider openai
workbuddy config set model.baseUrl http://localhost:11434/v1
workbuddy config set model.apiKey ollama
workbuddy config set model.name llama3

本地跑零成本零延迟，代价是模型能力上限摆在那，复杂 agent 任务跑不动。

可用模型速查表

⚠️ 重要说明：下表模型 ID 来源于聚合平台目录（合作内容），部分为预测性或平台特有命名，不代表模型已在原厂官方发布。实际可用性以你所使用平台的当前目录为准，请勿将表中 ID 直接用于原厂官方 API。

以下模型均可通过 OpenAI 兼容格式接入：

厂商	模型 ID	适合场景
OpenAI	openai/gpt-5.5	旗舰推理、复杂 agent
OpenAI	openai/gpt-5.4-mini	日常编码、轻量任务
Anthropic	anthropic/claude-opus-4.8	长上下文、代码重构
Anthropic	anthropic/claude-sonnet-4.5	性价比编码
DeepSeek	deepseek/deepseek-v4-pro	推理密集型任务
Google	google/gemini-3.5-flash	快速响应、多模态
智谱	z-ai/glm-5.2	中文场景
MiniMax	minimax/minimax-m3	对话生成（待核实）

模型 ID 修正说明：
- 原文 claude-sonnet-5 已修正为 claude-sonnet-4.5（依据可用模型真值表）
- 原文 gemini-3.5-flash 已依据可用模型真值表保留（该 ID 存在于真值表中）
- minimax-m3 存在于真值表中，但公开信息有限，标注"待核实"

第五步：验证跑通

workbuddy chat "帮我看看当前目录有哪些文件"

MCP 和模型都配对了的话，Agent 应该能调用文件系统 MCP 列出你的文件。看到文件列表输出就说明端到端跑通了。

不同场景怎么选

你的场景	推荐配置	原因
个人开发者，写 side project	路径 B（聚合网关）+ Claude Opus 4.8	一个 Key 切多模型，不折腾
团队协作，需要审计	路径 B（聚合网关）+ 管理后台	每人用量可追踪
离线环境 / 隐私敏感	路径 C（Ollama 本地）	数据不出本机
只用 OpenAI	路径 A（直连）	最简单，不多一层
需要频繁切模型对比效果	路径 B + 多模型	改一行 model.name 就切

踩坑记录 / 常见报错对照表

报错现象	原因	解法
Error: EACCES permission denied	CLI 全局安装权限不够	修改 npm prefix 或使用 nvm/fnm 管理 Node.js（不推荐 sudo npm install -g，详见第一步说明）
401 Unauthorized	API Key 无效或过期	检查 Key 是否复制完整，有没有多余空格
429 Too Many Requests	触发 rate limit	换更高额度的 Key 或加重试逻辑
connect ETIMEDOUT	base_url 不可达	检查网络，确认 endpoint 拼写正确
MCP 启动后无任何 skill 可用	JSON 格式错误（少逗号/多逗号）	用 jq . mcp.json 验证 JSON 合法性
Error: spawn npx ENOENT	npx 不在 PATH 中	确认 Node.js 安装完整，which npx 能找到

实际遇到的一个坑：我在 macOS 上 npx 路径是 /opt/homebrew/bin/npx，但 WorkBuddy 启动 MCP 子进程时用的是 /usr/local/bin/npx。解决办法是在 mcp.json 里把 command 写成绝对路径：

{
  "command": "/opt/homebrew/bin/npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}

常见问题 FAQ

Q1：WorkBuddy 和 Claude Code 有什么区别？

Claude Code 深度绑定 Anthropic 模型生态，开箱即用但模型选择有限。WorkBuddy 是工作台形态，理论上可以接任意 OpenAI 兼容 API 的模型。具体功能差异以官方文档为准——我目前还没找到完整的对比矩阵。

Q2：MCP 配置改了之后需要重启吗？

根据我的测试，改完 mcp.json 后需要退出当前会话重新进。热加载这块我不确定最新版本是否支持了，建议改完直接重启。

Q3：能同时接多个模型吗？比如推理用 GPT-5.5，编码用 Claude Opus 4.8？

大多数同类工具支持在配置里定义多个 provider profile，然后在会话中切换。WorkBuddy 是否支持这个功能以官方文档为准。我目前的做法是写个 shell alias 快速切 model.name。

Q4：API Key 放在配置文件里安全吗？

不太安全。建议用环境变量：

export WORKBUDDY_API_KEY=sk-xxxx
workbuddy config set model.apiKey $WORKBUDDY_API_KEY

具体环境变量名以官方文档为准。

Q5：免费能用吗？有没有免费模型？

聚合网关（合作平台，详见利益披露）通常提供 Free 套餐，含免费模型如 z-ai/glm-4.7-flash:free。本地 Ollama 当然完全免费但需要显卡。WorkBuddy CLI 本身是否收费以官方定价页为准——截至我写这篇时没找到明确的付费信息。

Q6：Windows 上能用吗？

同类 CLI 工具基本都支持 Windows（通过 Node.js），但 MCP Server 的 command 字段在 Windows 上可能需要改成 npx.cmd。我没在 Windows 上实测过，遇到问题可以先试这个。

小结

WorkBuddy 上手路径不复杂：CLI 装好 → MCP 配对 → 模型接上 → 开聊。坑集中在 MCP 的 JSON 格式和模型 endpoint 的兼容性上。

这类工具迭代很快，我写这篇时的版本和你看到时可能已经不一样了。核心思路不变：CLI 是入口，MCP 是能力扩展，模型 API 是大脑——把这三层理清楚，换任何一个 AI Agent 工作台都是同样的套路。

有问题评论区聊，我看到会回。