给 OpenClaw 配置 GitHub 机器人账号：用 GitHub App 读取 PR review 代码

说明：本文由 OpenClaw 助手根据一次真实配置与排障过程辅助整理，内容经过人工确认。

在研发协作里，OpenClaw 经常需要读取 GitHub Pull Request、汇总代码审查结果，并把结论评论回 PR。最稳妥的做法不是使用个人账号 token，而是给组织创建一个 GitHub App，让 OpenClaw 以机器人身份访问指定仓库。

本文记录一套已经验证可用的配置方式：创建 GitHub App、限制仓库范围、配置最小权限、在服务器上保存私钥，并通过 installation token 调用 GitHub API。

为什么用 GitHub App

相比个人访问令牌，GitHub App 更适合作为机器人账号：

权限可以按仓库和 API 资源精细控制。
token 是短期 installation token，泄漏风险低于长期 token。
评论会显示为 xxx[bot]，身份边界清楚。
可以只安装到一个仓库，而不是整个组织所有仓库。

这篇文章的目标场景是：

OpenClaw 能读取指定仓库的 PR。
OpenClaw 能在 PR 下发普通评论。
暂时不启用 webhook。
不使用个人 GitHub token。

一、创建 GitHub App

需要 GitHub 组织 owner 或有 GitHub App manager 权限的人操作。

进入组织的 GitHub App 创建页面：

https://github.com/organizations/<ORG>/settings/apps/new

建议基础信息：

GitHub App name: <your-openclaw-bot-name>
Homepage URL: https://github.com/<ORG>/<REPO>
Webhook: 取消 Active

如果当前只是让 OpenClaw 手动读取 PR、发表评论，不需要 webhook，所以可以先关闭 Webhook 的 Active。关闭后 Webhook URL 和 Secret 不需要填写。

Callback URL、Setup URL 也可以先留空。这个场景不走用户 OAuth 授权流程。

二、配置 Repository permissions

最终验证可用的最小权限如下：

Metadata: Read-only
Contents: Read-only
Pull requests: Read and write
Issues: Read and write

几个说明：

Metadata 是 GitHub App 默认需要的读取权限。
Contents: Read-only 用于读取仓库文件、diff 相关信息。
Pull requests: Read and write 用于 PR 相关 API 权限。
Issues: Read and write 用于 PR 普通评论，因为 GitHub 的 PR 普通评论走 issue comments API。

这里有一个容易踩坑的点：一开始可能会以为“普通 PR 评论只需要 Issues write”，但实际调用时 GitHub 会返回类似诊断：

x-accepted-github-permissions: issues=write; pull_requests=write

也就是说，在对 PR 发普通评论时，Issues 和 Pull requests 都需要 Read and write。如果 Pull requests 只有 Read-only，创建评论可能失败：

Resource not accessible by integration

三、限制安装范围

创建 GitHub App 后，不要安装到整个组织所有仓库。进入 App 的 Install App 页面，安装到指定组织时选择：

Only select repositories

然后只选择 OpenClaw 需要访问的仓库，例如：

<ORG>/<REPO>

这样即使 App 权限后续扩大，也只影响被选中的仓库。

四、记录 App ID 和 Installation ID

创建和安装完成后，需要记录两个非密钥信息：

App ID: <APP_ID>
Installation ID: <INSTALLATION_ID>

App ID 可以在 GitHub App 的 General 页面看到。

Installation ID 通常可以在安装完成后的 URL 中看到，形式类似：

/installations/<INSTALLATION_ID>

这两个值不是私钥，但也建议只放在服务器配置或内部文档中，不要写进公开文章的真实示例里。

五、生成并保存 private key

在 GitHub App 的 General 页面找到 Private keys 区域，点击：

Generate a private key

GitHub 会下载一个 .pem 文件。这个文件是敏感私钥，不能发到群聊、issue、PR 或公开文档里。

在 OpenClaw 服务器上建议保存到固定路径：

mkdir -p ~/.config/openclaw/github-apps
mv <downloaded-private-key>.pem ~/.config/openclaw/github-apps/<your-app-name>.private-key.pem
chmod 600 ~/.config/openclaw/github-apps/<your-app-name>.private-key.pem

权限应类似：

-rw------- 1 ubuntu ubuntu ... <your-app-name>.private-key.pem

chmod 600 的含义是只有当前用户可以读写，其他用户不能读取。

六、生成 installation token

GitHub App 不能直接拿 private key 调用仓库 API。标准流程是：

用 App ID 和 private key 生成一个 GitHub App JWT。
用 App JWT 请求 installation access token。
用 installation token 调 GitHub REST API。

下面是一个最小 Python 示例，展示如何生成 token 并验证仓库访问。示例不会输出 token 本身。

import json
import time
import urllib.request
import urllib.error
import jwt

APP_ID = "<APP_ID>"
INSTALLATION_ID = "<INSTALLATION_ID>"
KEY_PATH = "/home/ubuntu/.config/openclaw/github-apps/<your-app-name>.private-key.pem"
OWNER = "<ORG>"
REPO = "<REPO>"

with open(KEY_PATH, "rb") as f:
    private_key = f.read()

now = int(time.time())
app_jwt = jwt.encode(
    {
        "iat": now - 60,
        "exp": now + 540,
        "iss": str(APP_ID),
    },
    private_key,
    algorithm="RS256",
)

def github_request(method, url, token, data=None):
    headers = {
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
        "Authorization": f"Bearer {token}",
        "User-Agent": "openclaw-github-app",
    }
    body = None if data is None else json.dumps(data).encode("utf-8")
    req = urllib.request.Request(url, data=body, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=20) as resp:
        raw = resp.read().decode("utf-8")
        return json.loads(raw) if raw else {}

token_payload = github_request(
    "POST",
    f"https://api.github.com/app/installations/{INSTALLATION_ID}/access_tokens",
    app_jwt,
    {},
)

installation_token = token_payload["token"]
permissions = token_payload.get("permissions", {})

repo = github_request(
    "GET",
    f"https://api.github.com/repos/{OWNER}/{REPO}",
    installation_token,
)

print(
    json.dumps(
        {
            "repo": repo.get("full_name"),
            "permissions": permissions,
        },
        ensure_ascii=False,
        indent=2,
    )
)

如果配置正确，返回的权限应包含：

{
  "contents": "read",
  "issues": "write",
  "metadata": "read",
  "pull_requests": "write"
}

七、验证读取 PR

可以用 installation token 读取打开的 PR：

prs = github_request(
    "GET",
    f"https://api.github.com/repos/{OWNER}/{REPO}/pulls?state=open&per_page=5",
    installation_token,
)

for pr in prs:
    print(pr["number"], pr["title"])

能正常返回 PR 列表，说明仓库安装范围和读取权限已经生效。

八、发送 PR 普通评论

PR 的普通评论使用 issue comments API。注意 URL 里的 number 是 PR number：

PR_NUMBER = 2
comment_body = "OpenClaw GitHub App comment test: installation token and issue comment permission verified."

comment = github_request(
    "POST",
    f"https://api.github.com/repos/{OWNER}/{REPO}/issues/{PR_NUMBER}/comments",
    installation_token,
    {"body": comment_body},
)

print(comment["html_url"])

成功后，GitHub 返回 201 Created，评论作者会显示为：

<your-app-name>[bot]

九、常见问题

1. 能读 PR，但发评论 403

错误可能是：

Resource not accessible by integration

先检查 token 权限。如果只有：

{
  "issues": "write",
  "pull_requests": "read"
}

需要把 GitHub App 的 Pull requests 权限从 Read-only 改成 Read and write，然后到 Install App 页面重新确认安装权限更新。

2. 改了权限，但 token 里还是旧权限

GitHub App 权限修改后，安装侧可能还需要重新批准。处理方式：

进入 GitHub App 的 Install App 页面。
找到对应组织安装项。
点击 Review request、Accept new permissions、Update permissions 或类似按钮。
重新生成 installation token 再验证。

3. 私钥应该放哪里

建议放在服务器固定路径，并设置为 600：

~/.config/openclaw/github-apps/<your-app-name>.private-key.pem

不要把 private key 写进：

群聊
PR 评论
issue
Markdown 博客
Git 仓库
shell history 中可见的长命令

4. 是否需要 webhook

如果只是让 OpenClaw 在需要时读取 PR 并发表评论，不需要 webhook。

只有当你希望 GitHub 主动通知 OpenClaw，例如 PR 创建、更新、评论触发自动流程时，才需要启用 webhook，并额外配置公网可访问的 webhook endpoint 与 secret 校验。

十、建议的 OpenClaw 配置方式

OpenClaw 侧可以保存三类配置：

GITHUB_APP_ID=<APP_ID>
GITHUB_APP_INSTALLATION_ID=<INSTALLATION_ID>
GITHUB_APP_PRIVATE_KEY_PATH=/home/ubuntu/.config/openclaw/github-apps/<your-app-name>.private-key.pem

不要保存长期 GitHub token。每次需要访问 GitHub 时，动态生成短期 installation token 即可。

推荐封装一个内部 helper：

get_github_installation_token(app_id, installation_id, private_key_path)

然后所有 GitHub API 调用都通过这个 token 走。

结论

这套 GitHub App 方式可以让 OpenClaw 以明确的机器人身份参与 GitHub 协作，并把权限限制在指定仓库和必要 API 范围内。

最终经过验证的最小可用权限是：

Metadata: Read-only
Contents: Read-only
Issues: Read and write
Pull requests: Read and write

如果只读 PR，不发表评论，可以把 Issues 和 Pull requests 降到只读。但只要要在 PR 下发普通评论，建议直接配置为上面的组合，并通过安装范围限制到单仓库来控制风险。

posted @ 2026-05-27 02:35 LexLuc 阅读(8) 评论(0) 收藏举报

刷新页面返回顶部

Lex个人随想乡

Attention before pay attention