OpenWork 开源桌面应用怎么接模型：三条路径的机制与代价

本文基于 openwork 仓库 commit 3b41381（2026-08-03）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/different-ai/openwork 最新代码与文档为准。

在 OpenWork 里接一个模型，本质上是往工作区的 OpenCode 配置文件和凭据存储里写一条记录；三条路的真正区别不是点几下鼠标，而是这条记录由谁写、写在哪个文件、以及谁有权把它改掉或删掉。 这个判断成立之后，后面那些「为什么 Anthropic 要手工粘 key」「为什么本地模型要改 JSON」「为什么公司发的这台机器上添加自定义供应商是灰的」都能顺着推出来。

先把名字说清楚：本文说的 OpenWork 是 different-ai 开源的那个桌面应用项目，跟同名的职场点评网站、跟中文里泛指的「开放工作」没有关系，下文出现的 OpenWork 一律指这个项目。

这也是本篇跟站内几篇的分工——API 接入方式对比讲的是直连、聚合、自建网关这些通用形态怎么选，模型路由策略讲多模型之间按什么规则分流，多模型 fallback 设计讲主模型挂掉之后怎么退，而本篇只钉在 OpenWork 这一个具体项目上，讲它的接入机制长什么样、代价在哪。

一、三条路分别在解决什么问题

OpenWork 把模型接入的文档放在 packages/docs/start-here/connect-your-stack/ 目录下，跟 MCP 服务器接入、外部服务连接并列。同一个目录里，模型接入相关的正好是三份，对应三种完全不同的处境。

第一种处境：你手上有服务商控制台里签发的 API key。这条路最直白，桌面端给一个手工输入框，你把 key 粘进去。add-anthropic-api-key.mdx 讲的就是这条，并且它明确说了这条路在 Anthropic 上是被动变成默认的——文档写的是 Anthropic 已经关闭了第三方 OAuth，为了继续支持 Anthropic 系模型，OpenWork 改为默认走手工 API key 录入。

第二种处境：你要接的东西不在任何目录里，可能是局域网里一台跑本地模型的机器，也可能是自家部署的兼容层。这条路要落到配置文件上，add-a-custom-llm.mdx 给的是 JSON 结构。

第三种处境：你已经为某个订阅付过费了，不想再单独申一把 key。sign-in-with-chatgpt.mdx 走的是浏览器授权，把已有账号的登录态引进来。

组成部分	它负责什么	对应仓库位置	你什么时候会碰到它
供应商接入弹窗	渲染手工 key 输入、OAuth 等待、设备码确认这几种不同的接入视图	apps/app/src/react-app/domains/connections/provider-auth/provider-auth-modal.tsx	在 Settings 里点 Connect Provider 的那一刻
云端供应商配置写入与对账	把组织下发的供应商定义写进工作区配置，并拆分凭据的落点	apps/app/src/react-app/domains/connections/provider-auth/cloud-provider-config.ts	从 Settings -> Cloud 点 Import、Sync、Remove 时
桌面策略闸门	判断某个供应商 ID 在当前组织策略下允不允许添加、允不允许选用	apps/app/src/react-app/domains/connections/provider-auth/provider-policy.ts	公司机器上「添加自定义供应商」变灰时
自定义供应商文档	给出 OpenCode 风格的 provider JSON 结构与本地模型样例	packages/docs/start-here/connect-your-stack/add-a-custom-llm.mdx	接私有端点或本地模型时
团队托管供应商文档	组织侧统一保管凭据、圈定模型清单、分配访问范围	packages/docs/cloud/share-with-your-team/managed-llm-provider.mdx	一把 key 要给一队人用时
出网主机清单	列出桌面端与服务端各自要放行的域名，以及被拦之后具体坏在哪	packages/docs/start-here/outbound-network-access.mdx	内网机器接入失败、要找 IT 开白名单时

顺带交代一句出处：仓库根目录的 README 是这样给自己定位的——一个用来共享 AI 工作流的免费开源桌面应用，并把自己表述为 Claude Cowork 和 Codex 的开源替代。这是项目自己的说法，不是本文的判断，你照旧按自己的场景去验证。

二、自带 key：最直白的一条，也是最需要你负责的一条

add-anthropic-api-key.mdx 把流程拆得很细：在 platform.claude.com 登录，打开 API Keys 页面，点 Create Key，给它起个能认出来的名字（文档建议就叫 OpenWork），然后立刻复制——文档专门提醒，完整值只在创建时显示一次，之后要当密码对待。回到桌面端，打开 Settings，进 Connect Provider 选 Anthropic，把 key 粘进手工输入框，保存，然后在聊天里选一个 Anthropic 模型。

它还给了三条排障提示，每条都对应一类真实错误：key 被拒，先检查复制时是不是带了多余空格；看不到 API Keys 页面，去确认这个账号有没有开通 API 访问与计费；key 弄丢了，别指望找回，回服务商重新签一把再回来更新。文档末尾补了一句很有用的泛化——大多数走手工 key 的服务商都是这个套路：在服务商开发者控制台创建、复制一次、粘进 OpenWork。

这条路的机制代价很清楚：凭据的生命周期完全由你自己管。轮换、作废、发现泄露后的止损，OpenWork 这边不会替你做，它只是持有者。凭据管理本身的通用做法可以看API Key 安全管理，这里不重复。

还有一点要留意：Anthropic 这条路从 OAuth 退回手工 key，是上游服务商侧的策略变化导致的，不是 OpenWork 的设计偏好。这类规则会调整，具体以官方最新说明为准。

三、自定义供应商：底座是 OpenCode 的配置文件

add-a-custom-llm.mdx 开门见山地交代了一件事：因为 OpenWork 建立在 OpenCode 的原语之上，凡是你能在 .opencode.json 里改的东西，OpenWork 都支持。这句话的分量比它看起来大——它意味着模型接入这一层不是 OpenWork 自己发明的格式，你在 OpenCode 生态里攒的配置经验可以直接迁过来。

紧接着是一条很实际的建议：改配置请写到 /path-to-your-workspace/.config/opencode/opencode.json，而不是去动 ~/.config/opencode/opencode.json。前者是工作区级的，后者是用户全局的。这个取舍指向的是同一台机器上多个工作区互不串味。

文档给的结构长这样：

{
  "provider": {
    "my-api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My model",
      "options": {
        "baseURL": "https://your API address/v1"
      },
      "models": {
        "model-name": {
          "name": "Model name"
        }
      }
    }
  }
}

四个键各管一段：npm 指定用哪个 AI SDK 包去说话，OpenAI 兼容端点填 @ai-sdk/openai-compatible；name 是显示名；options.baseURL 是端点地址；models 下面挂这个端点实际提供的模型。

文档随后给了一个能跑通的本地例子：provider 的 key 写成 ollama，baseURL 指向 http://localhost:11434/v1，models 下挂 qwen3:8b。前置动作是先 ollama pull qwen3:8b 把模型拉下来，再确认 ollama serve 起来了、端口可达。文档对结果的描述是：改一下供应商名，你机器上就跑着一个完全本地的 LLM。

这条路的代价同样直白：你得自己保证那个端点真的兼容、真的活着。JSON 里写错一个键名，或者端点地址少了 /v1，桌面端能做的只是失败，它没法替你猜。

团队场景下这条路还有个变体。custom-llm-provider.mdx 说明，如果供应商不在目录里，可以在 OpenWork Cloud 的 LLM Providers 里切到 Custom provider，填 Name（Provider ID 会自动带出）、OpenAI 兼容端点的 Base URL、这个端点提供的 Model IDs，再粘共享凭据——OpenAI 兼容端点走到这一步就不需要写 JSON 了。需要更细的控制时，那里还有一个 Advanced: edit as JSON 入口，接受 models.dev 风格的定义，文档要求这份 JSON 至少包含 id、name、npm、env、models 这几项，api 可选但多数 OpenAI 兼容供应商都会用；编辑器会校验 JSON 合法、至少一个环境变量、至少一个模型。

四、借用别处的登录态：把订阅账号引进来

sign-in-with-chatgpt.mdx 描述的路径是 Settings > Connect Provider > OpenAI > ChatGPT Pro/Plus，然后在打开的 openai Auth 页面用有效订阅的邮箱登录，完成授权后回到聊天界面换模型。文档最后一句点出了三条路汇合的地方：模型选择器里能选的，是你已连接的所有供应商提供的全部模型——三条路进来的模型在选择器里是平权的。

界面代码里能看到这条路不止一种形态。provider-auth-modal.tsx 有一个自动完成的分支：浏览器标签页里登录完，桌面端自己把连接补完，界面上显示的是等待浏览器确认、自动轮询连接状态。还有一个针对 OpenAI 的无头分支，界面文案要求你先在账号设置里打开设备码授权（文案里给的路径是 ChatGPT > Account Settings > Security > Enable device code authorization），然后复制界面上那串确认码、点开浏览器、粘进去，回来点 Complete connection。同一个弹窗上还留了 Open browser again，专门救「浏览器窗口被顺手关掉了」这种事故。

这条路省掉了申 key 和保管 key 两件事，但换来另一组约束：授权的有效性挂在你的订阅账号上，账号那边的任何变化都会直接反映到桌面端；而设备码授权是账号级的安全开关，第一次接入要你自己去打开——这本身就是一次对账号安全策略的改动，值不值得你自己判断。

五、边界与代价：这套设计明确不管什么

它不管路由。 三条路解决的是「模型可用」，不是「什么请求走哪个模型」。选择器把可用模型都列出来，选哪个是人的动作。想要按任务类型自动分流、按失败自动降级，那属于另一层要自己搭的东西。

它不管缓存。 what-uses-tokens.mdx 里写得很明白：目前没有结果缓存，同一个任务重跑一次就是重新发一次模型请求。同一份文档还提到，用量会跟着智能体要读的上下文规模一起涨，工具调用多的任务通常更贵。这两条对成本预期的影响比很多人以为的大，尤其是在反复调试同一条流程的时候。

它不管端点的真实能力。 自定义供应商那条路只负责把请求发到你给的地址，端点支不支持工具调用、返回格式对不对，配置文件里写什么都不改变事实。

凭据是集中保管的，这就是暴露面。 cloud-provider-config.ts 里的逻辑显示，云端下发的供应商凭据会被拆成两部分落地：一部分作为 opencode auth.json 里的条目，一部分作为环境变量写入；多凭据的供应商按 models.dev 的约定，把 env 列表里的第一个当作主凭据。也就是说，一台装了 OpenWork 的机器上，同时躺着你所有已接入供应商的凭据。这台机器的磁盘加密、锁屏习惯、有没有别人共用，都变成了模型凭据安全的一部分。

在有组织的场景里，能不能自己接模型不由你决定。 desktop-policies.mdx 列出的桌面策略键里，Custom providers 直接控制「允不允许本地添加未经 OpenWork Cloud 下发的模型供应商」，Enable OpenCode Zen Models 控制内置模型能不能用，Control Settings 控制能不能改桌面设置。代码侧对得上：provider-policy.ts 读的限制项名叫 allowCustomProviders，一旦开启限制，只有云端托管的供应商键以及那个特定的内置供应商 ID 能过闸。文档还说明，被策略挡掉的能力会以组织控制的形式解释给用户，被禁的内置扩展会从常规目录里隐藏，并在隐藏视图里带上 Disabled by organization 的说明。策略的生效时机是重载、切换云端组织、更换云端账号，或者等每小时一次的桌面配置刷新。

组织侧看得到什么，得单独想清楚。 走 managed-llm-provider.mdx 那条路时，组织在 Cloud 的 LLM Providers 里点 Add Provider，停在 Catalog provider，选好供应商与要暴露的模型，粘贴共享的 API key / credential，再配置 People access 与 Team access；桌面端从 Settings -> Cloud 选中 Active org 后点 Import，OpenWork 会把这个供应商写进工作区的 opencode.jsonc，并为该工作区保存组织凭据。之后组织侧改了模型或权限，成员用 Sync 拉齐；组织侧删掉了，桌面端会显示 Removed from cloud 并允许 Uninstall 本地配置。换句话说，你用的是别人保管的凭据，模型清单和访问范围的定义权也在别人手里。

许可证是分层的，别笼统当成一句「MIT 开源」。 仓库根 LICENSE 写明：/ee 目录下的全部内容按 ee/LICENSE 定义的 Fair Source 许可证（该文件标题是 Functional Source License, Version 1.1, MIT Future License），其余部分才是 MIT（Copyright 2026 Different AI），第三方组件另按各自原始许可。上面提到的组织控制面相关实现，大量落在 ee/ 之下——仓库里 ee/apps/ 有 10 个、ee/packages/ 有 3 个，而非 ee 侧的 apps/ 是 4 个、packages/ 是 12 个。本文不提供法律意见，能不能商用、能不能改、改了能不能分发，一律以许可证原文为准。

六、上手与避坑清单

别去改用户全局的那份 OpenCode 配置。 会踩是因为习惯和搜索都会把你引到 ~/.config/opencode/opencode.json，那是最眼熟的位置。怎么避：按文档建议写到工作区下的 .config/opencode/opencode.json，让每个工作区的供应商互不影响。

别手改带 lpr_ 前缀的供应商块，也别手改 openwork 那个键。 会踩是因为它们和你手写的供应商躺在同一份 opencode.jsonc 里，看上去没差别。代码注释写得很清楚：这两类键属于云端导入系统所有，从来不是手写的，所以在这两类键上重新导入会被当作一次安全的对账（用来找回丢失的导入基线）覆盖掉，而不是被当成对用户手写供应商的误伤。怎么避：自定义供应商用你自己的 ID，跟这两类键错开。

别在内网机器上假设「装上就能连」。 会踩是因为默认的模型目录来自 models.openworklabs.com，被防火墙拦掉的表现不是明确报错，而是模型列表陈旧、残缺或干脆出不来。怎么避：照 outbound-network-access.mdx 的表把需要的主机报给 IT；模型目录可以用 OPENCODE_MODELS_URL 指到内部镜像。那份表格背后还有一份机器可读的清单文件和一个 CI 检查脚本在守着，别凭记忆列白名单。

别指望订阅登录能一次配好永远不管。 会踩是因为这条路的有效性挂在外部账号上，而不是挂在一串你自己保管的字符串上。怎么避：把「重新授权」当成会周期性发生的运维动作纳入预案，而不是当成故障；团队场景下尤其别让关键流程只依赖某个人的个人订阅。

别把粘贴凭据当成一次性动作就撒手。 会踩是因为手工 key 这条路上，桌面端只负责持有，轮换与作废的责任在你。怎么避：给每把 key 起可识别的名字（文档就建议叫 OpenWork），在服务商侧留下这把 key 给哪台机器用的记录，机器换手或人员离开时按名字回收。

别把「能选到这个模型」等同于「这个模型在这台机器上真的能干活」。 会踩是因为选择器把所有已连接供应商的模型混在一起展示，看不出来源差异，而自定义端点的兼容程度只有跑一次才知道。怎么避：新接一个供应商后，先跑一个会触发工具调用的真实任务，而不是只发一句「你好」。这一步同样适用于 MCP 侧的连接，授权与权限收敛的思路可以参考MCP 授权加固。

别忽略策略生效有延迟。 会踩是因为管理员在 Cloud 里改完策略，成员这边看起来「没变化」，于是以为改错了。怎么避：按文档的路子主动触发——重载、切换活动组织、刷新云端账号，或者干脆等那次每小时的配置刷新。

接下来读哪个文件

如果你只是想在自己机器上跑起来，按这三问核一遍就够了：模型选择器里能看到目标模型吗？换一个需要工具调用的任务还能跑通吗？这台机器上现在躺着几家供应商的凭据，你说得出来吗？

想再往下挖，仓库里有三处值得先看。packages/docs/start-here/connect-your-stack/ 是三条路的一手说明，篇幅短但每句话都对应一个具体动作。apps/app/src/react-app/domains/connections/provider-auth/ 是接入行为的实现所在，弹窗、云端配置写入、策略判断三份文件互相咬合，读代码比读文档更能看清边界在哪。packages/docs/start-here/outbound-network-access.mdx 则是内网落地绕不开的一份，里面「被拦掉之后具体坏在哪」那一列，比单纯的域名清单有用得多。

至于组织控制面那一侧，先看清 ee/ 的许可证边界再决定要不要深入——这一步的判断标准只有许可证原文，不是任何一篇解读文章。

本篇属于一个把开源AI 工作流桌面应用 OpenWork逐层拆开讲的系列，整体地图见 OpenWork 是什么：把技能与 MCP 打包成能力的开源桌面应用；沿着这条线往下，还可以看 给开源桌面应用 OpenWork 接外部服务：MCP 服务器、办公套件与搜索的授权边界 和 OpenWork 开源桌面应用的跨会话记忆：一层你能读能改的明文记忆。