vercel-labs/open-agents

# 开放代理 [](https://vercel.com/new/clone?project-name=open-agents&repository-name=open-agents&repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fopen-agents&demo-title=Open+Agents&demo-description=Open-source+reference+app+for+building+and+running+background+coding+agents+on+Vercel.&demo-url=https%3A%2F%2Fopen-agents.dev%2F&env=POSTGRES_URL%2CJWE_SECRET%2CENCRYPTION_KEY%2CNEXT_PUBLIC_VERCEL_APP_CLIENT_ID%2CVERCEL_APP_CLIENT_SECRET%2CNEXT_PUBLIC_GITHUB_CLIENT_ID%2CGITHUB_CLIENT_SECRET%2CGITHUB_APP_ID%2CGITHUB_APP_PRIVATE_KEY%2CNEXT_PUBLIC_GITHUB_APP_SLUG%2CGITHUB_WEBHOOK_SECRET&envDescription=Neon+can+provide+POSTGRES_URL+automatically.+Generate+JWE_SECRET+and+ENCRYPTION_KEY+yourself%2C+then+add+your+Vercel+OAuth+and+GitHub+App+credentials+for+a+full+deployment.&products=%255B%257B%2522type%2522%253A%2522integration%2522%252C%2522protocol%2522%253A%2522storage%2522%252C%2522productSlug%2522%253A%2522neon%2522%252C%2522integrationSlug%2522%253A%2522neon%2522%257D%252C%257B%2522type%2522%253A%2522integration%2522%252C%2522protocol%2522%253A%2522storage%2522%252C%2522productSlug%2522%253A%2522upstash-kv%2522%252C%2522integrationSlug%2522%253A%2522upstash%2522%257D%255D&skippable-integrations=1) Open Agents 是一个用于在 Vercel 上构建和运行后台编码代理的开源参考应用。它包含 Web UI、代理运行时、沙箱编排以及从提示到代码变更所需的 GitHub 集成，而无需让笔记本电脑持续参与。 该仓库旨在被 Fork 和适配，而不是当作黑盒使用。 ## 它是什么 Open Agents 是一个三层系统： ``` Web -> Agent workflow -> Sandbox VM ``` - Web 应用处理认证、会话、聊天和流式 UI。 - 代理作为持久化工作流在 Vercel 上运行。 - 沙箱是执行环境：文件系统、Shell、Git、开发服务器和预览端口。 ### 关键架构决策：代理不是沙箱 代理不在虚拟机内部运行。它在沙箱外部运行，并通过文件读取、编辑、搜索和 Shell 命令与之交互。 这种分离是项目的主要目的： - 代理执行不与单个请求生命周期绑定 - 沙箱生命周期可以独立休眠和恢复 - 模型/提供者选择和沙箱实现可以独立演进 - 虚拟机保持为一个纯粹的执行环境，而不是变成控制平面 ## 当前能力 - 基于聊天的编码代理，支持文件、搜索、Shell、任务、技能与 Web 工具 - 使用 Workflow SDK 支持的后端多步骤执行、 streaming 和取消 - 基于快照的恢复功能的隔离 Vercel 沙箱 - 沙箱内的仓库克隆与分支操作 - 可选的自动提交、推送和 PR 创建（成功运行后） - 通过只读链接共享会话 - 通过 ElevenLabs 进行可选的语音输入转录 ## 运行时说明 以下是一些影响当前实现的重要细节： - 聊天请求会启动工作流运行，而不是内联执行代理。 - 每个代理回合可以跨多个持久化工作流步骤继续执行。 - 活动运行可以通过重新连接到现有工作流的流来恢复。 - 沙箱使用基础快照，暴露端口 `3000`、`5173`、`4321` 和 `8000`，并在空闲后休眠。 - 支持自动提交和自动 PR，但它们是偏好驱动的功能，并非始终启用。 ## 当前实际所需条件 这些要求基于当前的 `apps/web` 代码路径，而非旧的设置脚本。 ### 最低运行时 以下是应用启动并加载服务器状态所需的硬性要求： ``` POSTGRES_URL= JWE_SECRET= ``` ### 登录并实际使用托管应用所需 一个可用的部署还需要令牌加密和 Vercel OAuth 登录： ``` ENCRYPTION_KEY= NEXT_PUBLIC_VERCEL_APP_CLIENT_ID= VERCEL_APP_CLIENT_SECRET= ``` 没有这些，网站可以部署，但 Vercel 登录将无法工作。 ### 访问 GitHub 仓库、推送和 PR 所需 如果你希望用户连接 GitHub、在仓库/组织上安装应用、克隆私有仓库、推送分支或打开 PR，请添加以下 GitHub App 值： ``` NEXT_PUBLIC_GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET= GITHUB_APP_ID= GITHUB_APP_PRIVATE_KEY= NEXT_PUBLIC_GITHUB_APP_SLUG= GITHUB_WEBHOOK_SECRET= ``` ### 可选配置 ``` 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`：可选的技能元数据缓存（未配置时回退到内存）。 - `VERCEL_PROJECT_PRODUCTION_URL` / `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`：用于元数据和部分回调行为的规范生产 URL。 - `VERCEL_SANDBOX_BASE_SNAPSHOT_ID`：覆盖默认沙箱快照。 - `ELEVENLABS_API_KEY`：语音转录。 ## 在 Vercel 上部署你自己的副本 推荐路径：在 Vercel 上将本仓库部署到仓库根目录，然后叠加认证和 GitHub 集成。 1. Fork 本仓库。 2. 创建 PostgreSQL 数据库并复制其连接字符串。 3. 生成以下密钥： openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' # JWE_SECRET openssl rand -hex 32 # ENCRYPTION_KEY 4. 将仓库导入 Vercel。 5. 在 Vercel 项目设置中至少添加以下环境变量： POSTGRES_URL= JWE_SECRET= ENCRYPTION_KEY= 6. 部署一次以获取稳定的生产 URL。 7. 创建 Vercel OAuth 应用，回调 URL 为： https://YOUR_DOMAIN/api/auth/vercel/callback 8. 添加以下环境变量并重新部署： NEXT_PUBLIC_VERCEL_APP_CLIENT_ID= VERCEL_APP_CLIENT_SECRET= 9. 如果需要完整的 GitHub 启用编码代理流程，请使用以下信息创建 GitHub App： - 主页 URL：`https://YOUR_DOMAIN` - 回调 URL：`https://YOUR_DOMAIN/api/github/app/callback` - 设置 URL：`https://YOUR_DOMAIN/api/github/app/callback` 在 GitHub App 设置中： - 启用“安装期间请求用户授权（OAuth）” - 使用 GitHub App 的客户端 ID 和客户端密钥作为 `NEXT_PUBLIC_GITHUB_CLIENT_ID` 和 `GITHUB_CLIENT_SECRET` - 如果希望组织安装能正常工作，请将应用设为公开 10. 添加 GitHub App 环境变量并重新部署。 11. 可选添加 Redis/KV 和规范生产 URL 变量。 ## 本地设置 1. 安装依赖： bun install 2. 创建本地环境文件： cp apps/web/.env.example apps/web/.env 3. 在 `apps/web/.env` 中填写所需值。 4. 启动应用： bun run web 如果已链接 Vercel 项目，仍可使用 `vc env pull` 拉取环境变量，但设置现在是故意手动的，以便你能清楚看到哪些值重要。 ## OAuth 与集成设置 ### Vercel OAuth 创建 Vercel OAuth 应用并使用以下回调： ``` https://YOUR_DOMAIN/api/auth/vercel/callback ``` 对于本地开发，使用： ``` http://localhost:3000/api/auth/vercel/callback ``` 然后设置： ``` NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=... VERCEL_APP_CLIENT_SECRET=... ``` ### GitHub 应用程序 你不需要单独的 GitHub OAuth 应用。Open Agents 使用 GitHub App 的用户授权流程。 创建一个用于基于安装方式的仓库访问的 GitHub App，并配置： - 主页 URL：`https://YOUR_DOMAIN` - 回调 URL：`https://YOUR_DOMAIN/api/github/appallback` - 设置 URL：`https://YOUR_DOMAIN/api/github/app/callback` - 启用“安装期间请求用户授权（OAuth）” - 如果希望组织安装能正常工作，请将应用设为公开 对于本地开发，回调/设置 URL 使用 `http://localhost:3000/api/github/app/callback`，主页 URL 使用 `http://localhost:3000`。 然后设置： ``` 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 格式存储。 ## 常用命令 ``` bun run web bun run check bun run typecheck bun run ci bun run sandbox:snapshot-base ``` ## 仓库结构 ``` 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 ```

标签：GitHub集成, OSV, Vercel, Web层, 三层架构, 云代理, 代理工作流层, 代码变更, 会话管理, 威胁情报, 工作流, 开发者工具, 开源, 持久化工作流, 搜索引擎查询, 无笔记本电脑开发, 服务器端, 模板, 沙箱, 沙箱VM层, 流式UI, 测试用例, 生成式AI安全, 聊天流, 背景编码代理, 自动化攻击, 自动化编码, 虚拟机, 认证, 部署模板