02 安装与桌面/服务端双启动

02 安装与桌面/服务端双启动

本节摘要:环境就绪后,本节做两件事——把 OpenWork 装上,然后启动它。这里的关键认知是:OpenWork 跑起来时,桌面外壳和本地服务端会同时启动并协作——你看到的界面是桌面外壳(React 单页应用跑在 Electron 渲染进程里),但真正干活的「中枢」是本地服务端。本节带你走完「克隆 → 装依赖 → 启动」,并解释这个「双启动」背后谁在干什么。

一、克隆与装依赖

OpenWork 源码是一个 Git 仓库,第一步是克隆它,然后用 pnpm 装依赖:

# 概念性示例:克隆与装依赖
git clone <仓库地址>
cd openwork

# 用 pnpm 装依赖(必须是 pnpm)
pnpm install
​

装依赖这一步会比较慢,原因前面说过——前端栈重、有原生依赖要编译、有补丁要应用。这是正常的,耐心等。

⚠️ 别用 npm 或 yarn:哪怕你平时习惯用 npm,这里也必须用 pnpm。用错包管理器,工作区的链接会错乱,依赖装不全,后面一堆「找不到模块」。如果已经用错了,删掉依赖目录和锁文件,重新用 pnpm 装。

二、启动:桌面形态(最常用)

最常用的启动方式是桌面形态——一条开发命令同时拉起桌面外壳、本地服务端、底层引擎:

# 概念性示例:开发模式启动桌面形态
pnpm dev
​

这条命令背后做的事比你想象的多。它实际触发的是「桌面应用」这个包的启动,而桌面应用启动时又会:

1. 启动前端开发服务器(Vite)
2. 启动 Electron 主进程(桌面外壳)
3. 主进程生成并管理本地服务端子进程
4. 服务端反向托管底层引擎(OpenCode)

所以你敲一条命令,实际上有四个东西在跑,它们通过 HTTP 和 IPC 通信:

pnpm dev
   ├─ 前端开发服务器(Vite)
   ├─ Electron 主进程(桌面外壳)
   │    └─ 生成管理 ──► 本地服务端
   │                       └─ 反向托管 ──► 底层引擎(OpenCode)
   └─ 你看到的桌面窗口
​

💡 为什么要这么复杂:因为 OpenWork 的核心设计是「服务端消费优先」(第 2 章)——桌面外壳只是服务端的客户端,真正的中枢是服务端。所以启动桌面时,服务端必须一起起来。这种「一条命令拉起整套」的设计是为了让你不用手动协调多个进程。

三、启动:纯服务端形态(无桌面)

有时你不需要桌面界面,只想起服务端(比如做自动化、做集成测试、或在无头服务器上跑)。这时可以单独启动服务端形态:

# 概念性示例:单独启动服务端
# 具体命令以本地版本为准,通常在服务端包目录下
​

纯服务端形态下,没有 Electron、没有桌面窗口,只有 HTTP 服务。你可以用任何 HTTP 客户端(包括浏览器访问前端、或别的 Agent 通过 MCP)来调它。这种形态是第 3 章「服务端核心」和第 7 章「meta-MCP」的主要研究对象。

四、启动:企业 Den 形态(高级)

如果你要跑企业版(Den),那是另一套启动方式——需要 Docker 起 MySQL,然后分别起 den-api、den-web、inference 等多个服务。根目录提供了编排脚本:

# 概念性示例:启动 Den 本地开发(需要 Docker)
pnpm dev:den
​

这条命令会编排多个服务(MySQL、后端 API、Web 控制台、推理代理)。这是第 12 章「企业控制平面」的主题,第一次接触不用碰它——先把桌面形态跑通再说。

⚠️ 新手建议:第一次启动,只用 pnpm dev(桌面形态)。Den 形态涉及 Docker 和多个服务,复杂度高,等你对基础架构熟了再碰。

五、验证启动成功

怎么知道启动成功了?几个信号:

如果桌面窗口弹出来了、能看到界面,基本就成功了。如果卡住或报错,回到第 01 节的自检清单排查——最常见的是运行时版本不对或原生依赖没编译成功。

六、第一次启动后该做什么

启动成功后,别急着干别的,先做这两件事:

1. 创建或打开一个工作区:工作区是 OpenWork 的基本单元(一个项目目录)。先打开你熟悉的一个项目,作为后续操作的场地。
2. 观察界面布局:熟悉一下界面——会话区、工作区切换、设置入口。这些是后续章节的实操起点。

七、本节没讲的

本节刻意没讲:如何接入一个 Agent、如何发起第一次会话、Den 的详细启动。这些是后面几节(或后面章节)的主题。本节的目标只有一个:让你把 OpenWork 装上、桌面形态跑起来、看到界面。

本节要点回顾

1. 装依赖用 pnpm,别用 npm/yarn;慢是正常的(前端重 + 原生依赖 + 补丁)。
2. 桌面启动一条命令拉起四样:前端开发服务器、Electron 主进程、本地服务端、底层引擎。
3. **「一条命令拉起整套」**是因为服务端消费优先——桌面是服务端的客户端,服务端必须一起起来。
4. 纯服务端形态适合自动化/集成/无头场景;Den 形态是企业版,新手先别碰。
5. 验证成功:桌面窗口弹出、界面可操作,基本就成功了。
6. 启动后先做:创建/打开工作区、熟悉界面布局——为后续实操做准备。

跑起来之后,OpenWork 的价值在于「跨工具复用」——下一节讲如何把你的 Agent 接进来。