5 分钟搭建 OpenBot 开发环境:Bun 工具链与依赖安装完整教程
5 分钟搭建 OpenBot 开发环境:Bun 工具链与依赖安装完整教程
OpenBot 是一个本地优先(local-first)的 AI 队友桌面工作区,支持 Codex、Claude、Grok 等 Agent 独立工作区、任务队列与浏览器控制。本文带你用 5 分钟完成 OpenBot 开发环境搭建:安装 Bun 工具链与 Node.js 24,一条命令安装全部依赖,并启动开发服务跑通整个项目。
一、环境准备:OpenBot 开发环境最低要求
在开始之前,请确认你的电脑满足以下 3 个条件:
| 工具 | 版本要求 | 说明 |
|---|---|---|
| Bun | 1.4.2(稳定版) | 包管理器 + 运行时,package.json 中通过 packageManager: bun@1.4.2 锁定 |
| Node.js | 24 | 与 .nvmrc 一致,对应 Electron 内置的 Node 版本 |
| Git | 任意较新版本 | 用于克隆仓库与安装 git hooks |
💡 注意:Bun 版本必须精确匹配。项目使用
--frozen-lockfile安装,版本不一致会直接报错,这也是保证团队依赖一致的关键。
二、一键安装 Bun 1.4.2 工具链
🍎 macOS / Linux(一条命令安装指定版本):
curl -fsSL https://bun.com/install | bash -s "bun-v1.4.2"
🪟 Windows(PowerShell):
iex "& {$(irm https://bun.com/install.ps1)} -Version 1.4.2"
随后配置 Node.js 24(以 nvm 为例,自动读取 .nvmrc):
nvm install
nvm use
验证安装结果:
bun --version # 应输出 1.4.2
node --version # 应输出 v24.x
三、克隆仓库并运行 bun install 安装依赖
在 5 分钟流程里,这是耗时最长的一步(首次安装会下载 Electron 运行时):
git clone https://gitcode.com/GitHub_Trending/openbo/openbot.git
cd openbot
bun install --frozen-lockfile
安装过程中,Bun 会自动执行 package.json 中定义的两个钩子:
prepare:运行 scripts/install-git-hooks.ts,安装 pre-commit 钩子,提交时自动执行 Biome 格式检查与增量类型检查;postinstall:运行 scripts/install-electron.ts 下载 Electron 运行时,并缓存到本机目录(macOS 为~/Library/Caches/OpenBot/electron-dist)。之后在 git worktree 中重复安装几乎不占额外磁盘空间。
理解 bunfig.toml:OpenBot 的依赖安全机制
bunfig.toml 里配置了几个值得新手了解的策略:
exact = true:所有依赖精确锁定版本,杜绝隐式升级;minimumReleaseAge = 259200:拒绝安装发布时间不足 3 天的版本,规避恶意发包风险(恶意发布通常几天内就会被移除);trustedDependencies:仅electron-winstaller、esbuild、workerd三个包允许执行安装脚本,其余依赖的 install 脚本一律被拦截。可用bun pm untrusted查看被拦截的脚本。
四、验证 Agent CLI:codex:doctor 最快自检方法
OpenBot 通过本地 CLI 进程驱动 Codex、Claude、Grok 等 Agent(运行时版本清单见 native-runtime.lock.json)。安装完成后,先做一次快速体检:
bun run codex:doctor
该命令会检查 CLI 版本、App Server 握手和登录状态,但不会真正发起一次模型对话,因此不消耗额度。如果你使用 Computer Use(电脑操作)功能,还可以额外运行 bun run cua-driver:doctor。
📌 如果某个 provider 尚未登录,无需在终端处理:应用内选择 Download 即可让 OpenBot 自动下载并固定对应 CLI 版本,详见 docs/architecture/providers.md。
五、启动开发服务:bun run dev 跑通 OpenBot
一切就绪后,启动命令只有一条:
bun run dev
这个命令由 scripts/dev-services.ts 驱动,一次拉起三套服务:本地 Auth API(D1 数据库)、Signal 服务、Electron 客户端(带渲染进程 HMR 热更新)。它还有几个对新手很友好的自动行为:
- 仅在
bun.lock、workspace 的package.json、补丁文件或数据库迁移有变更时,才重新执行bun install --frozen-lockfile和api:migrate:local; - 每个 git worktree 拥有独立端口与独立开发配置文件,互不冲突;
- 首次启动会自动填充演示数据,你打开的就是一个有内容的工作区。
如果想像官方演示数据一样看到丰富的 Agent 对话与频道示例,可以注入种子数据后用共享配置启动:
bun run dev:seed
bun run dev --shared
六、常用开发命令速查表
| 命令 | 作用 |
|---|---|
bun run dev |
启动 Auth API + Signal + Electron 客户端(日常开发主入口) |
bun run dev:stop |
安全停止当前 worktree 的整套开发服务(按进程记录停止,不会误杀其他 worktree) |
bun run dev:reset |
删除本地开发配置文件(含 openbot.db),重置开发状态 |
bun run dev:bootstrap |
新建 git worktree 后一键补齐依赖、迁移数据库并注入种子 |
bun run dev:status |
以 JSON 打印本机所有开发服务、端口与进程状态 |
bun run check |
完整检查:Biome lint、双端类型检查、离线测试、浏览器冒烟测试与生产构建 |
bun run test:backend |
只运行后端测试 |
bun run typecheck |
并行检查全部 15 个子项目的类型 |
⚠️ 停止服务请始终使用
bun run dev:stop,不要用pkill -f electron——在多 worktree 机器上它会杀掉其他检出的任务。
更多命令说明见 README 的 Commands 部分,检查体系的设计细节可参考 docs/development-checks.md。
七、常见问题快速排查(FAQ)
Q1:bun install 报版本不匹配?
确认 Bun 是 1.4.2(bun --version)。项目通过 packageManager 字段锁定版本,旧版 Bun 会拒绝执行。
Q2:首次安装特别慢 / 卡在 Electron 下载?
这是正常现象。postinstall 需要下载 Electron 二进制,脚本对 429/5xx 错误会自动重试。macOS 上第二次安装会直接命中本机缓存,几乎秒装。
Q3:为什么某些依赖的 install 脚本没有执行?
这是安全设计:只有 package.json 中 trustedDependencies 列出的包可以运行安装脚本,用 bun pm untrusted 可以查看被拦截的清单。
Q4:Node 版本报错?
项目要求 Node 24(package.json 的 engines 与 .nvmrc 均为 24)。用 nvm use 切换即可,不要用全局高版本 Node 直接跑。
Q5:Agent 无法对话? 先确认对应 CLI 已登录。开发者也可以像普通用户一样,在应用内选择 Download 让 OpenBot 托管下载 CLI,避免手动版本错配。
八、下一步:开始贡献
环境跑通之后,建议完整阅读 CONTRIBUTING.md 了解代码规范——项目统一使用 Biome 作为唯一的 lint 与格式化工具(并加载仓库内 GritQL 自定义规则),类型检查基于 TypeScript 7。开发时随时可用 bun run dev:verify 生成当前 worktree 的检查计划。
恭喜!🎉 你现在已拥有完整可运行的 OpenBot 开发环境,接下来可以尝试修改 src/renderer 中的 SolidJS 界面,或深入 src/backend 查看各 provider 适配器的实现。


