志不强者智不达。——墨翟

Open Agents：一套会“自己干活”的云端编码代理参考应用（它不住在沙盒里，它指挥沙盒干活）

Open Agents 站在门口，像个带着工牌的工程队长，先把自我介绍写得清清楚楚：

它是一个 开源参考应用，用来在 Vercel 上构建和运行 后台（background）编码代理（coding agents）。它把你想要的关键部件都端上桌了：Web UI、Agent 运行时、沙盒（Sandbox）编排、GitHub 集成。

它还顺手提醒你一句，语气非常“我懂你要拿我去改造”的那种：

这个仓库的设计目标是：让你 fork 走、再按你的需求改，而不是把它当成一个黑盒产品供着。

它的 GitHub description 也很直给：

An open source template for building cloud agents.

换句话说：Open Agents 不是来当“成品”的，它更像一张 云端代理系统的工程图纸，你可以照着搭，也可以直接拿去改成你自己的代理工厂。

它是什么：三层结构，像一条干净的流水线

Open Agents 把自己拆成了三层，甚至画成了一行非常“工程师友好”的文字图：

1
Web -> Agent workflow -> Sandbox VM

它像一个会分工的团队：

  • Web：负责认证、会话、聊天、流式 UI（streaming UI）
  • Agent workflow：代理作为 durable workflow 在 Vercel 上运行，能多步执行、能持久化、能取消
  • Sandbox VM：执行环境，里面有文件系统、shell、git、dev server、预览端口

这三层各司其职，像一支配合默契的小队：一个负责对话和指挥，一个负责持久化决策与步骤推进，一个负责真正下场“敲命令、改文件、跑服务”。

核心决定：最重要的一句——“Agent 不是 Sandbox”

Open Agents 最关键的架构决策写得很硬：

The key architectural decision: the agent is not the sandbox

它强调一件事：

  • Agent 不运行在 VM 里
  • 它运行在沙盒外面，通过工具去和沙盒交互：读文件、编辑、搜索、跑 shell 命令……

这听起来像一句“位置描述”，但其实是一个会影响所有后续演进的底层选择。因为这带来了一整串非常现实的好处：

  • agent 的执行不绑定某一次请求生命周期（不再被请求/响应绑架）
  • sandbox 的生命周期可以独立休眠/恢复（你想让它睡就睡，想叫醒就叫醒）
  • 模型/供应商选择 与 sandbox 实现可以分别演进（两条腿走路，不互相拖死）
  • VM 保持“纯粹执行环境”，不会被迫变成控制平面（不让沙盒变成一个又重又复杂的指挥中心）

Open Agents 像个清醒的架构师：把“控制”和“执行”切开，让系统可以长期演进。

目前能做什么：它已经把“后台编码代理”的骨架搭好

Open Agents 现在的能力列表非常像一份“我已经能上岗”的简历：

  • chat 驱动的 coding agent：支持 file、search、shell、task、skill、web 工具
  • durable 多步执行：基于 Workflow SDK 的 runs，支持 streaming 和 cancellation
  • 隔离的 Vercel sandboxes：支持 snapshot-based resume（快照恢复）
  • 在沙盒里 clone repo、创建分支并工作
  • 可选：成功后自动 commit、push、创建 PR（auto-commit / auto-PR）
  • 通过只读链接分享会话（session sharing）
  • 可选：通过 ElevenLabs 做语音输入转写（voice input via transcription）

它不像那种“只能回答问题的聊天机器人”，它更像一个能被调度去干活的后台工人：能跑很久、能中断、能恢复、能把产物推回 GitHub。

运行时细节：它怎么跑得“像后台服务”而不是“像一次请求”？

Open Agents 在 Runtime notes 里把几个重要的实现习惯写得很清楚：

  • 聊天请求不是“直接在接口里跑 agent”，而是 启动一个 workflow run
  • 每一次 agent turn 都可以跨越多个持久化的 workflow steps
  • 如果你断线了，重新连上流，可以继续接到��有 workflow（resumed runs）
  • sandboxes 使用 base snapshot，开放端口 3000, 5173, 4321, 8000，并在闲置后 hibernate
  • auto-commit / auto-PR 是“偏好驱动”的能力，不是永远强制开启的行为

它像一个很懂“线上要活下去”的系统：考虑了中断、恢复、生命周期分离，也考虑了不把所有行为都硬编码成默认。

它真正需要什么：别猜，README 把“硬需求”写在墙上

Open Agents 没玩“装上就跑”的幻觉，它把“今天真实需要的东西”写得很直接，并明确说：

这些 requirements 基于当前 apps/web 的代码路径，而不是旧脚本。

最小运行时（Minimum runtime）

只要想让应用能启动并加载服务端状态，硬要求就两条：

1
2
POSTGRES_URL=
JWE_SECRET=

能登录并真正使用部署版（Vercel OAuth + token encryption）

如果你想让一个部署是“可用的”，需要加上 token 加密 + Vercel OAuth：

1
2
3
ENCRYPTION_KEY=
NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
VERCEL_APP_CLIENT_SECRET=

没有这些也能部署，但 Vercel sign-in 不会工作。Open Agents 很诚实：能跑不代表能用。

GitHub repo 访问、push、PR（GitHub App）

如果你想让用户连接 GitHub、给 repo/org 装 app、clone 私有仓库、push 分支、开 PR，那么需要这些 GitHub App 相关变量：

1
2
3
4
5
6
NEXT_PUBLIC_GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
NEXT_PUBLIC_GITHUB_APP_SLUG=
GITHUB_WEBHOOK_SECRET=

可选项（Optional）

1
2
3
4
5
6
REDIS_URL=
KV_URL=
VERCEL_PROJECT_PRODUCTION_URL=
NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=
VERCEL_SANDBOX_BASE_SNAPSHOT_ID=
ELEVENLABS_API_KEY=

其中几个也写得很明白：

  • REDIS_URL / KV_URL：可选 skills metadata cache（不配就回退到内存）
  • VERCEL_PROJECT_PRODUCTION_URL：给 metadata 和部分 callback 行为提供 canonical production URL
  • VERCEL_SANDBOX_BASE_SNAPSHOT_ID：覆盖默认 sandbox snapshot
  • ELEVENLABS_API_KEY：语音转写

把它部署到 Vercel：它像一本“可执行的上线路径”

Open Agents 的部署步骤不是那种“点点按钮就完事”的软糖，它更像一份做事清晰的 checklist：

  1. Fork this repo.

  2. 创建 PostgreSQL，拿到连接串。

  3. 生成 secrets：

    1
    2
    openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n'   # JWE_SECRET
    openssl rand -hex 32                                    # ENCRYPTION_KEY

  4. 把 repo 导入 Vercel。

  5. 在 Vercel 项目设置里至少加这些 env：

    1
    2
    3
    POSTGRES_URL=
    JWE_SECRET=
    ENCRYPTION_KEY=

  6. 先部署一次，拿到稳定 production URL。

  7. 创建 Vercel OAuth app，callback URL：

    1
    https://YOUR_DOMAIN/api/auth/vercel/callback

  8. 加 env 并 redeploy：

    1
    2
    NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
    VERCEL_APP_CLIENT_SECRET=

  9. 想要完整 GitHub-enabled coding-agent 流程：创建 GitHub App，并配置：

    • Homepage URL: https://YOUR_DOMAIN
    • Callback URL: https://YOUR_DOMAIN/api/github/app/callback
    • Setup URL: https://YOUR_DOMAIN/api/github/app/callback

    并在 GitHub App settings 里：

    • 启用 “Request user authorization (OAuth) during installation”
    • 用 GitHub App 的 Client ID/Secret 填 NEXT_PUBLIC_GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET
    • 如果想让 org installs 顺滑，建议把 app 设为 public

  10. 加 GitHub App env vars 并 redeploy。

  11. 需要的话再加 Redis/KV 和 canonical production URL vars。

它像一个项目经理一样，按顺序把你带到“能用的系统”，并且明确分层：先跑起来、再能登录、再能接 GitHub。

本地启动：它不花哨，但非常直

本地跑起来的姿势也很清爽，用的是 bun：

  1. 安装依赖：

    1
    bun install

  2. 创建本地 env：

    1
    cp apps/web/.env.example apps/web/.env

  3. 填好 apps/web/.env 中 required values。

  4. 启动：

    1
    bun run web

它甚至补了一句：如果你已经 linked 过 Vercel 项目，你当然可以 vc env pull，但现在刻意保持 setup 手动，是为了让你看清楚“哪些值真正重要”。

OAuth 与集成：它把回调地址写到你没法写错

Vercel OAuth

部署环境 callback：

1
https://YOUR_DOMAIN/api/auth/vercel/callback

本地开发 callback：

1
http://localhost:3000/api/auth/vercel/callback

对应 env：

1
2
NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=...
VERCEL_APP_CLIENT_SECRET=...

GitHub App

Open Agents 明确说：不需要单独的 GitHub OAuth App，直接用 GitHub App 的 user authorization flow。

GitHub App 配置：

  • Homepage URL: https://YOUR_DOMAIN
  • Callback URL: https://YOUR_DOMAIN/api/github/app/callback
  • Setup URL: https://YOUR_DOMAIN/api/github/app/callback
  • enable “Request user authorization (OAuth) during installation”
  • make public（如果你希望 org installs 更干净）

本地开发时：

  • callback/setup URL: http://localhost:3000/api/github/app/callback
  • homepage: http://localhost:3000

env：

1
2
3
4
5
6
NEXT_PUBLIC_GITHUB_CLIENT_ID=...   # GitHub App Client ID
GITHUB_CLIENT_SECRET=...           # GitHub App Client Secret
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY=...
NEXT_PUBLIC_GITHUB_APP_SLUG=...
GITHUB_WEBHOOK_SECRET=...

GITHUB_APP_PRIVATE_KEY 可以用 PEM（带转义换行）或 base64 PEM。

这部分像一个负责集成的工程师，站在你旁边一条条确认：“回调别写错、slug 别写错、secret 别漏。”

有用的命令：它把日常操作都摆在桌面上

1
2
3
4
5
bun run web
bun run check
bun run typecheck
bun run ci
bun run sandbox:snapshot-base

这几条命令像它的日常口头禅：

  • “跑起来”
  • “检查一下”
  • “类型过一遍”
  • “CI 跑全套”
  • “沙盒快���处理一下”

仓库布局：每个目录都像一个角色

Open Agents 把 repo layout 写得很干净，读起来就像在点名：

1
2
3
4
apps/web         Next.js app, workflows, auth, chat UI
packages/agent   agent implementation, tools, subagents, skills
packages/sandbox sandbox abstraction and Vercel sandbox integration
packages/shared  shared utilities

你能看出来它的边界感：

  • Web 是 Web：界面、认证、会话、工作流入口
  • Agent 是 Agent：工具、子代理、skills
  • Sandbox 是 Sandbox：抽象层 + Vercel sandbox 集成
  • Shared 是 Shared：共用工具箱

这也呼应了那句“Agent 不是 Sandbox”：结构上就把它们拆开了，让它们可以分别演进。

apps/web 里的 README：它很 Next.js，但它也有它的底线

apps/web 里还有一个 Next.js 的 README，它会提醒你最关键的一件事：

  • POSTGRES_URL 是必需的，并且 build 时会跑 migrations（通过 lib/db/migrate.ts 在 next build 期间自动执行）

它也给出了常见的 dev server 启动方式（npm/yarn/pnpm/bun）：

1
2
3
4
5
6
7
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

结尾：Open Agents 更像“参考实现 + 可改造模板”，而不是一个黑盒产品

Open Agents 整个 README 给人的感觉很像一个成熟的系统在自我介绍：

它不炫技，它不吹“全自动”，它把边界、假设、必需条件、可选能力、演进方向写得清清楚楚。

它的态度也很明确：

  • 这是一套可以 fork 并改造的参考应用
  • 它把 Agent workflow 和 Sandbox VM 分离
  • 它专注于“后台、可持久化、可恢复”的运行方式
  • 它把 GitHub 集成（clone/push/PR）当成可扩展能力，而不是强行绑死的默认动作

如果你想搭一个“云端后台编码代理”的系统，Open Agents 就像一位不啰嗦但很可靠的领班，递给你一套已经打磨过的工具、流程、结构，然后说：

“拿去 fork，改成你自己的。别把我当黑盒——你要的是一座能持续扩建的工厂。”