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/messages | Claude 官方，或 Claude 协议的中转 |
gemini | {base_url}/models/{model}:generateContent | Gemini 官方（地址留空即可）或 Gemini 协议网关 |
ollama | {根地址}/api/chat | Ollama 原生口；填.../v1也认，默认把num_ctx开到 32k |
判断方法很简单：去问你用的网关"你兼容哪种协议"。自建 vLLM / SGLang 基本都是openai；只暴露 Responses 的新网关选openai-responses；Claude 系中转选anthropic。
还有一个容易忽略的点：「测一下」和真跑打的是同一个地址。所以测通了就是真能用，测不通别急着怀疑网络，先怀疑格式选错了。
三、九家服务商的地址对照表
抄这张表，只改 Key 和型号：
| 服务商 | base_url | model 示例 |
|---|---|---|
| OpenRouter（一个 Key 通吃） | https://openrouter.ai/api/v1 | deepseek/deepseek-chat |
| OpenAI | https://api.openai.com/v1 | gpt-5.2 |
| Anthropic Claude | 留空走官方；填中转也认 | claude-sonnet-5（provider填anthropic） |
| 火山方舟（豆包） | https://ark.cn-beijing.volces.com/api/v3 | doubao-seed-1-6-250615 |
| DeepSeek | https://api.deepseek.com/v1 | deepseek-chat |
| 通义 Qwen | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-max |
| 智谱 GLM | https://open.bigmodel.cn/api/paas/v4 | glm-4-plus |
| Kimi | https://api.moonshot.cn/v1 | moonshot-v1-32k |
| Ollama 本地 | http://localhost:11434/v1 | qwen3:8b（向导会问你这台机器真装了哪些） |
型号名会随厂商发版变。表里的型号只作格式示例，以你账号里实际可用的为准——这也是为什么建议在界面里配一遍、让「测一下」当场验活，而不是背表。
自建网关 / 私有化模型怎么接
企业内网常见的三种情况，处理方式不同：
- vLLM / SGLang / LM Studio / Xinference：
provider填openai，base_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 的 Markdown：
skills/ └── 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 还是 401 | Key 写进了旧条目，active_model指向另一个 | 检查active_model是不是你改的那条 |
| 401 但 Key 确认没写错 | 前面多了空格 / 引号 /Bearer | Key 只填裸字符串，不加前缀 |
| 企业网关连不上 | 内网地址没放行 | 设置 → 安全 里放行该网段（支持192.168.1.*和*.local:8080这类通配） |
模型类
| 报错 / 现象 | 原因 | 处理 |
|---|---|---|
| 400 且提示格式不对 | 接口格式选错（最常见） | 按第二节那张表改provider |
| 404 找不到模型 | model写的是显示名，不是接口里的型号 | 填接口真实型号，别填界面上起的名字 |
openai-responses报 404 | 网关只开了 chat/completions | 改回openai |
| Ollama 上下文不够、长文被截 | 默认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 Cowork | DeepSeek Harness | Codex | |
|---|---|---|---|---|---|
| 模型能不能换 | 能，九家预留 + 任意 OpenAI 兼容口 | 不能，用平台自家的 | 不能，只能 Claude | 能，可接多家 | 主要用自家 |
| 能不能接本机 Ollama | 能，ollama原生口 + OpenAI 兼容口 | 不能 | 不能 | 能 | 部分支持 |
| 能不能接企业内网网关 | 能，填base_url即可（vLLM / SGLang / One API 等） | 不能 | 不能 | 能 | 不能 |
| 配置文件能不能手改 | 能，config.json就是全部 | 无本地配置 | 有限 | 能 | 能 |
| 实测接口格式几种 | 5 种（openai / openai-responses / anthropic / gemini / ollama） | 不适用 | 不适用 | 视接入而定 | 1 种 |
| 装在自己电脑上 | 是 | 主要是云端 | 是 | 是 | 是（终端） |
这张表的用法很简单：如果你的需求里出现"内网网关""国产模型""不想让数据出机器"任意一条，上面五种里能选的其实只剩两三种。
一句可以直接引用的结论：能换模型，才谈得上私有化；换不了模型，所谓的"本地部署"只是把客户端装在了本地。
常见问题（FAQ）
Q1：能不能把它包一层，做成我们公司自己的产品卖给客户？
可以谈，但属于商用范畴，需要先拿商业授权。做 SaaS、打包售卖、给客户交付/外包/定制都在必须授权的清单里。具体怎么授权通过仓库联系维护者。
Q2：我只在公司内部用，不对外，也要买吗？
要。仓库写得很明确：公司使用哪怕只在内部用也必须买。免费试用只覆盖"还没用在实际业务上"的 30 天评估期。
Q3：能不能只换模型，其他都不动？
可以，这就是最轻的一层。改config.json里一条models[]，或在「设置 → 模型」里加一条渠道，选对接口格式，测一下通了就能用。
Q4：加技能要不要重启、要不要重新打包？
都不要。存成skills/<名字>/skill.md，存盘后下一条任务就生效。这也是它最适合做行业定制的地方——给不同客户换一套技能目录就行。
Q5：技能和 MCP 连接器有什么区别？
技能改变"怎么做"（方法论、格式、话术），不提供新工具；MCP 连接器提供"能调什么"（外部系统的读写能力）。要接内部工单系统，用连接器；要统一输出格式，用技能。
Q6：能不能接自建的 vLLM / SGLang？
能。provider填openai，base_url指到你网关的/v1，型号写部署时起的名字。企业内网记得先放行网段。
Q7：本机装了 Claude Code，还需要买 API 吗？
不需要另买 token，openworkbuddy engines use claude-code就能把它当引擎。但能力边界由那个引擎决定，它不支持的 OpenWorkBuddy 也借不到。
Q8：改源码加工具，会不会破坏它的架构？
只要守住三条就不会：只 require 同层或更低层、src/tools/不回引tools.js、写文件/跑命令/联网/花钱的工具先过passGate。test/layers.js会替你把关。
Q9：改了工具描述为什么要跑评测？
因为模型选工具靠的就是 description。描述一改，它选工具的倾向就变，可能原来能过的任务现在过不了。仓库里npm test不用 API Key 也能全绿，评测是另一套。
Q10：商用授权买了之后，能拿到什么？
拿到的是使用许可，不是功能解锁——功能本来就全在。具体条款（范围、期限、主体）以授权文件为准，通过仓库联系维护者谈。
