5 分钟搭建 OpenBot 开发环境:Bun 工具链与依赖安装完整教程

原创2026-10-27 20:59:481,865 阅读
文章标签:桌面应用AI Agent人工智能多智能体代码智能体浏览器控制本地部署MCP 服务

5 分钟搭建 OpenBot 开发环境:Bun 工具链与依赖安装完整教程

OpenBot 是一个本地优先(local-first)的 AI 队友桌面工作区,支持 Codex、Claude、Grok 等 Agent 独立工作区、任务队列与浏览器控制。本文带你用 5 分钟完成 OpenBot 开发环境搭建:安装 Bun 工具链与 Node.js 24,一条命令安装全部依赖,并启动开发服务跑通整个项目。

OpenBot 桌面 AI 工作区开发环境概览插图

一、环境准备: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)。安装完成后,先做一次快速体检:

OpenBot 支持的 Codex AI Agent 运行时配图

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

OpenBot 集成 Claude Code 等 AI Agent 运行时配图

这个命令由 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 适配器的实现。

登录后查看全文
openbot