OpenWork 开源桌面应用连不上：先走网络自查线，再用诊断提示词
本文基于 openwork 仓库 commit 3b41381（2026-08-03）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/different-ai/openwork 最新代码与文档为准。
OpenWork 连不上时最贵的一步，是一上来就去改配置。 这个开源桌面应用把「连不上」拆成了两条互不重叠的线：一条是 DNS、TCP 443、TLS 链、代理、Den 出站可达性，归网络自查；另一条是运行时指向了错的服务器、工具没注册上、任务拿的是旧工具快照，归诊断提示词。仓库文档在这两个页面开头都写了互相指路的话，意思很直白——走错线的人，会在错误的地方反复重启和重装。
先做命名消歧。OpenWork 是 different-ai 这个组织下的一个开源桌面应用项目，把技能、MCP 连接与外部服务打包成可共享的「能力」，跟同名的职场点评网站、跟中文里泛指的「开放工作」没有关系。下文出现 OpenWork 一律指这个项目。
一、先分诊：判断你在哪条线上
分诊的依据不是症状看着有多吓人，而是失败发生在哪一层。
如果你看到的是 TLS 握手失败、证书链报错、主机名解析不了、连接被代理拦，或者 Den 这个服务端组件出不去，走网络自查线，入口是仓库文档 packages/docs/start-here/network-diagnostics.mdx。
如果网络本身是通的，但表现是「能力少了」「工具没了」「明明连着却说不认识这个能力」，走诊断提示词那条线，入口是 packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx。
这个分诊为什么值钱？因为第二类症状极容易被误判成网络问题。文档给的典型症状是：search_capabilities 返回的工具比预期少，execute_capability 对一个本该存在的名字返回 unknown_capability，而云端面板上那条连接明明显示已连接。这些看着像网络抖动，实际根因往往是本地 openwork-cloud 这条 MCP 配置是个快照——它把建立那一刻的服务器 URL 和 token 存了下来，如果当初是对着本地开发服务器建的，之后它就一直在问那个旧世界，而面板显示的是当前世界。
这里顺带把它和站内几篇相近文章的分工说清：MCP Server 启动失败排查讲的是通用 MCP 进程起不来的普适手法，Agent 失败分类讲的是怎么给失败建立分类体系，API 超时与终端排查讲的是调用侧超时的通用处理；本文只讲 OpenWork 这一个具体项目在自己仓库里备好的排查顺序，是「某个项目的实操路径」，不是通用方法论。
二、网络自查线：一个脚本，五种判决
这条线的核心工具是 scripts/support/openwork-doctor.ps1。文档把它定位成给客户 IT 用的只读体检报告：兼容 Windows PowerShell 5.1、不需要管理员权限、不改任何东西。它检查 DNS、TCP 443、用 SslStream 抓活的 TLS 证书链、在有 openssl 时再核一遍服务端实际送出的证书、读 WinHTTP 与 .NET 的代理设置、报 PowerShell 与操作系统版本，并打印 NODE_EXTRA_CA_CERTS 当前值。
脚本只接三个参数：-WebUrl、-ApiUrl、-ExpectedIssuerMatch（默认值是 DigiCert）。-WebUrl 填你的 Den web 源；只有当你的部署确实单独发布了 Den API 源时才填 -ApiUrl，单源部署里 API 路径通常挂在 web 源的 /api/den 代理后面。文档给了两种跑法：机器能连 GitHub 时直接从 raw 地址拉下来跑；raw 下载被挡时，通过你自己批准的离线通道把脚本拷过去，用 -File 方式跑。
真正省时间的是它的判决词。文档给了一张对照表，关键几条按同样口径复述如下：LIKELY TLS INTERCEPTION 意味着叶证书的签发者是内部或代理 CA 而不是预期的公共签发者，处理方向是在代理上放行 OpenWork 的主机，或者把企业根证书装进每一个需要它的信任面；LIKELY MISSING INTERMEDIATE OR UNTRUSTED ROOT 和 MISSING INTERMEDIATE CONFIRMED BY OPENSSL 都指向服务端证书链不完整，文档明确要求先修服务端的 fullchain 或证书包，再去验客户端信任；LIKELY DNS ISSUE 让你去看 VPN 状态、split-horizon DNS 以及内部主机名到底存不存在；PROXY DETECTED 表示 WinHTTP 或 .NET 把这个 URL 路由到了代理，接着查代理认证与主机放行。
顺序上的价值就在这儿：这五种判决提前把「是服务端的锅还是客户端的锅」定死了。证书链不完整是服务端问题，你在客户端装一百个根证书也没用。
三、证书与代理：四个信任面，装一个不等于全通
packages/docs/start-here/certificate-trust-and-proxies.mdx 开篇就点了这条线上最容易踩的坑：OpenWork 有多个网络信任面，给其中一个装了私有根证书，并不会自动配置其它几个。文档把它们分成四块。
第一块是桌面应用自身的 HTTPS。它的外部调用走 Electron 的 Chromium 网络栈，用的是 Chromium/Electron 的证书信任和系统代理配置；内置浏览器面板是另一回事，有自己独立的代理入口。Windows 和 macOS 上把企业根装进操作系统信任库即可；Linux 上文档特意警告，别以为往 /etc/ssl 里放就够了。它给了一段真机验证记录：在 Daytona Linux 的 Electron 端到端环境里，私有 CA 装进了 Debian 的 /etc/ssl，curl 和带 --use-system-ca 的 Node 都认，但裸 Node 的 fetch 报 UNABLE_TO_VERIFY_LEAF_SIGNATURE，Electron 的 net.fetch 报 ERR_CERT_AUTHORITY_INVALID——因为 Chromium 在那个镜像上走的是 NSS 或用户信任路径。文档也说明，裸 Node 的 fetch 并不是被认可的桌面外部调用路径，新的外部调用由守卫路由到 electronNet.fetch，但这并不消除 Linux 上 Chromium/NSS 的信任库差异。
第二块是被拉起来的本地运行时和 sidecar。每次启动时，桌面端会在用户数据目录里生成一个附加的 system-ca-bundle.pem，来源是它能读到的所有系统信任源：Node 的系统库、Windows 的 LocalMachine 与 CurrentUser 的 Root/CA 证书存储、macOS 上由管理员控制的 System 与 SystemRoot 钥匙串，合并去重后通过 NODE_EXTRA_CA_CERTS 传给子进程。这里有三条必须记住的边界：用户或启动器已经设过 NODE_EXTRA_CA_CERTS 的话，用户的值优先，OpenWork 不覆盖；这个生成的包只服务于 Node 兼容的子运行时，不配置 Electron 的 Chromium 信任库；别假设每个 sidecar 都认 HTTP_PROXY 或 HTTPS_PROXY，该按具体运行时的文档来配。
同一块里还有一个容易被误解的自动行为：启动时桌面端会检查已激活的组织服务器是不是只送了叶证书，如果叶证书通过 AIA 指向一个缺失的中间证书，它会去取那张中间证书、验签、确认能链到内置公共根，然后才加进生成的 system-ca-bundle.pem。它拒绝私有或企业根，也拒绝任何非「仅缺中间证书」的 TLS 失败。这个修复阶段默认限时 20 秒，可以用 OPENWORK_CHAIN_REPAIR_TIMEOUT_MS 调，用 OPENWORK_DISABLE_CHAIN_REPAIR=1 关掉。文档强调：服务端该修还是得修，诊断照旧报告服务端实际送出了什么。
第三块是 Den 的容器与 Helm 部署。用 chart 的 customCa 把选定的 Secret 或 ConfigMap 键挂到 /etc/openwork/custom-ca/ca-bundle.pem，并为 den-api、den-web、启用的 inference 和迁移 Job 设置 NODE_EXTRA_CA_CERTS；轮换 CA 需要重启运行中的工作负载，Node 才会重新读文件。
第四块是严格模式的 MySQL TLS。文档把「加密」和「证书身份校验」拆开讲：sslaccept=accept 只开 TLS 不验链，只适合冒烟测试或过渡；sslmode=require 是加密，但别把它描述成证书身份校验；真正做验证的是 sslmode=verify-ca、sslmode=verify-full 和 sslaccept=strict，要配上正确的 CA 包，通常通过 Helm 的 customCa 给。
代理这边有条硬时序：Den 跑在 Node.js 24.5 及以上时，NODE_USE_ENV_PROXY=1、HTTPS_PROXY、NO_PROXY 必须在进程启动前配好，在浏览器里或应用内环境编辑器里设已经晚了。
四、诊断提示词：把排查交给 Agent，但按阶段收口
另一条线的设计取向很有意思：既然 Agent 本来就能读配置、探服务器、当场验证修复，那就把排查过程写成可直接粘贴的提示词，让它自己走。文档明说这些提示词默认是安全的——先收集证据、脱敏、改动前先问你。
第一组针对「云端能力变旧或不见了」。它分六个阶段：Phase 1 取证，打出所有能找到的配置里 openwork-cloud 那条的 url，并检查两个可能在设置界面底下悄悄覆盖服务器地址的文件——~/.config/openwork/desktop-bootstrap.json 和 macOS 上的 ~/Library/Application Support/com.differentai.openwork/desktop-bootstrap.json，而且只准报 baseUrl、apiBaseUrl、requireSignin、writtenAt 这几个字段，绝不打印带凭据的字段；Phase 2 直接探两个服务器做对比；Phase 3 通过自己的 MCP 工具取带内地面真相；Phase 4 判定你身处哪个世界；Phase 5 才是修，每一步破坏性操作前确认；Phase 6 在新会话里复验。通过态的标准写得很死：那条 url 指向你真实的服务器且以 /mcp/agent 结尾，execute_capability 对已知能力返回数据或一条可行动的连接提示，而不是 unknown_capability。
第二组针对「MCP 配着但工具不见了」。它更谨慎，整段是纯取证：不改配置、不登录登出、不重启服务、不打印配置文件内容。做法是先在当前任务里硬试着调 openwork-cloud_search_capabilities 和 openwork_extension_list_actions，记录运行时到底接不接受这次调用——文档特意提醒，别从模型对「列出你的工具」的回答去推断工具可用性，模型会漏报也会编。然后找到桌面应用真正用的那个 OpenCode 可执行文件（优先 resources/sidecars 里自带的那个，别拿 PATH 上同名的顶包），找到 server.json 旁边生成的 runtime-opencode-config.json，只报路径、是否存在和最后修改时间，绝不解析或摘要其内容——因为里面可能有 Authorization 头。最后临时给子进程设 OPENCODE_CONFIG，跑一次 opencode mcp list 做新进程探测。
文档在这里反复提醒：这只是新进程探测，别声称它连上了 OpenWork 里正在跑的那个 OpenCode 服务。收尾给了一张交叉判定表，把新进程探测结果和应用内状态两两组合，定位边界落在生成配置/端点/token/TLS/认证、活引擎注册与工作区路由、任务的工具快照，还是模型的选工具倾向。用两个独立信号交叉定位，比死盯一个报错有用得多。
五、这套东西由哪些部分组成
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| Windows 网络体检脚本 | 只读体检 DNS/TCP 443/TLS 链/代理，给出判决词 | scripts/support/openwork-doctor.ps1 | 登录页都打不开、TLS 报错、疑似被代理拦 |
| 网络诊断文档 | 讲清判决词怎么读、云目录诊断与 Den 出站诊断怎么开 | packages/docs/start-here/network-diagnostics.mdx | 拿到脚本输出但不知道下一步查哪 |
| 证书与代理文档 | 四个信任面的划分、自动链修复、严格 MySQL TLS | packages/docs/start-here/certificate-trust-and-proxies.mdx | 企业内网做了 TLS 解密，或自建 Den 走 Helm |
| 诊断提示词集 | 分阶段的可粘贴排查脚本，交给 Agent 自己跑 | packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx | 网络通但能力变少、工具不见了 |
| 出站访问清单 | 按组件列目标主机、必需级别、被挡了会坏什么 | packages/docs/start-here/outbound-network-access.mdx | 找 IT 报白名单之前 |
| 出站清单的机器可读源 | 主机元数据的归属点，CI 用脚本守着 | docs/enterprise/outbound-access.json、scripts/check-outbound-access.mjs | 你要把白名单接进自动化 |
顺带说下这个仓库的体量，方便你判断要不要跟着源码走：全仓 3490 个受版本控制文件，apps/ 4 个、packages/ 12 个，企业侧 ee/apps/ 10 个、ee/packages/ 3 个；文档 packages/docs/ 有 57 份 mdx，其中 model-context-protocol/ 下 10 份是各客户端接入指南；架构文档 docs/ 20 份 md，evals/ 26 份流程 md；apps/server/src/ 顶层就有 138 个 .ts 文件；packaging/ 下提供三种分发方式。
许可证这件事必须说准：这个仓库是分层授权的——根 LICENSE 写明，/ee 目录下的内容按 ee/LICENSE 定义的许可证（该文件自己的标题是 Functional Source License, Version 1.1, MIT Future License，缩写 FSL-1.1-MIT，根 LICENSE 里称其为 Fair Source License），第三方组件按各自原始许可证，此外的部分才是 MIT（Copyright 2026 Different AI）。上面表里凡是涉及 Den、团队控制面、企业能力的部分，多数落在 ee/ 这一侧。能不能商用、能不能改，以许可证原文为准，本文不提供法律意见。
六、边界与代价：它明确不管的事
这套排查体系的取向是「先证据后动作」，代价也在这里。
它不替你做修复决策。 网络自查脚本是只读的，判决词后面跟的是「第一个该查的修复方向」，不是自动修。证书链不完整这类问题，文档明确要求先修服务端证书包。桌面端那个自动链修复是唯一的例外，而且适用面被刻意收窄了：只处理仅缺 AIA 指向的中间证书这一种情况，拒绝私有或企业根，其它任何 TLS 失败一概不碰。
它不掩盖凭据集中带来的暴露面。 用这类工具意味着你的机器上装了桌面应用，它代管模型凭据、持有第三方服务的授权，还可能连到团队控制面。诊断提示词里那些「绝不打印 bearer token、Authorization 值、cookie、密码、API key、本地服务器 token 和以 ow_mcp_at_ 开头的字符串」的约束，恰恰说明这些东西就在你本地配置里躺着。你得自己评估：谁能读这台机器的用户数据目录、组织管理员在控制面那边能看到什么、哪些连接是「以你的身份」建立的。
云目录诊断默认不信任你的自建源。 Settings → Debug 里那个云目录诊断会探 openwork-cloud 这条托管 MCP 条目，验证 Cloud 恰好暴露 search_capabilities 和 execute_capability 这两个工具。自建 Den 源要先设 OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS，值是逗号分隔的裸源列表（只含 scheme、host、可选端口），除环回地址外必须用 https:。源不在信任列表里时诊断直接跳过，不向未信任源发带凭据的请求，Cloud MCP 本身不受影响。这个变量还必须在 OpenWork 启动前由启动器、MDM 配置、服务包装器或 shell 环境设好，因为应用内的环境变量存储会剔掉 OPENWORK_* 和 OPENCODE_* 开头的键。
Den 出站诊断是人工触发的，不是后台依赖。 默认诊断源是 https://diagnostic.openworklabs.com，由工作区所有者或超级管理员发起。文档要求诊断用的 token 必须是合成的、至少 24 个字符，明确写了不要拿服务商或客户的真凭据去跑。要换成内部诊断源，就把诊断应用部署在内部可达的受支持运行时上，然后给 Den 设 DEN_DIAGNOSTICS_ORIGIN 和 DEN_DIAGNOSTICS_BEARER_TOKEN；文档同时提醒别想当然套一个通用的 Kubernetes 部署方式，除非你的部署路径已经验证过。
它不管模型服务商那边的规则。 额度、限流、套餐分级这些机制会调整，以官方最新说明为准，排查线里不涉及。凭据这一侧的通用做法可以看API 密钥安全管理。
七、上手与避坑清单
别拿 PATH 上的同名可执行文件当桌面应用用的那个。 会踩是因为很多人本机早就装过 OpenCode，一敲命令自然用它。躲法是照第二组提示词的要求，先定位桌面应用 resources/sidecars 里自带的那个可执行文件，用绝对路径跑；有多个构建同时在跑而又无法安全确认时，宁可如实报告存在歧义，也别猜。
别把新进程探测的结果说成活引擎的状态。 会踩是因为 opencode mcp list 的输出看起来太权威了。它起的是全新进程，跟 OpenWork 里正在跑的那个服务不是一回事。躲法是把它和应用内的实时状态放一起看：Settings → Extensions 里点 Refresh，再点 Show hidden，在 Your apps 下找到 OpenWork Cloud Control 那一行，展开看它是 Ready、Issue、Sign in needed、Offline 还是 Paused。两个信号交叉才有结论。
别忽略 desktop-bootstrap.json。 会踩是因为它在设置界面底下悄悄覆盖服务器地址，你在 UI 上怎么看都是对的。躲法是排查一开始就把这个文件列进取证清单；确认里面是过期或 localhost 地址后，先展示再删。删完还得看看那个旧的本地服务进程是不是还在监听端口，不然它还能继续给出旧答案。
别只重启不新建任务。 会踩是因为任务持有的是它建立那一刻的工具快照。文档给的收尾动作是完整的一串：重启应用、在受影响工作区点 Refresh、从命令面板跑 Reload OpenCode config、然后开一个新任务，最后在新会话里复验探测。少一步都可能让你以为没修好。
别在应用内环境编辑器里设那些进程启动前才生效的变量。 会踩是因为界面上就有这个入口，看着像正路。OPENWORK_* 和 OPENCODE_* 会被应用内环境存储剔掉，Den 的代理变量也属于进程启动设置。躲法是统一在启动器、MDM 或服务包装器里配。
别忘了 GitHub 下载会跳走。 会踩是因为 IT 只放行了 github.com，结果下载到一半失败。发布资产当前的重定向目标是 release-assets.githubusercontent.com，旧客户端和回滚路径还会走 objects.githubusercontent.com，两个都得放。另外打包版桌面端会用 npx -y openwork-ui-mcp，registry.npmjs.org 被挡时应用能开但 UI 控制类 MCP 用不了；模型目录默认走 models.openworklabs.com，被挡了就用 OPENCODE_MODELS_URL 指向已批准的内部镜像。
别把提示词里的安全约束当客套话删掉。 会踩是因为想让 Agent 跑得利索点。那些「先取证、脱敏、改之前问我」的措辞，是这套提示词能安全交给 Agent 跑的前提，删掉之后你得到的是一个会直接改你配置的东西。相关取舍可以对照MCP 调试技巧里的思路看。
收束：一条自检顺序
真要用的话，顺序是这样的：先问自己失败在网络层还是运行时层；网络层就跑 openwork-doctor.ps1，拿判决词决定是修服务端证书链还是修客户端信任面；确认是 TLS 解密或私有根，回到四个信任面逐个核，别指望装一处全通；网络通了还不对，再上诊断提示词，按阶段取证、交叉判定、在新会话里复验。
接下来该读哪个文件？找 IT 报白名单之前先读 packages/docs/start-here/outbound-network-access.mdx，那份表按组件列了主机、必需级别和被挡了会坏什么；自建 Den 走 Kubernetes 的话，packages/docs/start-here/certificate-trust-and-proxies.mdx 里指向 Helm README 的 Custom CA 章节，才是低层取值和冲突规则的归属处。
最后说明一句：仓库 README 把这个项目定位成面向 macOS、Windows、Linux 的开源桌面应用，是 Claude Cowork 和 Codex 的开源替代——那是项目自己的说法，不是本文的判断。它和别的方案在设计取向上的差异，你可以从上面这些文档里自己看出来：它把「网络信任面」和「运行时工具注册」当成两个独立问题分开处理，并且把排查过程本身写成了可交给 Agent 执行的分阶段脚本。好处和代价，上面都写了。
本篇属于一个把开源AI 工作流桌面应用 OpenWork逐层拆开讲的系列，整体地图见 OpenWork 是什么：把技能与 MCP 打包成能力的开源桌面应用；沿着这条线往下，还可以看 开源桌面应用 OpenWork：工作流、设置共享、团队模板各自漏在哪 和 OpenWork 开源桌面应用上手：三条安装路线与第一次配置要交出什么。