WorkBuddy 安装配置全攻略：模型接入、规则设定与报错排查实战

1. 为什么我花了三天才把 WorkBuddy 跑起来

先说结论：WorkBuddy 这类 AI 工作台，安装本身十分钟就能搞定，真正耗时间的是模型接入配置和权限规则设定这两块。我前后折腾了三天，踩的坑基本都集中在models.json的字段格式、API Key 的传递方式，以及"给 WorkBuddy 定几条规则让它对所有任务生效"这个看似简单实则容易翻车的地方。

这篇内容适合三类人看：一是刚听说 WorkBuddy、想搞清楚它和 CodeBuddy 到底差在哪的人；二是已经装好了但卡在模型配置、一直报 401 或 400 的人；三是想把 WorkBuddy 当成日常 AI Agent 中台来用、需要一套稳定规则体系的人。我会把安装、模型接入、规则设定、缓存目录迁移、常见报错排查这几件事按我实际操作的顺序讲清楚，中间穿插一些官方文档里不会写、但实际用起来很关键的经验。

需要提前说明的是，WorkBuddy 本身是一个AI Agent 工作台，它的定位不是单纯的聊天窗口，而是把多个模型、多个技能（Skill）、多套规则编排在一起，让 Agent 能持续执行任务。理解这一点很重要，因为后面所有的配置逻辑，都是围绕"让 Agent 稳定干活"这个目标展开的。如果你只是想要一个问答工具，那其实用不上它；但如果你想让 AI 帮你处理文件、调用接口、按固定流程跑任务，那 WorkBuddy 这套东西就值得花时间研究。

2. WorkBuddy 和 CodeBuddy 到底差在哪，别装错了

2.1 两者的定位差异

很多人第一次接触会懵：WorkBuddy 和 CodeBuddy 名字这么像，是不是一个东西的两个版本？不是。我一开始也以为只是换了个皮，实际用下来发现两者的重心完全不同。

CodeBuddy 的重心在代码场景，它的交互逻辑、上下文管理、技能设计都是围绕"写代码、改代码、跑代码"来的。而 WorkBuddy 的重心在通用工作任务，它更像一个可以挂载各种能力的 Agent 运行环境，代码只是它能处理的其中一类任务。举个直观的例子：你让 CodeBuddy 去整理一份 Excel 并生成图表，它能做，但过程会比较别扭；而 WorkBuddy 处理这类任务时，因为它的技能体系本身就更偏向通用办公和自动化流程，所以顺畅得多。

2.2 选型时我建议这样判断

我自己的做法是两个都装，CodeBuddy 处理纯代码任务，WorkBuddy 处理需要调用外部 API、需要多步骤编排的任务。这样分工之后，效率比只用一个高出不少。当然如果你只想装一个，那就看你的任务里"代码"占比高不高，高就 CodeBuddy，不高就 WorkBuddy。

2.3 国际版和国内版的区别

热词里出现了"workbuddy 国际版"，这里也说一下。国际版和国内版在模型接入方式上有差异，国际版通常默认对接的是海外的模型服务，国内版则更偏向国内可用的模型。这个差异直接影响你后面models.json怎么写。我建议是：如果你主要用国内的模型服务（比如智谱、讯飞星火、DeepSeek 这些），那就用国内版，配置起来省事；如果你有 OpenRouter 这类海外聚合服务的 Key，那国际版会更顺手。不要两个版本混着配，容易在 API 地址和鉴权方式上打架。

3. 安装环节：十分钟能搞定的事，别被细节绊住

3.1 安装前的环境确认

WorkBuddy 支持 Windows、macOS 和 Linux。我三个平台都试过，安装过程本身没什么坑，但有几个前置条件容易被忽略。

第一是系统缓存目录的磁盘空间。WorkBuddy 运行过程中会产生不少缓存，尤其是你挂载了多个模型、频繁跑任务的时候。默认缓存目录在系统盘，如果你系统盘空间紧张，装之前就得先想好要不要迁移（后面第 6 节会讲怎么改到 D 盘）。

第二是网络环境。这里说的不是别的，就是正常的网络连通性——你要接入的模型服务地址得能正常访问。我遇到过有人装完了发现所有模型都调不通，最后查出来是本地网络策略把出站请求拦了。这个排查起来很快，但不知道的话会以为是软件问题。

第三是权限。Linux 下如果用普通用户安装，注意安装目录要有写权限，否则后面写配置文件会失败。Windows 下建议不要装在Program Files里，因为那个目录的写权限管理比较严格，配置文件改起来麻烦。

3.2 安装步骤的实际操作

安装本身按官方引导走就行，我重点说几个引导里不会强调但实际要注意的点：

1. 安装路径尽量选一个没有中文、没有空格的目录。这个不是 WorkBuddy 独有的问题，很多工具在处理路径时对中文和空格的支持都不够稳，能避就避。
2. 安装完成后先别急着配模型，先启动一次，看看主界面能不能正常打开、有没有报错。这一步是确认基础环境没问题，把"安装问题"和"配置问题"分开排查。
3. 首次启动会让你选工作目录，这个目录建议单独建一个，不要直接用桌面或者文档根目录。因为 Agent 执行任务时会在这个目录里读写文件，单独建目录方便你管理和清理。

3.3 安装后第一件事：确认版本和更新通道

装完之后我建议先看一眼版本号，然后确认更新通道。WorkBuddy 这类工具迭代比较快，不同版本之间models.json的字段可能有细微差异。我踩过一次坑：照着旧版本的教程写配置，结果新版本里某个字段名改了，一直报错，查了半天才发现是版本不匹配。

提示：装完后先记录当前版本号，后面遇到配置报错时，第一件事就是确认你参考的教程是不是对应这个版本。

4. models.json 配置：90% 的报错都出在这里

4.1 这个文件到底管什么

models.json是 WorkBuddy 的模型接入配置文件，它决定了你的工作台能用哪些模型、每个模型怎么调用、用什么 Key 鉴权。可以说这个文件写对了，WorkBuddy 就活了；写错了，就是各种 401、400 报错轮番上。

它的核心结构其实不复杂，就是一组模型定义，每个定义里包含模型名称、服务地址、API Key、模型标识这几样。但问题在于，不同模型服务商对这几个字段的要求不一样，有的要求地址带特定路径，有的要求模型标识用特定写法，有的对 Key 的格式有要求。这就是为什么同样的配置模板，别人能用你不能用。

4.2 配置字段逐个拆解

我按实际配置时最常打交道的几个字段来说：

• 模型显示名称：这个随便起，只要你自己认得出来就行，不影响调用。
• 服务地址（base URL）：这是最容易出错的地方。不同服务商的地址格式差异很大，有的要带/v1，有的不带，有的路径还不一样。写错了通常报的是连接类错误或者 404。
• API Key：鉴权用的，格式通常是sk-开头的一串字符。这个字段写错或者过期，报的就是 401。
• 模型标识（model name）：这个必须用服务商规定的准确名称，不能自己编。写错了通常报的是模型不存在或者 400。

我建议配置的时候，一个模型一个模型地加，加完一个就测一个，别一次性全写完再测。因为一旦全写完报错，你根本不知道是哪个模型的问题。

4.3 一个可参考的配置结构

下面这个结构是我实际在用的，字段名以你当前版本为准，逻辑是通用的：

{ "models": [ { "name": "我的主力模型", "baseUrl": "https://你的服务商地址/v1", "apiKey": "sk-你的key", "model": "服务商规定的模型标识" } ] }

这里要强调一点：baseUrl末尾要不要带斜杠、要不要带/v1，完全取决于服务商。我见过有人因为多了一个斜杠导致所有请求 404，也见过因为少了一个路径段导致 401。这个没有通用答案，只能对着服务商的文档来。

4.4 多模型配置的排序策略

如果你配了多个模型，WorkBuddy 通常会有一个默认模型的概念。我的建议是把最稳定、响应最快的那个设为默认，把能力更强但偶尔抽风的放在后面备用。因为 Agent 执行任务时如果默认模型不稳定，整个任务链都会受影响。

另外，多模型配置时注意 Key 的管理。不要把同一个 Key 到处复用，也不要把 Key 直接写在会分享出去的文件里。我一般会把 Key 单独管理，配置文件里只做引用，这样万一配置文件泄露了，损失可控。

5. 那些让人抓狂的报错，逐个拆给你看

5.1 401 报错：Key 的问题占九成

热词里反复出现unexpected status 401 unauthorized: incorrect api key provided，这个报错我太熟了。它的字面意思是"提供的 API Key 不正确"，但实际原因有好几种：

我遇到最多的是复制 Key 时带了空格或者换行。这个特别隐蔽，因为肉眼看不出区别。解决办法是把 Key 粘贴到纯文本编辑器里看一眼，确认是干净的一行。

还有一种情况是 Key 和地址不匹配。比如你拿 A 服务商的 Key 去配 B 服务商的地址，那必然 401。这个听起来很蠢，但实际配置多个模型时真的容易搞混，尤其是 Key 长得都差不多的时候。

5.2 400 报错：上下文超限和模型配置问题

热词里有api error: 400 this model's maximum context length is 1048576 tokens，这个报错的意思是你发给模型的上下文超过了它的上限。1048576 这个数字看着很大，但如果你把整个项目文件都塞进去，或者对话历史很长，是真的会超的。

处理办法有几个：一是精简输入，只发必要的内容；二是开启上下文压缩或者分段处理；三是换一个上下文窗口更大的模型。我一般是用第一种，因为最直接。

还有一种 400 是this organization has been disabled，这个是账号层面的问题，通常是服务商那边把你的组织禁用了，这个只能去服务商后台处理，本地怎么改配置都没用。

5.3 排查报错的通用思路

我总结了一个排查顺序，基本能覆盖大部分情况：

1. 先看报错类型：401 是鉴权问题，400 是请求问题，404 是地址问题，超时是网络问题。类型决定了排查方向。
2. 再看是哪个模型报的：多模型配置时，先确认是单个模型的问题还是全部模型的问题。单个就是那个模型的配置问题，全部就是公共配置或者网络问题。
3. 然后核对配置：把出问题的模型配置和服务商文档逐字段对一遍，重点看 baseUrl 和 model 标识。
4. 最后测连通性：用一个最简单的请求测一下，排除是复杂请求导致的问题。

这个顺序的好处是，你不用一上来就怀疑所有东西，按类型缩小范围，效率高很多。

6. 缓存目录迁移：系统盘告急的救命操作

6.1 为什么要迁移

WorkBuddy 跑一段时间后，缓存目录会越来越大。如果你系统盘本来就不宽裕，很快就会收到磁盘空间不足的警告。热词里有人问"workbuddy 系统缓存目录能改到 d 盘吗"，答案是能，而且操作不复杂。

6.2 迁移的实际步骤

迁移的核心思路是：先把缓存目录整个复制到新位置，再修改配置指向新位置，最后确认没问题再删旧的。顺序不能反，反了容易丢数据。

1. 找到当前的缓存目录。这个通常在设置里能看到，或者在安装目录下的某个子目录里。
2. 完全退出 WorkBuddy，确保没有进程在占用缓存文件。
3. 把整个缓存目录复制到目标位置，比如D:\WorkBuddyCache。
4. 修改配置文件里的缓存路径指向新位置。
5. 重新启动 WorkBuddy，确认能正常读取缓存、任务能正常跑。
6. 确认无误后，再删除旧位置的缓存。

注意：第 2 步一定要做。我有一次没完全退出就复制，结果复制出来的缓存是损坏的，启动后各种异常，最后只能重装。

6.3 迁移后的验证

迁移完不要只看能不能启动，要实际跑一个任务，确认缓存读写正常。因为有些工具的缓存路径是分好几处的，你改了一处，另一处没改，启动时看不出来，跑任务时才报错。我一般会跑一个会产生明显缓存的任务，然后去新目录看有没有生成文件，这样最直观。

7. 给 WorkBuddy 定规则：让所有任务都听话

7.1 规则体系为什么重要

热词里有一句"给 workbuddy 定几条规则，后续对所有任务都生效"，这个需求非常真实。WorkBuddy 作为 Agent 工作台，如果没有规则约束，它每次执行任务的行为可能都不一致。规则的作用就是把"你希望它怎么干活"固化下来，让后续所有任务都遵循同一套标准。

我一开始没重视这个，结果发现同一个任务，今天跑和明天跑结果风格不一样，有时候啰嗦有时候简略，很影响使用体验。后来定了几条规则，稳定性立刻上来了。

7.2 我实际在用的几条规则

规则不用多，关键是清晰、可执行。我目前用的几条：

• 输出语言和风格：统一用中文，技术术语保留英文原文，不堆砌客套话。
• 文件操作规范：所有生成的文件统一放在指定目录，命名带日期前缀，方便追溯。
• 任务执行原则：遇到不确定的信息先问，不要自己编；涉及删除、覆盖的操作必须先确认。
• 错误处理：报错时先给出可能原因，再给解决方案，不要只丢一个错误码。

这几条看起来简单，但实际用起来效果很明显。尤其是"遇到不确定先问"这条，直接减少了很多它自己瞎编的情况。

7.3 规则生效范围的坑

这里有个坑要提醒：规则的生效范围取决于你写在哪里。有的规则是全局的，对所有任务生效；有的规则只在特定技能或特定会话里生效。如果你发现规则没起作用，先确认它写的位置对不对。

我的做法是把通用规则写在全局配置里，把特定任务的规则写在对应技能里。这样既保证了通用行为一致，又保留了灵活性。

8. Skill 和 API 调用：WorkBuddy 真正好用的地方

8.1 Skill 是什么，怎么用

Skill 可以理解为 WorkBuddy 的"技能包"，每个 Skill 封装了一类能力。比如文件处理、数据查询、接口调用，都可以做成 Skill。它的价值在于把重复的操作流程固化下来，下次直接调用，不用重新描述一遍。

我常用的几个 Skill 都是自己按实际需求配的。配置 Skill 的关键是把输入输出定义清楚，输入是什么格式、输出是什么格式、中间怎么处理，定义得越清楚，用起来越稳。

8.2 API 调用的实际经验

WorkBuddy 调用外部 API 是很常见的用法，热词里出现了 DeepSeek API、OpenRouter API Key、智谱 API、讯飞星火 API、MinerU API 等等，说明大家在这块的实践很多。我分享几个通用经验：

第一，API Key 的管理要独立。不要把 Key 硬编码在会分享的配置里，用环境变量或者单独的密钥文件管理。

第二，调用要有超时和重试。外部 API 不稳定是常态，没有超时和重试机制的话，一个请求卡住整个任务就停了。

第三，返回结果要校验。不要假设 API 一定返回你期望的格式，加一层校验，格式不对就报错，比默默用错误数据强。

8.3 从 0 到 1 搭一个 Agent 的思路

热词里有"从 0 到 1 搭建 ai agent"，我简单说下思路。搭 Agent 的核心不是技术，是把任务拆解清楚。你要先想明白：这个 Agent 要解决什么问题、输入是什么、输出是什么、中间需要哪些步骤、每步用什么能力。

想清楚这些之后，再对应到 WorkBuddy 里：哪些步骤用模型、哪些步骤用 Skill、哪些步骤调 API。拆得越细，搭起来越顺。我见过很多人一上来就写配置，结果写到一半发现流程没想清楚，只能推倒重来。

9. 生成网站发布和 Linux 部署的实操要点

9.1 用 WorkBuddy 生成网站并发布

热词里有"workbuddy 怎么生成网站发布"，这个我实际跑过。流程大致是：让 WorkBuddy 生成静态页面文件，然后你把文件部署到托管服务上。这里的关键是生成的文件结构要规范，入口文件、资源文件、样式文件分清楚，不然部署上去会各种 404。

我的经验是，生成完之后先在本地用浏览器打开确认没问题，再部署。因为部署上去之后再排查，成本高很多。

9.2 Linux 下的部署注意点

Linux 下跑 WorkBuddy，除了前面说的权限问题，还要注意进程管理。如果你希望它长期运行，建议用系统自带的服务管理方式把它管起来，这样开机自启、异常重启都能自动处理。直接前台跑的话，终端一关就停了。

另外 Linux 下的路径都是正斜杠，配置里写路径的时候注意别用 Windows 的反斜杠，这个错误很隐蔽，报错信息也不直观。

10. 一些零散但有用的经验

最后分享几个零散的点，都是实际用下来觉得值得说的。

关于模型选择：不要迷信参数最大的模型。实际用下来，响应速度和稳定性往往比单纯的参数规模更重要。我主力用的模型不是最强的那个，但是最稳的那个，综合体验反而更好。

关于配置备份：models.json和规则配置这些，改之前先备份。我有一次改配置改崩了，又没备份，只能从头配，浪费了大半天。现在养成习惯，改之前先复制一份。

关于版本更新：更新前先看更新说明，确认配置格式有没有变化。如果变化大，先备份配置再更新，出问题能回滚。

关于学习路径：WorkBuddy 这类工具，看教程只能入门，真正会用是靠实际跑任务跑出来的。建议找一个真实的小需求，从头到尾用 WorkBuddy 做一遍，中间遇到的所有问题都自己解决一遍，这一轮下来比看十篇教程都管用。

我在实际使用中最大的体会是：WorkBuddy 这类 AI 工作台，配置阶段的投入是值得的。前期把模型、规则、Skill 都配好，后面用起来就是顺水推舟；前期图省事随便配，后面就是各种报错轮番来。这个投入产出比，用一段时间就能明显感觉到。