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代码上下文管理更专业跨模型编排、多技能组合任务WorkBuddyAgent 中台定位扩展性强需要自定义规则约束所有任务WorkBuddy规则体系更完整只想快速问答两者都行但都算杀鸡用牛刀我自己的做法是两个都装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 安装步骤的实际操作安装本身按官方引导走就行我重点说几个引导里不会强调但实际要注意的点安装路径尽量选一个没有中文、没有空格的目录。这个不是 WorkBuddy 独有的问题很多工具在处理路径时对中文和空格的支持都不够稳能避就避。安装完成后先别急着配模型先启动一次看看主界面能不能正常打开、有没有报错。这一步是确认基础环境没问题把安装问题和配置问题分开排查。首次启动会让你选工作目录这个目录建议单独建一个不要直接用桌面或者文档根目录。因为 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 状态Key 和 baseUrl 不匹配确认这个 Key 是对应这个服务商的Key 权限不足确认 Key 有调用该模型的权限我遇到最多的是复制 Key 时带了空格或者换行。这个特别隐蔽因为肉眼看不出区别。解决办法是把 Key 粘贴到纯文本编辑器里看一眼确认是干净的一行。还有一种情况是 Key 和地址不匹配。比如你拿 A 服务商的 Key 去配 B 服务商的地址那必然 401。这个听起来很蠢但实际配置多个模型时真的容易搞混尤其是 Key 长得都差不多的时候。5.2 400 报错上下文超限和模型配置问题热词里有api error: 400 this models maximum context length is 1048576 tokens这个报错的意思是你发给模型的上下文超过了它的上限。1048576 这个数字看着很大但如果你把整个项目文件都塞进去或者对话历史很长是真的会超的。处理办法有几个一是精简输入只发必要的内容二是开启上下文压缩或者分段处理三是换一个上下文窗口更大的模型。我一般是用第一种因为最直接。还有一种 400 是this organization has been disabled这个是账号层面的问题通常是服务商那边把你的组织禁用了这个只能去服务商后台处理本地怎么改配置都没用。5.3 排查报错的通用思路我总结了一个排查顺序基本能覆盖大部分情况先看报错类型401 是鉴权问题400 是请求问题404 是地址问题超时是网络问题。类型决定了排查方向。再看是哪个模型报的多模型配置时先确认是单个模型的问题还是全部模型的问题。单个就是那个模型的配置问题全部就是公共配置或者网络问题。然后核对配置把出问题的模型配置和服务商文档逐字段对一遍重点看 baseUrl 和 model 标识。最后测连通性用一个最简单的请求测一下排除是复杂请求导致的问题。这个顺序的好处是你不用一上来就怀疑所有东西按类型缩小范围效率高很多。6. 缓存目录迁移系统盘告急的救命操作6.1 为什么要迁移WorkBuddy 跑一段时间后缓存目录会越来越大。如果你系统盘本来就不宽裕很快就会收到磁盘空间不足的警告。热词里有人问workbuddy 系统缓存目录能改到 d 盘吗答案是能而且操作不复杂。6.2 迁移的实际步骤迁移的核心思路是先把缓存目录整个复制到新位置再修改配置指向新位置最后确认没问题再删旧的。顺序不能反反了容易丢数据。找到当前的缓存目录。这个通常在设置里能看到或者在安装目录下的某个子目录里。完全退出 WorkBuddy确保没有进程在占用缓存文件。把整个缓存目录复制到目标位置比如D:\WorkBuddyCache。修改配置文件里的缓存路径指向新位置。重新启动 WorkBuddy确认能正常读取缓存、任务能正常跑。确认无误后再删除旧位置的缓存。注意第 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 都配好后面用起来就是顺水推舟前期图省事随便配后面就是各种报错轮番来。这个投入产出比用一段时间就能明显感觉到。