OpenWork 开源桌面应用上手：三条安装路线与第一次配置要交出什么

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

装 OpenWork 这个开源桌面应用最容易被忽略的一点是：三条安装路线并不是同一件事的三种皮肤，它们把「谁来持有身份」这个问题的答案排在了不同的位置。 手动下载桌面应用，是你先有账号再有工作区；命令行引导包 openwork-bootstrap 的 cloud bootstrap-workspace，是先建一个没有邮箱身份的临时工作区、把认领链接写到本地文件里等人来接管；让 Agent 按项目提供的引导文档替你装，则是把上面两步串成一条对话。选错路线不会装不上，但会在第二天你想把工作区交给团队时，多绕一圈。

这篇只钉住一件事：从零到跑通第一个工作区，这条动线上每一步在仓库里有据可查的行为，以及每一步要你交出什么。站内已有的 AI Agent 平台盘点 做的是横向选型比较，MCP 配置教程 讲的是协议层怎么接客户端，而 AI 绘画工具 属于另一条创作工具线、和本篇没有交集；本篇不做选型也不讲协议规范，只讲这一个仓库的装机与首次配置。

先说清命名：OpenWork 在本文中特指 different-ai 维护的这个开源桌面应用项目，跟同名的职场点评网站、以及中文里「开放工作」这种泛指没有任何关系。

一、这个项目先要你理解的两个词

仓库 README 这样定位自己：一个免费、开源、为分享 AI 工作流而做的桌面应用，覆盖 macOS、Windows 和 Linux，并把自己描述为 Claude Cowork 和 Codex 的开源替代。这是项目自己的说法，本文不替它背书，只作为理解它设计取向的入口——它的重心在「分享」，不在「再做一个聊天框」。

文档 packages/docs/start-here/do-work-with-it/skills-plugins-and-mcp.mdx 把可用单元切成三块：连接器（connector）负责触达邮件、日历、CRM、工单这些系统；技能（skill）是任务匹配时加载的书面指令；插件（plugin）是能被整体安装和分发的捆绑包。这份文档还写了一句很关键的实现细节：底层一切都是插件，你让 OpenWork 创建一个技能时，它实际创建的是一个只含这一个技能的小插件。所以「该建技能还是建插件」这个问题，对大多数人不成立。

第二个词是「能力」（capability）。README 写的是，OpenWork 的 MCP 服务端对外暴露两个工具：search_capabilities 用来找你能用的东西，execute_capability 用来执行它。这解释了为什么 packages/docs/start-here/connect-your-stack/connect-services.mdx 敢让你直接说「总结我最新的五封邮件」——Agent 先在你已登录账号的实时能力列表里检索，再去执行精确匹配到的那一条，而不是要你先背下某个 MCP 服务器名和工具名。

对你意味着什么：这个项目的第一次配置，本质是在填一张「你能调用什么」的清单，而不是在配一个模型客户端。清单填得越靠前，后面越省事。

二、三条安装路线，各自适合谁

packages/docs/start-here/get-started.mdx 给的默认建议是从桌面应用开始，连上你选的模型服务商，发出第一条消息。这条路线适合个人先自己试，路径最短，代价是身份和工作区都得你手动过一遍。

第二条是命令行引导包。packages/openwork-bootstrap/README.md 明确写了这个包的定位：一个可被脚本安装的 openwork-bootstrap 命令，用于「面向 Agent 的引导安装」，且刻意做得很小、不假设 npm 是安装渠道。它当前的能力范围只有四类：把这个轻量 CLI 装进用户可写的 bin 目录；按清单下载桌面应用产物并校验 SHA-256 摘要后安装；doctor 体检；以及 cloud onboard 驱动的无头 REST 开通流程。README 结尾还补了一句边界——这只是安装与云端开通层，真正的运行时托管走桌面应用、OpenWork Cloud 或 openwork-server。

第三条是让 Agent 替你装。README 的「Install with your AI agent」段落给的就是一句提示词，让 Claude Code、Cursor、Codex、ChatGPT 这类能在你电脑上执行命令的 Agent 去按官网托管的那份 start 指引走；这份指引的内容由 ee/apps/landing/app/start.md/route.ts 在服务端拼出来，与仓库里的 packages/openwork-bootstrap/start.md 是同一份说明书的两个投放位（步骤顺序略有差别，正文一致）。想提前知道 Agent 会照着做什么，直接读仓库里那份就行。它是写给 Agent 看的操作说明书，第一句话就是「你是一个帮用户安装并配置 OpenWork 的 Agent」。

三条路线怎么选，我的判断是这样：只想自己试，走桌面应用；要在多台机器或者给同事批量装、需要每步都有 --json 可断言的输出，走引导包；手边已经有一个能执行命令的 Agent、且你愿意让它读写你的 home 目录，走第三条。第三条最省力，但它把「审阅每条命令」这件事外包了，后面第五节会说这笔账。

三、拼图各块在仓库里的位置

把动线上会碰到的东西对齐到仓库真实路径，看起来是这样：

组成部分	它负责什么	对应仓库位置	你什么时候会碰到它
引导 CLI	install / install app / doctor / cloud 四组命令，单文件、无依赖	packages/openwork-bootstrap/bin/openwork.mjs	走命令行或 Agent 代装路线时的全程
Agent 安装说明书	写给 Agent 的分步流程、成功判据与失败上报要求	packages/openwork-bootstrap/start.md	让 Agent 替你装时，它读的就是这份
入门文档	桌面应用、Cloud、企业三种起步方式的分岔口	packages/docs/start-here/get-started.mdx	决定走哪条路线时
服务连接文档	Settings > OpenWork Connect 的点选流程与前置条件	packages/docs/start-here/connect-your-stack/connect-services.mdx	第一次接 Gmail、Slack、Notion 这类服务时
自定义 MCP 文档	Settings > Extensions > Add Custom App 与 OAuth 分支	packages/docs/start-here/connect-your-stack/add-an-mcp-server.mdx	组织没提供、你要自己接一个服务器时
安装包分发文档	组织安装链接如何交付标准安装包，含挂载产物与 MDM 路径	packages/docs/start-here/installer-delivery.mdx	在公司内网批量铺开时
安装配置 schema	desktop-bootstrap.json 的字段定义与文件名解析	packages/install-config/src/index.ts	排查桌面应用为什么没读到工作区时
分层许可证	根目录 MIT，/ee 另按 ee/LICENSE	LICENSE 与 ee/LICENSE	决定能不能改、能不能商用之前

顺带给个仓库体量的直观尺度，这些数你自己 clone 下来数得出来：全仓 3490 个受版本控制文件，apps/ 下 4 个应用、packages/ 下 12 个包，企业侧 ee/apps/ 10 个、ee/packages/ 3 个；文档 packages/docs/ 有 57 份 mdx，其中 model-context-protocol/ 下 10 份是各客户端的接入指南；evals/ 顶层有 26 份流程说明；apps/server/src/ 顶层 138 个 .ts；packaging/ 提供 aur、docker、helm 三种分发方式。

四、命令行引导包实际做的几件事

读 bin/openwork.mjs 比读 README 更能看清它的行为边界。

装 CLI 自身。 默认安装目录是 $HOME/.openwork/bootstrap，默认 bin 目录是 $HOME/.local/bin，两者都可以用 --install-dir、--bin-dir 覆盖，也认 OPENWORK_INSTALL_DIR 和 OPENWORK_BIN_DIR 两个环境变量。start.md 在「Constraints」一节明确要求不得需要管理员权限、优先用户本地路径。

按清单装桌面应用。 install app 需要一个 --manifest（或环境变量 OPENWORK_INSTALL_MANIFEST），从清单里选出匹配当前平台的产物，下载后算 SHA-256。如果清单里带了 sha256 字段而实测摘要对不上，它直接抛 checksum_mismatch 并把期望值和实际值都打出来，不会静默继续。支持的产物类型是 macOS 的 .dmg、.zip、.tar.gz/.tgz，Linux 的 .AppImage，以及 Windows 的 .exe/.msi 拷贝式安装。装完会在应用目录写一份 openwork-app-install.json，记录来源清单、产物 URL、实测摘要、平台与架构。

体检。 doctor 不是一句「ok」，它逐项落到具体检查名上：node（要求主版本不低于 20）、installDir、binDir、openworkExecutable、manifest；带 --base-url 时加 denApiHealth；带 --app 时加 openworkApp 和 appInstallManifest；带 --desktop-bootstrap 时加 desktopBootstrap、desktopBootstrapPrepared、desktopBootstrapHandoff。排障时看的就是这几个名字，比看整体布尔值有用得多。

建临时工作区。 start.md 第 3 步用的是 cloud bootstrap-workspace，它的设计意图写得很直白：为了让邮箱身份不阻塞桌面就绪，先建一个「provisional workspace」，不创建邮箱／密码账号，而是把认领链接写进本地的桌面引导文件，等人来认领所有权。这里有个容易踩的时序：邀请同事的邮件不会立刻发出去，因为临时工作区还没有已认证的所有者去代发，文档说这些邀请会在有人认领所有权的那一刻自动触发。

start.md 第 7 节还给了一份内部成功判据（它明确写了不要展示给用户，我这里只是转述其结构）：cloud bootstrap-workspace --json 的返回里要同时出现 organization.id、setup.id、skill.id，skillRun.triggered 为真且 skillRun.output 等于那个约定的触发标记，claimLinks[0].id 存在，desktop.prepared 为真、desktop.bootstrapPath 与 desktop.skillPath 都有值。桌面应用启动后应落在带绿色「Setup complete」横幅、显示组织名、「First skill ready」磁贴和「Claim this workspace」动作的引导页。你自己走命令行时，把这几项当验收清单用就行。

五、第一次配置要你交出哪些东西

这一节是本篇的重点，因为这类工具会在你机器上装桌面应用、代管模型凭据、并拿走第三方服务的授权。逐项说清楚。

模型服务商的登录态或密钥。 sign-in-with-chatgpt.mdx 写的路径是 Settings > Connect Provider > OpenAI > ChatGPT Pro/Plus，走 OpenAI 侧的 OAuth 登录；文档同目录下还有添加 Anthropic API key 和自定义 LLM 的说明。走 OAuth 意味着桌面应用拿到的是一个可持续调用的授权，走 API key 意味着一把长期密钥落在本机的应用配置里。两者的暴露面不同，但都属于「凭据集中保管」——一旦这台机器被人拿到，你的模型账单也一起被拿到。密钥这条线的通用做法，可以对照 API 密钥安全管理 那篇的原则来做。

办公套件与协作工具的 OAuth 授权。 connect-services.mdx 列的托管服务包括 Gmail、Google Calendar、Google Drive、Slack、Notion、Linear。这条路要求你先登录 OpenWork 账号并加入一个开启了 Connect 的组织——注意这跟登录模型服务商是两回事。授权完成后，服务会从 Needs your sign-in 自动挪到 Ready to use。这里要你想清楚的是数据流向：授权范围内的邮件正文、日程、云盘文件，都会作为上下文进入模型请求。what-uses-tokens.mdx 也从成本角度印证了这一点——用量随 Agent 需要读的上下文规模增长，长会话、粘贴的文本、文件附件、工具返回结果都算在内。

组织侧的可见性。 同一份文档把四个近义概念区分得很清楚：Connect 是桌面应用里成员自己看的连接页；Connections 是 OpenWork Cloud 里组织管理员用的看板，用来发布服务、决定用谁的账号、以及给成员或团队授权；OpenWork Connect MCP 是让外部 MCP 客户端使用组织能力的托管端点；Add an MCP server 才是自建服务器的进阶路径。也就是说，一旦你加入的是别人管理的组织，「这个连接用的是谁的账号」这件事可能不由你定。README 描述的 Den 控制面还能设置桌面策略、限制本地模型访问、控制组织可用的应用版本。这类企业侧能力属于 /ee 目录范畴，下一节会讲许可证。

落到你磁盘上的文件。 这是最该记住的一组路径。--prepare-desktop 会写一份 desktop-bootstrap.json；start.md 第 10 节的安全提示说得很明白：为了支持免密码的工作区引导，这份文件里包含短时效的认领链接，链接不会打印在最终输出里，而且这个文件是机器本地的，不要在机器之间拷贝、也不要提交进仓库。CLI 里对应的默认路径由 configHomeDir() 决定——优先 XDG_CONFIG_HOME，Windows 上用 LOCALAPPDATA（代码注释特意写了 Windows 上绝不用 ~/.config，以对齐 Electron 外壳的行为），其余走 $HOME/.config。在这个基础上，桌面引导文件落在 openwork/desktop-bootstrap.json，技能落在 opencode/skills，还有一份设备密钥 bootstrap-device-key.json。这三个路径分别可以用 OPENWORK_DESKTOP_BOOTSTRAP_PATH、OPENWORK_SKILLS_DIR、OPENWORK_DEVICE_KEY_PATH 覆盖。

接进你现有 Agent 的那一步。 README 给的远程 MCP 地址是 https://api.openworklabs.com/mcp/agent，Codex 用 codex mcp add openwork --url ...，Claude Code 用 claude mcp add --transport http openwork ...，加完客户端会开浏览器让你登录并选择组织。start.md 补了两条纪律：临时工作区必须先被认领，其所有者才能完成 MCP 认证；配置完要重启当前 Agent，且在重启后的客户端能看到 search_capabilities 和 execute_capability 两个工具之前，不要宣称连接成功。授权面收紧的通用思路，可参考 MCP 授权加固。

六、边界与代价：它明确不管的事

许可证是分层的，不能笼统说成 MIT。 根目录 LICENSE 写得很清楚：/ee 目录下的所有内容按 ee/LICENSE 定义的 Fair Source 许可证；其余部分才是 MIT（Copyright 2026 Different AI）。而 ee/LICENSE 的抬头是 Functional Source License, Version 1.1, MIT Future License，其许可授予明确排除「Competing Use」。前面提到的 Den 控制面相关应用都在 ee/apps/ 下。本文不提供法律意见，能不能商用、能不能改，一律以许可证原文为准。

计算机操作的范围比你想的窄。 control-the-browser.mdx 直接写明，OpenWork 的 computer-use 目前只通过内置的 OpenWork Browser 生效，还不等于对 Ubuntu、macOS 或 Windows 桌面应用的完整控制。它能开页面、点击、填表单、读页面内容、截图；如果你连的是远程 OpenWork 服务端，浏览器跑在那个远程 worker 上——这句话的另一面是，被截图的页面内容会离开你本机。

没有结果缓存。 what-uses-tokens.mdx 明说「今天没有结果缓存」，同一个任务重跑一次就是一次新的模型请求。别指望靠重复执行省钱。至于具体的计费与额度规则，会随服务商调整，以官方最新说明为准。

引导包不负责运行时。 README 自己划的线：它是安装与 Cloud 开通层，运行时托管交给桌面应用、OpenWork Cloud 或 openwork-server。所以别指望用 openwork-bootstrap 去做进程守护、日志轮转这类事。

内网铺开是另一套工程。 installer-delivery.mdx 讲的三种交付形态里，只有联网那一档是「Den 校验组织安装令牌后把浏览器重定向到 GitHub 发布产物」；半隔离和完全内网这两档要求你把标准安装包放进 OPENWORK_INSTALLER_ARTIFACTS_DIR 指向的挂载目录，由 Den 直接流式下发。文档同时提醒，即使安装包走内网，桌面运行时依赖仍可能需要外网，除非你做了镜像或关闭。多副本 Den API 部署还要求每个副本以相同路径挂同一个只读 PVC。这些都不是「装个应用」的量级。

它是别人的项目。 仓库里有路线图文档，但那是文档里这么写，不是承诺；本文也不替维护者做任何时间表判断。

七、上手与避坑清单

• 别把远程安装脚本直接管道进 shell。 start.md 给的示例是先 curl -fsSLo 下载到 /tmp，再 less 读一遍，最后才 sh 执行，并附了一句「不要把远程脚本直接管道进 shell」。会踩是因为一键命令确实更快；避法就是多这两步，尤其在你打算给同事推同一条命令的时候。
• 装完找不到命令，先查 PATH 而不是重装。 start.md 的失败处理明确写了这一条：如果 openwork-bootstrap 装完不可用，确认 $HOME/.local/bin 在 PATH 里，或者直接用全路径调用。会踩是因为默认 bin 目录在很多发行版的默认 PATH 之外；避法是先 openwork-bootstrap doctor --json 看 binDir 和 openworkExecutable 两项的实际值。
• Node 版本别用系统自带的老版本。 doctor 的 node 检查要求主版本不低于 20。会踩是因为不少机器上 node 指向的是包管理器装的旧版；避法是在跑 install 之前先确认版本，不然你会在后面某一步拿到看不懂的报错。
• desktop-bootstrap.json 绝不要跨机器拷贝或提交。 它含短时效认领链接。会踩是因为「把配置同步到另一台电脑」看起来是个自然操作；避法是在新机器上重跑一次引导流程，而不是搬文件。顺手把它加进你的 dotfiles 忽略规则。
• 邀请同事没收到邮件，先看工作区认领没有。 临时工作区没有已认证的所有者，邀请要等认领之后才自动发出。会踩是因为命令返回 ok 会让你以为邮件已经在路上；避法是把「认领」当成一个独立的必做步骤，而不是可选的收尾。
• 认领链接不要提前打印出来。 start.md 第 6 节要求只在用户明确说要认领时才去取链接，取到之后用 open 之类的方式直接打开，而不是把原始链接粘进聊天记录。会踩是因为把链接贴出来最省事；避法是记住它是短时效凭据，聊天记录会被留存和转发。
• MCP 加过一次就别重复加。 start.md 提示，如果已经存在 openwork 这一项，不要新增重复条目，改为对已有条目做认证；要换组织或修复失效的授权，先 logout 再 login。会踩是因为报错时人的本能是再加一遍；避法是先列一遍已有条目。
• 区分「登录模型服务商」和「登录 OpenWork 账号」。 文档里两次强调这是两件事。会踩是因为都在 Settings 里、都叫「登录」；避法是记住 Connect 那一页要求的是 OpenWork 账号加上一个启用了 Connect 的组织，跟你有没有 ChatGPT 订阅无关。
• 自建 MCP 服务器接不上，先看动态客户端注册。 add-an-mcp-server.mdx 说 Add Custom App 面向支持动态 OAuth 客户端注册的服务器；不支持的，要走 Add Custom App > Advanced OAuth 填预注册的 client ID 和 secret。会踩是因为报错信息容易被当成网络问题；避法是先确认对方服务器的注册方式。

收个尾

跑完一遍之后，用四个问题自检：doctor 的分项检查里有没有非 ok 的名字；desktop-bootstrap.json 是不是只存在于这一台机器上；模型服务商和 OpenWork 账号这两个身份你是不是分得清；以及，你授权出去的 Gmail、Drive、Slack 里，有没有你其实不希望进入模型上下文的内容。

接下来该读哪个文件，取决于你要往哪走。想把它接进现有 Agent，读仓库 README 里 MCP 那一节和 packages/openwork-bootstrap/start.md 的第 5、6 节；想理解技能与插件怎么组织，读 packages/docs/start-here/do-work-with-it/skills-plugins-and-mcp.mdx；想在公司内网铺开，packages/docs/start-here/installer-delivery.mdx 和 packages/docs/start-here/self-host.mdx 这两份要一起读，前者管安装包怎么到手，后者管 Den web、Den controller、推理服务这些组件怎么摆。而在动手改代码之前，先把 LICENSE 和 ee/LICENSE 两份都看完——这个仓库的边界，写在那里。

本篇属于一个把开源AI 工作流桌面应用 OpenWork逐层拆开讲的系列，整体地图见 OpenWork 是什么：把技能与 MCP 打包成能力的开源桌面应用；沿着这条线往下，还可以看 OpenWork 开源桌面应用连不上：先走网络自查线，再用诊断提示词 和 开源项目 OpenWork 不装桌面应用也能用：两个 MCP 工具接进 Agent。