企业官网建设流程全解析

Open Agents GitHub App 创建指南：3 个回调 URL 逐一说清

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

Open Agents 是一个开源的云端 AI 编程代理模板（cloud agents template），内置 Web 界面、代理运行时、沙箱编排与 GitHub 集成。要让 GitHub 仓库接入、代码推送和 PR 自动创建正常工作，你必须创建一个 GitHub App，并正确配置 3 个回调 URL。本文逐个说清它们的用途、填写位置和对应源码，帮你一次配通，不再踩坑。

为什么是 GitHub App 而不是普通 OAuth？

Open Agents 特意不使用单独的 GitHub OAuth App，而是直接复用 GitHub App 自带的 Client ID / Client Secret 作为登录提供方，再用 App 的 installation token 访问仓库。好处是：

• 一个 App 同时搞定「登录」和「仓库读写」两件事
• 支持个人账号和组织（org）两种安装方式
• 安装/卸载事件可实时同步到数据库

💡 建议把 App 设为public，否则组织安装流程会遇到权限问题。

3 个关键 URL 总览

把YOUR_DOMAIN换成你的生产域名（本地开发用http://localhost:3000）：

回调 URL 一：登录回跳/api/auth/callback/github

这是 GitHub 登录的标准 OAuth 回跳地址。认证由 Better Auth：

clientId: NEXT_PUBLIC_GITHUB_CLIENT_ID # GitHub App 的 Client ID clientSecret: GITHUB_CLIENT_SECRET # GitHub App 的 Client Secret

用户点击「用 GitHub 登录」后，浏览器跳转到 GitHub 授权页，授权完成再回跳到这个 URL 完成 token 交换。

常见错误：误以为要填localhost到生产配置。部署后必须用https://的正式域名，本地开发才用http://localhost:3000/api/auth/callback/github。

回调 URL 二：安装回跳/api/github/app/callback

这是 GitHub App 设置里的Setup URL，用户在你的网站上完成安装（或向组织提交安装请求）后，GitHub 会带参数回跳到这里。处理逻辑在 route.ts：

• 读取 URL 中的installation_id和setup_action参数
• 校验用户是否已登录、是否关联了 GitHub 账号
• 调用 sync.ts 同步该用户所有安装记录到数据库
• 最终重定向回/get-started，并附带状态参数（如github=app_installed）供前端提示

配套的安装跳转入口在 install/route.ts：它生成一个防重放的state参数并写入 Cookie，用户授权后 Setup URL 回跳时完成闭环。

回调 URL 三：Webhook/api/github/webhook

在 GitHub App 的Webhooks设置里填入https://YOUR_DOMAIN/api/github/webhook，并订阅installation、installation_repositories、pull_request三个事件。处理入口 route.ts 会：

• 🔐 用GITHUB_WEBHOOK_SECRET校验x-hub-signature-256签名，防止伪造请求
• 📥installation事件：安装被删除时清理记录；安装变更时更新仓库选择范围
• 🔀pull_request事件：PR 被关闭/合并/重新打开时，自动同步对应会话状态，已归档会话会触发沙箱归档，避免资源浪费

签名校验函数见 verifySignature，这是 Webhook 安全的核心，secret 一定要填。

环境变量对照清单

配置完成后，按 apps/web/.env.example 填入以下变量（注释中已标明前两个 URL 的用途）：

NEXT_PUBLIC_GITHUB_CLIENT_ID= # GitHub App Client ID GITHUB_CLIENT_SECRET= # GitHub App Client Secret GITHUB_APP_ID= # App 页面底部的数字 ID GITHUB_APP_PRIVATE_KEY= # PEM 内容（换行转义）或 base64 编码 NEXT_PUBLIC_GITHUB_APP_SLUG= # App 的 slug（安装页 URL 中可见） GITHUB_WEBHOOK_SECRET= # Webhook 页签生成的 secret

GITHUB_APP_PRIVATE_KEY可以存为「带转义换行的 PEM 原文」，也可以存为 base64 编码后的 PEM，两种方式都支持，解析逻辑在 app.ts。

配置步骤速查

1. 创建 GitHub App，填写 Homepage URL（你的域名）、Callback URL、Setup URL
2. 权限勾选contents、pull_requests、metadata读写
3. 在 Webhooks 页签填入 Webhook URL + secret，订阅上述 3 个事件
4. 复制 Client ID/Secret、App ID、Private Key、slug 到环境变量
5. 重新部署，访问/api/github/connection-status自检（返回connected即成功，见 route.ts）

常见问题

Q：为什么安装后状态显示pending_sync？Setup URL 回跳时暂时查不到安装记录，属于正常过渡态，Webhook 到达后会补齐。

Q：本地开发要改什么？三个 URL 全部换成http://localhost:3000前缀即可，鉴权模块已默认放行 localhost:3000（见 config.ts）。

Q：忘了填 Webhook secret 会怎样？接口直接返回 500GITHUB_WEBHOOK_SECRET is not configured，所有事件都会被拒收。

按以上 3 个回调 URL 逐一核对配置，你的 Open Agents 实例就能完整跑通「GitHub 登录 → 仓库安装 → 代理改代码 → 自动 PR」的全流程。

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