openclaw-channel-github

v0.1.1

Published

11 days ago

GitHub Channel for OpenClaw — connects GitHub Issues, Pull Requests, Discussions, and CI/CD workflows to the OpenClaw AI agent framework via webhooks.

0High
0Medium
0Low

icebergu

openclaw github channel webhook issues pull-requests code-review

OpenClaw GitHub Channel

OpenClaw GitHub Channel 是一个基于 Node.js 的 OpenClaw Channel 插件，用来把 GitHub Issues、Pull Requests、Reviews、Discussions 和部分 CI 事件接入 OpenClaw。

它负责两件事：

接收入站 GitHub Webhook，并归一化为 OpenClaw 可消费的事件格式
将 OpenClaw 的回复写回 GitHub，例如评论、Review 或 Reaction

当前实现采用 TypeScript 开发，构建产物位于 dist/，插件清单位于 openclaw.plugin.json。

功能概览

支持 GitHub App Webhook 验签
支持 Issue、PR、Review、Discussion、Check Run、Workflow Run 等事件解析
支持将 GitHub 事件归一化为统一的 NormalizedEvent
支持基于 mention、命令、标签、自动触发的路由策略
支持简单的 delivery 去重与 bot loop 防护
支持回写 GitHub 评论、PR Review、Reaction
适合作为 OpenClaw 的“异步协作型 Channel”接入仓库工作流

仓库结构

.
├── openclaw.plugin.json
├── package.json
├── index.ts
├── src/
│   ├── main.ts
│   ├── auth/
│   ├── config/
│   ├── events/
│   ├── normalizer/
│   ├── outbound/
│   ├── routing/
│   ├── server/
│   └── state/
├── e2e/
└── docs/

各模块职责如下：

src/auth：GitHub App JWT、Webhook HMAC 验签、请求头提取
src/config：配置加载、解析、校验、仓库和账号匹配
src/events：GitHub Webhook 类型定义与事件解析
src/normalizer：把 GitHub 事件转换为统一事件结构
src/routing：session key、触发策略、bot 检测、outbound marker 检测
src/outbound：GitHub API 回写
src/state：去重状态存储
src/server：HTTP Webhook 入口与处理管线
src/main.ts：服务启动入口
index.ts：插件公共导出入口

运行要求

OpenClaw 主程序建议使用官方文档推荐版本安装
本项目代码运行需要 Node.js 20 或更高版本
npm 10 或更高版本
一个已安装到目标仓库或组织的 GitHub App
一个可被 GitHub 回调访问到的 HTTP 地址

安装 OpenClaw

如果你的机器上还没有 OpenClaw，先按官方 CLI 方式安装：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

以上命令格式与当前 OpenClaw 文档一致。

安装插件

OpenClaw 的插件分发通常有两种方式：

npm 包分发
本地扩展路径加载

本项目现在已经补齐了 OpenClaw 识别所需的元数据：

openclaw.plugin.json
package.json 中的 openclaw.extensions
package.json 中的 openclaw.channel 和 openclaw.install

这意味着它可以按 OpenClaw 当前文档中的插件机制被发现和展示。

方式一：本地路径安装

如果你在本地开发或尚未发布 npm 包，推荐直接用 OpenClaw CLI 从本地目录安装。

git clone https://github.com/Iceber/openclaw-channel-github.git
cd openclaw-channel-github
npm install
npm run build
openclaw plugins install -l .

说明：

-l 表示 link 安装，适合开发期本地调试
如果你想复制安装而不是链接安装，可使用 openclaw plugins install .
安装后可用 openclaw plugins list 检查插件是否被发现

常用检查命令：

openclaw plugins list
openclaw plugins info github
openclaw plugins doctor

方式二：npm 包安装

如果你准备将该插件发布到 npm，发布后可按 OpenClaw 官方支持的 npm spec 方式安装。

典型流程：

npm install
npm run build
npm publish

发布后安装命令格式如下：

openclaw plugins install openclaw-channel-github

如果后续改为 scoped 包名，则命令会变成：

openclaw plugins install @your-scope/openclaw-channel-github

OpenClaw 当前对 npm 插件安装的命令格式是固定的 openclaw plugins install <npm-spec>，不接受 git/url/file spec 作为 npm 安装来源。

建议确保发布包中包含以下内容：

openclaw.plugin.json
dist/
package.json

安装后启用与重启

插件安装后，建议执行：

openclaw plugins list
openclaw gateway status

如果你的 Gateway 已经在运行，按官方插件文档建议重启 Gateway 以加载新插件。

GitHub App 配置

推荐使用 GitHub App 模式接入，而不是直接使用个人访问令牌。

建议权限

当前插件清单中声明的权限如下：

issues: write
pull_requests: write
metadata: read
discussions: write
contents: read

建议订阅的 Webhook 事件

issues
issue_comment
pull_request
pull_request_review
pull_request_review_comment
discussion
discussion_comment
check_run
workflow_run

获取必要信息

你需要从 GitHub App 配置页拿到以下信息：

App ID
Installation ID
Webhook Secret
Private Key 文件路径

配置文件

服务启动时默认读取根目录下的 config.json。仓库中现在提供了可直接复制的示例文件 config.example.json。你也可以在启动命令中传入自定义路径。

最小配置示例

{
  "server": {
    "addr": ":8080"
  },
  "channel": {
    "enabled": true,
    "mode": "app",
    "appId": 123456,
    "installationId": 78901234,
    "privateKeyPath": "./github-app.private-key.pem",
    "webhookSecret": "replace-with-your-webhook-secret",
    "repositories": [
      "your-org/your-repo"
    ],
    "ignoreBots": true,
    "trigger": {
      "requireMention": true,
      "botUsername": "openclaw-bot",
      "commands": [
        "/openclaw"
      ],
      "labels": []
    },
    "outbound": {
      "mode": "comment",
      "outboundMarker": "<!-- openclaw-outbound -->"
    },
    "autoTrigger": {
      "onPROpened": false,
      "onIssueOpened": false
    }
  }
}

如果你只是想先跑起来，直接复制示例文件即可：

cp config.example.json config.json

多账号配置示例

当你需要一个实例管理多个 GitHub App 安装或多组仓库时，可使用 accounts。

{
  "server": {
    "addr": ":8080"
  },
  "channel": {
    "enabled": true,
    "ignoreBots": true,
    "trigger": {
      "requireMention": true,
      "botUsername": "openclaw-bot",
      "commands": ["/openclaw"],
      "labels": ["ai-review"]
    },
    "outbound": {
      "mode": "comment",
      "outboundMarker": "<!-- openclaw-outbound -->"
    },
    "autoTrigger": {
      "onPROpened": true,
      "onIssueOpened": false
    },
    "accounts": {
      "team-a": {
        "mode": "app",
        "appId": 111111,
        "installationId": 222222,
        "privateKeyPath": "./keys/team-a.pem",
        "webhookSecret": "team-a-secret",
        "repositories": [
          "org-a/repo-1",
          "org-a/repo-2"
        ]
      },
      "team-b": {
        "mode": "app",
        "appId": 333333,
        "installationId": 444444,
        "privateKeyPath": "./keys/team-b.pem",
        "webhookSecret": "team-b-secret",
        "repositories": [
          "org-b/repo-1"
        ]
      }
    }
  }
}

配置项说明

`server`

addr：监听地址，默认 :8080

`channel`

enabled：是否启用 GitHub Channel
mode：认证模式，当前主要使用 app
appId：GitHub App ID
installationId：GitHub App Installation ID
privateKeyPath：GitHub App 私钥 PEM 路径
webhookSecret：Webhook 验签密钥
repositories：允许处理的仓库列表，格式必须为 owner/repo
ignoreBots：是否忽略 Bot 发送者

`channel.trigger`

requireMention：是否必须 @bot 才触发
botUsername：Bot 用户名，用于 mention 检测
commands：命令前缀列表，例如 /openclaw
labels：标签触发列表，例如 ai-review

`channel.outbound`

mode：回写模式，支持 comment、review、auto
outboundMarker：写回隐藏标记，用于避免 bot loop

`channel.autoTrigger`

onPROpened：PR 打开时自动触发
onIssueOpened：Issue 打开时自动触发

`channel.accounts`

用于多安装、多仓库分组配置
如果配置了 accounts，会优先按仓库匹配具体账号

启动方式

开发模式

npm install
npm run dev -- ./config.json

说明：当前 dev 命令本质上执行的是 ts-node src/main.ts，启动参数会作为位置参数传入，推荐直接把配置路径作为最后一个参数。

生产模式

npm install
npm run build
npm start -- ./config.json

仅构建

npm run build

构建完成后主要产物包括：

dist/main.js
dist/index.js

Webhook 配置

在 GitHub App 中，将 Webhook URL 指向你的服务地址：

https://your-domain.example.com/webhook

健康检查地址：

https://your-domain.example.com/health

如果你本地调试，可通过隧道工具暴露本地端口，例如：

ngrok
cloudflared tunnel
反向代理到公网地址

事件处理模型

支持的事件

issues
issue_comment
pull_request
pull_request_review
pull_request_review_comment
discussion
discussion_comment
check_run
workflow_run

触发方式

按优先顺序大致如下：

mention 触发
命令前缀触发
标签触发
自动触发

会话键

会话键用于把同一个 Issue / PR 的后续消息归并到同一个 OpenClaw 会话中。

格式如下：

github:<owner>/<repo>:issue:<number>
github:<owner>/<repo>:pull_request:<number>
github:<owner>/<repo>:discussion:<number>
github:<owner>/<repo>:pull_request:<number>:review-thread:<threadId>

Bot Loop 防护

当前实现提供三层基础保护：

忽略 GitHub 标记为 Bot 的发送者
忽略用户名等于 botUsername 的发送者
检查回写文本中的 outboundMarker

建议保留默认的 outboundMarker，不要删除。

OpenClaw 集成建议

这个项目当前已经具备作为 OpenClaw 插件的基础结构：

根目录存在 openclaw.plugin.json
package.json 声明了 openclaw.extensions: ["./index.ts"]
构建后可由 dist/index.js 提供运行时代码

接入时建议遵循以下原则：

本地开发优先使用 openclaw plugins install -l .
发布后使用 openclaw plugins install <npm-spec>
在安装前先执行 npm install 和 npm run build
运行服务实例时提供正确的 config.json

如果你需要显式加载本地插件目录，也可以使用 OpenClaw 插件系统的标准方式，通过 openclaw plugins install 或 plugins.load.paths 管理，而不是依赖临时脚本扫描。

开发

安装依赖

npm install

运行测试

npm test

运行端到端测试

npm run test:e2e

持续观察测试

npm run test:watch

清理构建产物

npm run clean

当前验证状态

本仓库当前已验证：

单元测试通过
E2E 测试通过
TypeScript 类型检查通过
构建成功

部署建议

单实例部署

适合少量仓库场景：

一个 Node.js 进程
一个公开可访问的 Webhook 地址
一个或少量 GitHub App Installation

反向代理部署

推荐在生产环境中放在反向代理后面，例如：

Nginx
Caddy
Traefik

建议启用：

HTTPS
访问日志
超时控制
基础的请求大小限制

状态存储说明

当前 delivery 去重状态保存在内存中，仅适合单实例或轻量部署场景。

如果后续需要生产级高可用部署，建议把 src/state 替换为共享存储，例如：

Redis
数据库表
其他带 TTL 的分布式 KV

已知限制

当前默认消息处理器只是示例实现，不会自动转发到真实 OpenClaw Gateway
mode: token 只保留了配置入口，主要实现路径仍以 GitHub App 为主
delivery 去重基于内存，不适合多实例横向扩展
默认回写路径当前主要是普通 comment，复杂 Review 策略需要按你的 OpenClaw 集成方式继续扩展

常见问题

1. 服务启动后没有收到 GitHub 事件

检查以下内容：

Webhook URL 是否可从公网访问
GitHub App 是否订阅了正确事件
webhookSecret 是否与 GitHub App 中配置一致
请求是否实际到达 /webhook

2. Webhook 返回 401

通常表示验签失败，重点检查：

config.json 中的 channel.webhookSecret
GitHub App 中的 Webhook Secret
请求是否经过了会修改 body 的代理层

3. 事件到达但没有触发处理

通常是触发条件未命中，检查：

是否满足 mention
是否满足命令前缀
是否满足标签触发
是否开启了 auto trigger

4. 服务能处理但无法回写 GitHub