企业官网建设流程全解析

Open Agents部署Vercel完全指南：一次搞定从Fork到生产

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents

Open Agents 是一个开源的云端编码智能体（Coding Agent）参考应用，包含 Web 界面、Agent 运行时、沙箱编排与 GitHub 集成。本文带你用 Vercel 部署 Open Agents，从 Fork 仓库到生产环境一次搞定，全程无需本地服务器，几小时内即可拥有属于自己的 AI 编码代理平台。

30秒认识 Open Agents：为什么值得自己部署

Open Agents 采用三层架构，用一句话概括就是：Web → Agent → 沙箱 VM。

• Web 层：负责登录认证、会话管理、聊天界面与流式输出
• Agent 层：以持久化 Workflow 的形式在 Vercel 上运行，可跨请求持续执行多步任务
• Sandbox 层：独立的执行环境，提供文件系统、Shell、Git 和开发服务器

架构中最关键的设计是：Agent 不运行在沙箱 VM 里，而是位于沙箱之外，通过读文件、编辑、搜索、Shell 命令等工具与沙箱交互。这样 Agent 的执行不受单次请求生命周期限制，沙箱也可以独立休眠与恢复。更多细节见 docs/agents/architecture.md。

部署前准备：一键 Fork 仓库

Open Agents 是一个 Turborepo Monorepo，核心目录结构如下：

apps/web Next.js 应用（工作流、认证、聊天界面） packages/agent Agent 实现、工具、子代理、技能 packages/sandbox 沙箱抽象与 Vercel 沙箱集成 packages/shared 共享工具

第 1 步：在 GitCode 上 Fork 本项目（点击右上角 Fork 按钮即可）。

第 2 步：将 Fork 后的仓库导入 Vercel。在 Vercel 控制台选择 "Add New → Project"，导入你的 Fork 仓库。如果使用仓库 README 顶部的一键部署按钮，Neon Postgres 数据库会自动供给，省去手动建库的麻烦。

💡 提示：官方提供了一个引导部署页面，源码见 apps/web/app/deploy-your-own/page.tsx，其中预定义了全部需要配置的环境变量清单，可作为核对表使用。

第一步：数据库与最小运行环境变量

部署 Open Agents 最少只需要两个环境变量：

在 Vercel 项目设置的 Environment Variables 中填入这两项。

部署时有一个省心设计：数据库迁移会在构建阶段自动执行。迁移逻辑位于 apps/web/lib/db/migrate.ts，每次 Vercel 部署（无论是预览还是生产）都会自动应用待执行的迁移，你完全不用手动跑 SQL。

此外，项目开启了 Neon 数据库分支隔离——每个预览部署会自动分叉出独立的数据库分支，预览环境绝不会读写生产数据。这一点在团队协作调试时非常重要。

完成第一次部署后，先访问你的生产 URL 确认首页能正常打开。

第二步：配置 Vercel OAuth 登录

没有登录配置，用户无法进入系统。这一步只需 3 分钟：

1. 在 Vercel 创建 OAuth App，回调地址填：

   https://你的域名/api/auth/callback/vercel

2. 将生成的 Client ID 和 Secret 填入环境变量：
   • NEXT_PUBLIC_VERCEL_APP_CLIENT_ID
   • VERCEL_APP_CLIENT_SECRET
3. 重新部署

认证由 Better Auth 驱动，所有认证路由统一由/api/auth/[...all]通配路由承接，配置入口在 apps/web/lib/auth/config.ts。本地开发时回调地址使用http://localhost:3000/api/auth/callback/vercel。

第三步：接入 GitHub App，解锁完整编码代理能力

想让 Open Agents 真正"干活"——克隆仓库、改代码、提交并开 PR——需要创建 GitHub App：

三个关键细节：

• 不需要单独创建 GitHub OAuth App：Open Agents 直接复用 GitHub App 的 OAuth 凭证作为 Better Auth 的社交登录提供方，再用 App 的安装令牌访问仓库
• 建议将 App 设为公开，这样组织安装会更顺畅
• GITHUB_APP_PRIVATE_KEY可以是转义换行的 PEM 原文，也可以是 Base64 编码的 PEM

然后填入 6 个环境变量并重新部署：

NEXT_PUBLIC_GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET= GITHUB_APP_ID= GITHUB_APP_PRIVATE_KEY= NEXT_PUBLIC_GITHUB_APP_SLUG= GITHUB_WEBHOOK_SECRET=

完整的变量注释说明都在 apps/web/.env.example 中，对照填写不会出错。

✅ 到这一步，你的生产环境已具备：登录 → 创建会话 → Agent 在云端沙箱改代码 → 自动提交 / 开 PR 的完整链路。

可选优化：让部署更顺手

以下环境变量均为可选，按需添加：

沙箱的休眠与恢复由独立的生命周期 Workflow 管理：空闲 30 分钟后自动快照休眠，用户点 Resume 即可恢复。完整状态机说明见 apps/web/SANDBOX-LIFECYCLE.md，参数配置在 apps/web/lib/sandbox/config.ts。

本地开发调试：3 条命令跑起来

线上部署完成后，本地迭代体验也很顺滑：

bun install # 安装依赖（项目统一使用 Bun） cp apps/web/.env.example apps/web/.env bun run web # 启动开发服务器

如果本地已有关联的 Vercel 项目，直接用vc env pull拉取线上环境变量到本地，避免重复填写。修改数据库 schema 后记得生成迁移文件并提交（规则详见 AGENTS.md），构建时会自动执行。

常见问题排查

Q：部署成功但登录按钮没反应？检查回调 URL 是否与你的生产域名完全一致（含https://），并确认已重新部署使新的NEXT_PUBLIC_前缀变量生效。

Q：GitHub 连接后无法访问仓库？确认 GitHub App 已安装到目标仓库，且拥有 contents 读写权限；组织仓库还需确认 App 已设为公开并完成组织安装。

Q：沙箱总是很快休眠？Hobby 套餐的沙箱硬超时只有 40 分钟，生产场景建议保持标准资源配置，或设置VERCEL_SANDBOX_BASE_SNAPSHOT_ID加速恢复。

总结：你的 Open Agents 已上线 🎉

回顾整个部署路径：Fork 仓库 → 导入 Vercel（自动供给 Neon 数据库）→ 配置最小环境变量 → 部署获得稳定生产 URL → 配置 Vercel OAuth → 配置 GitHub App → 可选优化项。

Open Agents 的定位不是黑盒，而是拿来 Fork 后二次开发的模板：Agent 逻辑在 packages/agent/，沙箱抽象在 packages/sandbox/，Web 层在 apps/web/。想加新工具、换模型、改子代理策略，都可以直接改源码后重新部署。

完整项目说明参见 README.md，祝部署顺利！

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents