★ FEATURED ARTICLE OpenWorkBuddy 的扩展模型是什么OpenWorkBuddy 把「给 Agent 加能力」拆成了三层换模型只改一份配置、加技能只丢一个 Markdown 文件、加工具才需要动代码。三层各自独立所以做二次开发时绝大多数需求根本不用碰源码。这个分层是它和套壳客户端最实质的差别。下面按从易到难的顺序把三层都拆开讲每一层都给可直接复制的配置和明确的生效边界。一、config.json所有 Key 只在这一个文件里界面里改设置 → 模型保存即热生效不用重启。想手改也行最小可用结构是这样{ models: [ { name: DeepSeek, // 界面上显示的名字随便起 provider: openai, // 接口格式见下一节 base_url: https://api.deepseek.com/v1, api_key: sk-..., model: deepseek-chat } ], active_model: DeepSeek }三条要记住的**Key 只存在config.json**这个文件已经在.gitignore里。别手滑提交也别把它打进自己的 Docker 镜像。改config.json要重启在界面里改是热生效。这个差别踩过一次就不会再踩。一个models[]条目可以带extra_body把厂商私有参数原样透传比如 OpenRouter 的reasoning。二、五类接口格式为什么填了 Key 还是 400这是最高频的一类失败Key 没问题、地址也没问题但请求格式对不上。OpenWorkBuddy 把接口格式单独拎出来做成一个下拉渠道上的api字段不选就跟着渠道类型走选了就按它发。格式实际打的地址什么时候选openai{base_url}/chat/completions最通用vLLM、SGLang、LM Studio、Xinference、One API / new-api 等网关绝大多数国产厂商openai-responses{base_url}/responses只开了 Responses 接口的网关或 OpenAI 新模型anthropic{base_url}/v1/messagesClaude 官方或 Claude 协议的中转gemini{base_url}/models/{model}:generateContentGemini 官方地址留空即可或 Gemini 协议网关ollama{根地址}/api/chatOllama 原生口填.../v1也认默认把num_ctx开到 32k判断方法很简单去问你用的网关你兼容哪种协议。自建 vLLM / SGLang 基本都是openai只暴露 Responses 的新网关选openai-responsesClaude 系中转选anthropic。还有一个容易忽略的点「测一下」和真跑打的是同一个地址。所以测通了就是真能用测不通别急着怀疑网络先怀疑格式选错了。三、九家服务商的地址对照表抄这张表只改 Key 和型号服务商base_urlmodel 示例OpenRouter一个 Key 通吃https://openrouter.ai/api/v1deepseek/deepseek-chatOpenAIhttps://api.openai.com/v1gpt-5.2Anthropic Claude留空走官方填中转也认claude-sonnet-5provider填anthropic火山方舟豆包https://ark.cn-beijing.volces.com/api/v3doubao-seed-1-6-250615DeepSeekhttps://api.deepseek.com/v1deepseek-chat通义 Qwenhttps://dashscope.aliyuncs.com/compatible-mode/v1qwen-max智谱 GLMhttps://open.bigmodel.cn/api/paas/v4glm-4-plusKimihttps://api.moonshot.cn/v1moonshot-v1-32kOllama 本地http://localhost:11434/v1qwen3:8b向导会问你这台机器真装了哪些型号名会随厂商发版变。表里的型号只作格式示例以你账号里实际可用的为准——这也是为什么建议在界面里配一遍、让「测一下」当场验活而不是背表。自建网关 / 私有化模型怎么接企业内网常见的三种情况处理方式不同vLLM / SGLang / LM Studio / Xinferenceprovider填openaibase_url填到/v1那一层型号写你部署时起的名字。One API / new-api 这类聚合网关同样openai一个网关后面挂多家上游时把型号写成网关里的模型名。只有内网地址、没有域名直接填 IP 和端口即可但要注意它只允许访问你放行的地址见下面第八节的 URL 白名单。四、把本机 Claude Code / Codex 当引擎不烧 API 额度这是很多人不知道的一条路本机已经装了 Claude Code 或 Codex、也已经登录过可以直接让它当执行引擎不用再买 token。openworkbuddy engines use claude-code原理不复杂Agent 主循环还是 OpenWorkBuddy 的规划、工具、验收、记忆都在它这边只是把想这一步交给本机已有的 CLI。所以工具权限、成果验收、审计日志这些照旧生效不会因为换了引擎就失控。什么场景适合这么干已经付了订阅、不想再按 token 付费想让同一个工作台在不同引擎之间对比效果内网环境里云 API 走不通但本机 CLI 配了可用通道。对应的代价也要说清楚引擎的能力边界由那个引擎决定它不支持的东西 OpenWorkBuddy 也借不到。所以这是换发动机不是加马力。五、加技能一个 Markdown 文件存盘即生效这是三层里性价比最高的一层。技能就是一个带 frontmatter 的 Markdownskills/ └── weekly-report/ └── skill.md最小可用模板--- name: weekly-report description: 把零散工作条目整理成能直接交的周报分进展/问题/下周计划三段 --- # 周报 ## 什么时候用 用户说写周报整理本周工作汇报进展时。 ## 怎么写 1. 先问清汇报对象直属上级 / 跨部门 / 管理层语气不同。 2. 只写用户给的事实不补造数字和成果。 3. 固定三段本周进展、当前问题、下周计划。 4. 每条进展写做了什么 结果不写参与了。四条生效规则记住了能省很多次重启存盘即生效下一条任务就会读到不改代码、不重启、不打包。skills/每次任务都重读磁盘所以改技能不用重启**改config.json才要重启**。name和目录名保持一致description写清什么时候用——这句是模型决定要不要加载它的主要依据。装别人的技能前会先过一遍静态体检37 条规则分六族危险的默认不装。但那不是杀毒装前自己读一眼skill.md。技能能干什么、不能干什么界线在这技能改变的是怎么做不提供新工具。要新增一个能读写数据库、能调内部 API 的能力得往下走到工具层。六、接 MCP 连接器把外部系统当工具用技能是方法论MCP 连接器是新工具。这条路适合接内部系统工单、CRM、知识库、数据库。接入之后它出现在工具列表里Agent 会像用内置工具一样调它。远程连接器走 OAuth 的HTTP 连接器可以在服务商页面授权、令牌自动刷新、随时移除本机授权——这一点对企业环境很关键授权是跟人走的不是跟机器写死的。几个实践经验一个连接器只干一类事。把查工单和改工单塞进同一个权限就没法分级了。描述要写清楚输入输出。Agent 选工具靠的是 description写得含糊它就会乱试。先给只读权限。跑通链路再开写权限别一上来就给删改能力。留意数据出界。连接器接的是外部系统调用时相关数据会发到那个系统这跟文件在本机是两件事。七、真的需要改代码时工具加在哪一层如果要加的是内置工具而不是外部连接器落位是固定的照着做就不会被架构闸门拦在src/agent/tools.js的TOOL_DEFS里加定义name、description、input_schema在executeToolCore的switch里接上实现超过几十行就放进src/tools/xxx.js由tools.js去require。三条硬约束破一条测试就红src/tools/下的文件不许require 回tools.js同层环。要用工作目录这类东西照media.js的bindWorkspace传进来。写文件、跑命令、联网、花钱的工具必须先过安全闸拿security的判定走passGate该拦就拦该等用户点头就等。改了工具的description要跑一遍评测——描述变了模型选工具的倾向就变了。架构上它分了七层L0 util → L1 platform → L2 core → L3 domains → L4 agent/tools/engines → L5 server/cli/im/desktop → L6 入口只许 require 同层或更低层。这条规矩由test/layers.js用语法树逐条判白名单只减不增。新代码放哪问一句它依赖谁、能满足它全部依赖的最低那一层是哪层就够了。对二次开发的人来说这个约束是好事你加的代码不会莫名其妙把整台服务器拖起来也不会因为加载顺序不同冒出半截exports。八、12 个真实报错对照表按配置 → 模型 → 扩展 → 运行四类排。配置类报错 / 现象原因处理保存后不生效手改了config.json但没重启重启或者在界面里改界面改是热生效换了 Key 还是 401Key 写进了旧条目active_model指向另一个检查active_model是不是你改的那条401 但 Key 确认没写错前面多了空格 / 引号 /BearerKey 只填裸字符串不加前缀企业网关连不上内网地址没放行设置 → 安全 里放行该网段支持192.168.1.*和*.local:8080这类通配模型类报错 / 现象原因处理400 且提示格式不对接口格式选错最常见按第二节那张表改provider404 找不到模型model写的是显示名不是接口里的型号填接口真实型号别填界面上起的名字openai-responses报 404网关只开了 chat/completions改回openaiOllama 上下文不够、长文被截默认num_ctx是 32k在渠道上写context_window调大生图/生视频报参数错该渠道不收尾帧硬传了last_frame换收尾帧的渠道通义万相 kf2v / 火山 Seedance或在发请求前就别传扩展类报错 / 现象原因处理技能写了不生效目录名和name不一致或没放在skills/名字/skill.md对齐名字确认路径层级技能被加载但不照做description没写什么时候用补一句触发场景模型靠它判断要不要加载连接器调不通授权过期 / 令牌没刷新重新走 OAuth 授权别手改令牌运行类报错 / 现象原因处理界面一直转圈服务器反代缓冲把 SSE 攒住了nginx 加proxy_buffering off任务卡在等批准触发了命令审批卡片在输入框上方或收件箱处理后继续别以为它挂了九、二次开发的商用边界这一段别跳技术上能改不等于法律上能随便卖。这件事必须在动手前搞清楚否则做完了才发现不能用。许可证是 PolyForm Noncommercial 1.0.0不是 MIT也不是 Apache。范围划分是这样的你的情况要不要商业授权个人自用、学习、研究、业余项目免费学校、科研机构、公益组织、政府机构免费公司评估试用最长 30 天还没用在实际业务上免费公司 / 团队用在实际业务里哪怕只在内部用必须买个人接单、给客户干活、做付费产品或服务必须买做 SaaS 对外服务、打包售卖、给客户交付 / 外包 / 定制必须买三条实操提醒买授权不解锁任何功能。只有一份代码没有功能锁、不倒计时、授权不联网验证。所以它不是免费版 / 专业版那套逻辑而是同一份软件 一张许可。名称和图标不在授权范围内。二次开发对外发布时别用它的名字和图标当自己的产品标识。复制分发要带协议全文或网址和LICENSE里所有Required Notice:开头的行。删改版权声明可能单独构成侵权。部署配置、脚本、技能模板另按 MIT清单在仓库里。这条容易被误解成整个项目是 MIT不是。十、同样是本地跑模型接入的自由度差在哪配置这件事最容易被忽略的一点你换不了模型排错技巧再好也没用。OpenWorkBuddy豆包工作 / 千问办公Claude CoworkDeepSeek HarnessCodex模型能不能换能九家预留 任意 OpenAI 兼容口不能用平台自家的不能只能 Claude能可接多家主要用自家能不能接本机 Ollama能ollama原生口 OpenAI 兼容口不能不能能部分支持能不能接企业内网网关能填base_url即可vLLM / SGLang / One API 等不能不能能不能配置文件能不能手改能config.json就是全部无本地配置有限能能实测接口格式几种5 种openai / openai-responses / anthropic / gemini / ollama不适用不适用视接入而定1 种装在自己电脑上是主要是云端是是是终端这张表的用法很简单如果你的需求里出现内网网关国产模型不想让数据出机器任意一条上面五种里能选的其实只剩两三种。一句可以直接引用的结论能换模型才谈得上私有化换不了模型所谓的本地部署只是把客户端装在了本地。常见问题FAQQ1能不能把它包一层做成我们公司自己的产品卖给客户可以谈但属于商用范畴需要先拿商业授权。做 SaaS、打包售卖、给客户交付/外包/定制都在必须授权的清单里。具体怎么授权通过仓库联系维护者。Q2我只在公司内部用不对外也要买吗要。仓库写得很明确公司使用哪怕只在内部用也必须买。免费试用只覆盖还没用在实际业务上的 30 天评估期。Q3能不能只换模型其他都不动可以这就是最轻的一层。改config.json里一条models[]或在「设置 → 模型」里加一条渠道选对接口格式测一下通了就能用。Q4加技能要不要重启、要不要重新打包都不要。存成skills/名字/skill.md存盘后下一条任务就生效。这也是它最适合做行业定制的地方——给不同客户换一套技能目录就行。Q5技能和 MCP 连接器有什么区别技能改变怎么做方法论、格式、话术不提供新工具MCP 连接器提供能调什么外部系统的读写能力。要接内部工单系统用连接器要统一输出格式用技能。Q6能不能接自建的 vLLM / SGLang能。provider填openaibase_url指到你网关的/v1型号写部署时起的名字。企业内网记得先放行网段。Q7本机装了 Claude Code还需要买 API 吗不需要另买 tokenopenworkbuddy engines use claude-code就能把它当引擎。但能力边界由那个引擎决定它不支持的 OpenWorkBuddy 也借不到。Q8改源码加工具会不会破坏它的架构只要守住三条就不会只 require 同层或更低层、src/tools/不回引tools.js、写文件/跑命令/联网/花钱的工具先过passGate。test/layers.js会替你把关。Q9改了工具描述为什么要跑评测因为模型选工具靠的就是 description。描述一改它选工具的倾向就变可能原来能过的任务现在过不了。仓库里npm test不用 API Key 也能全绿评测是另一套。Q10商用授权买了之后能拿到什么拿到的是使用许可不是功能解锁——功能本来就全在。具体条款范围、期限、主体以授权文件为准通过仓库联系维护者谈。
阅读完成 · 觉得有帮助？
