Open Agents 部署实战指南：基于 deploy-open-harness 技能的两级凭据清单与 Vercel 上线流程

Open Agents 部署实战指南基于 deploy-open-harness 技能的两级凭据清单与 Vercel 上线流程【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agentsOpen Agents 的部署入口由仓库内置的deploy-open-harness技能文档SKILL.md完整定义它指导你把部署拆分为「最小部署」与「GitHub 全流程部署」两个级别收集各自真正需要的凭据在 Vercel 上完成导入、配置、重部署并通过首启验证确认链路可用。读完本篇你可以按图索骥地完成一份自己的 Open Agents 云端部署并理解每个环境变量在源码中的真实消费位置避免被过期文档误导。技能文档的定位与第一原则以当前代码为准SKILL.md 的 frontmatter 声明了它的用途引导用户完成部署自己的 Open Harness 副本所需的全部凭据收集、Vercel 部署与首启设置适用于任何「部署、自托管、凭据配置、fork 起步」类请求。这份文档最重要的设计决策是把「验证当前要求」放在「给出部署建议」之前。它的规则是先读仓库、再给建议。文档明确列出了一组必读文件README.md、.env.example、数据库客户端、Redis 客户端、沙箱配置 以及各 GitHub 回调路由。代码与文档不一致时信任代码并明确指出。这不是客套话——当前仓库就存在一处真实的文档漂移技能文档的凭据清单里仍写着JWE_SECRET用于会话加密和ENCRYPTION_KEY用于 provider token 静态加密而当前的 .env.example 与 README.md 的最小运行时要求是POSTGRES_URLBETTER_AUTH_SECRET且不再要求ENCRYPTION_KEY。在 认证配置 中可以看到OAuth token 加密已经收敛为 Better Auth 的原生能力encryptOAuthTokens: true见 config.ts 第 143 行密钥复用BETTER_AUTH_SECRET。这正是技能文档要求「说出文档与代码的差异」的典型场景。不要依赖scripts/setup.sh。该脚本在当前仓库中并不存在仓库的 scripts 目录只有 Vercel token 刷新与快照脚本文档因此要求一切以源码现状为准。部署前先划定范围最小部署 vs 完整部署文档要求第一步永远是确定用户要哪条路径最小部署Minimal deploy一个可正常运行的托管应用——用户可以用 Vercel 账号登录、正常使用产品但不涉及 GitHub 仓库访问。完整部署Full deploy在最小部署之上增加 GitHub 账号关联、GitHub App 安装、私有仓库访问、推送与 PR 创建能力。如果用户拿不准文档的推荐是先做最小部署再叠加 GitHub 能力。这一分级直接决定了下面凭据清单中哪些是「现在必须」哪些是「以后再补」。完整凭据清单按部署级别分组以下是技能文档给出的四级凭据分组并结合当前仓库 .env.example 的实际变量名做了核对。应用运行所必需变量用途源码中的消费位置POSTGRES_URLPostgres 连接串lib/db/client.ts 在首次惰性初始化 Drizzle 客户端前校验缺失时直接抛错BETTER_AUTH_SECRET技能文档旧称JWE_SECRETBetter Auth 会话签名/加密密钥lib/auth/config.ts 的secret字段数据库客户端 用了一个值得注意的实现db导出的是一个Proxy首次属性访问时才真正读取POSTGRES_URL并创建postgres连接与 Drizzle 实例。这意味着缺变量时构建不会立刻失败而是在第一次触达数据库的运行时请求上抛出POSTGRES_URL environment variable is required——排障时要记住这个失败时点。托管部署可用所必需变量用途消费位置ENCRYPTION_KEY技能文档所列当前代码已并入BETTER_AUTH_SECRETencryptOAuthTokensprovider token 静态加密lib/auth/config.tsNEXT_PUBLIC_VERCEL_APP_CLIENT_IDVercel OAuth 客户端 IDNEXT_PUBLIC_前缀会打进客户端产物lib/auth/config.ts 的socialProviders.vercelVERCEL_APP_CLIENT_SECRETVercel OAuth 客户端密钥同上GitHub 仓库流程所必需变量用途NEXT_PUBLIC_GITHUB_CLIENT_IDGitHub App 的 Client ID兼作 Better Auth 的 GitHub 社交登录GITHUB_CLIENT_SECRETGitHub App 的 Client SecretGITHUB_APP_IDGitHub App ID用于换取 installation 访问令牌GITHUB_APP_PRIVATE_KEYGitHub App 私钥NEXT_PUBLIC_GITHUB_APP_SLUGApp 的 slug用于构造安装链接GITHUB_WEBHOOK_SECRETWebhook 签名校验消费于 webhook 路由可选项变量说明REDIS_URL/KV_URL可选缓存。技能文档说明它增强可恢复流、停止信号与缓存能力但首次部署不需要.env.example 注释补充了具体用途skills 元数据缓存未配置时回退到内存缓存见 lib/redis.tsVERCEL_PROJECT_PRODUCTION_URL/NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL规范化生产 URL用于元数据与部分回调行为认证配置 会把它连同VERCEL_URL、BETTER_AUTH_URL解析为允许的主机白名单并自动附加*.host通配以覆盖预览域名VERCEL_SANDBOX_BASE_SNAPSHOT_ID新沙箱的可选基础快照未设置时沙箱从 Vercel 标准 Sandbox 运行时启动需使用你自己 Vercel 作用域内可访问的快照ELEVENLABS_API_KEY语音转写可选功能OPEN_AGENTS_RESOURCE_PROFILE当前 .env.example 新增项设为hobby使用 Hobby 计划的低配资源默认值留空为标准行为逐项凭据获取指南PostgreSQL创建任意一个托管 PostgresVercel 生态中通常用 NeonREADME 的一键部署按钮会自动 provisioning把连接串填入POSTGRES_URL。注意表结构由 drizzle 迁移 管理CI 中可用bun run ci触发迁移一致性检查。会话加密密钥BETTER_AUTH_SECRET技能文档给出的推荐生成命令是 URL-safe 的 base6432 字节熵openssl rand -base64 32 | tr / -_ | tr -d \n而 README.md 的最小运行时示例用的是更简单的openssl rand -base64 32。两者熵值相同前者只是额外排除了非 URL-safe 字符任选其一即可。该值只应存放在 Vercel 项目环境变量或本地.env文件中。加密密钥ENCRYPTION_KEY旧形态技能文档说明 provider token 会静态加密取值必须是 64 字符的十六进制串推荐生成命令openssl rand -hex 32需要再次强调按「信任代码」原则当前仓库的 .env.example 已不含ENCRYPTION_KEYtoken 加密由 Better Auth 的encryptOAuthTokens承担密钥即BETTER_AUTH_SECRET。按当前仓库部署时这一项不需要单独配置该命令仅适用于仍基于旧版 JWE 模块的 fork。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。回调路径提示技能文档写的回调是/api/auth/vercel/callback而当前 README.md 与 .env.example 注释给出的路径是https://YOUR_DOMAIN/api/auth/callback/vercel。所有认证路由由 Better Auth 的/api/auth/[...all]通配路由route.ts承载两种形态都能命中 catch-all但创建 OAuth 应用时应以当前 README 给出的路径为准——这正是技能文档「不一致时以代码为准」原则的又一实例。GitHub App不需要单独的 OAuth 应用技能文档明确强调不需要再建一个 GitHub OAuth App。Open Harness/Open Agents 直接复用 GitHub App 自身的用户授权OAuth流程GitHub App 的 Client ID/Secret 同时充当 Better Auth 的 GitHub 社交提供方见 lib/auth/config.ts 的 socialProviders.github仓库访问则走 App 的 installation 令牌。创建 GitHub App 时配置Homepage URLhttps://YOUR_DOMAINCallback URLhttps://YOUR_DOMAIN/api/github/app/callbackSetup URLhttps://YOUR_DOMAIN/api/github/app/callback本地开发homepage 用http://localhost:3000callback/setup 用http://localhost:3000/api/github/app/callback另外要求勾选 “Request user authorization (OAuth) during installation”安装时才会触发用户级授权将 GitHub App 的 Client ID / Client Secret 分别填入NEXT_PUBLIC_GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET若希望组织级安装顺畅工作把 App 设为 public生成 webhook secret 存入GITHUB_WEBHOOK_SECRET下载或生成私钥存入GITHUB_APP_PRIVATE_KEY——它可以是转义换行后的 PEM 原文也可以是 base64 编码后的 PEM两种方式都被 README.md 明确支持。其中 Setup URL 对应仓库中的 安装回调路由负责完成 installation 同步安装入口路由 负责引导用户发起安装。Redis / KV可选。技能文档的原话定位改善可恢复流、停止信号与缓存体验但不是首次部署的前置条件。未配置时 lib/redis.ts 会回退到内存实现。九步部署流程文档给出的部署序列按「先拿稳定生产 URL再回填回调依赖型凭据」的节奏编排Fork 仓库。在仓库根目录导入 Vercelmonorepo 的 app 位于apps/webVercel 会识别 Next.js 目录。配置基线环境变量POSTGRES_URL、JWE_SECRET当前代码为BETTER_AUTH_SECRET、ENCRYPTION_KEY如仍适用。部署一次拿到稳定的生产 URL。用该生产 URL 创建 Vercel OAuth 应用。补上NEXT_PUBLIC_VERCEL_APP_CLIENT_ID与VERCEL_APP_CLIENT_SECRET。重新部署。若要 GitHub 全流程用生产 URL 创建 GitHub App补全 6 个 GitHub 环境变量再次重新部署。可选追加 Redis/KV 与生产 URL 变量。如果已备好自定义域名可以从一开始就用自定义域名替代默认vercel.app生产 URL后续 OAuth 回调配置随之使用自定义域名即可。首启验证按部署级别分别验收最小部署走四步打开生产站点 → 用 Vercel 登录 → 确认成功进入应用 → 创建一个 session 并确认基础 UI 正常加载。完整部署在此之上追加GitHub 账号关联可用GitHub App 安装流程能完整走完UI 中能看到已安装项或仓库列表对应 安装同步接口 与 仓库列表接口可以启动一个仓库驱动的 session沙箱成功启动agent 能在仓库内工作沙箱生命周期与端口暴露见 README.md 的 Runtime notes 与 SANDBOX-LIFECYCLE.md。文档还定了一条排障纪律出问题时定位到具体缺失的凭据或回调不匹配而不是给泛泛的通用建议。结合上文可知最常见的失败面就是 OAuth 回调路径不一致/api/auth/callback/vercelvs/api/auth/vercel/callback与 GitHub App 的 Setup URL 未指向/api/github/app/callback。安全规则与回答结构约定技能文档对自身即指导部署的 Agent设定了四条安全规则同样适用于人工操作永远不要让用户把密钥粘贴进对话只说明每个值应该放在哪里密钥值始终留在 Vercel 项目环境变量或本地 env 文件中把「最小部署的阻塞项」和「GitHub 全流程的阻塞项」分开陈述避免一次性甩出全部变量凡是可选项都要显式标注为可选。文档最后还约定了标准化的回答结构目标范围 → 按「现在必须 / 以后可选」分组的凭据清单 → 每个缺失凭据的具体获取方式 → 下一步部署动作 → 部署后的验证项 → 按需的后续升级项Redis、GitHub、语音、自定义域名、快照覆盖。这套结构保证了部署引导始终朝「下一个解锁点」推进而不是原地打转。小结deploy-open-harness 技能的价值在于把「部署一个带 GitHub 深度的 Agent 平台」拆成了可验证的小步先按最小范围收集POSTGRES_URL 会话密钥两个变量上线再逐层叠加 Vercel OAuth 与 GitHub App 凭据每一步都能指向 源码、env 模板 或 README 中的具体位置做核对。它的「信任代码、明示差异」原则也提醒我们在 fork 一个快速演进的开源模板时凭据清单永远要以当前仓库的.env.example为最终基准。【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考