Git

通过 git forge 的 issue 和 pull request 评论与代理对话，并通过按事件路由表展示仓库事件，包括 PR 生命周期、审查评论、CI 结果和发布。该通道围绕一个 provider seam 构建：provider 字段用于选择 forge。GitHub、Gitea 和 Forgejo 是已接入的 provider；其他 forge 作为并列 provider 接入，无需更改通用通道。

刚接触 ZeroClaw？ 先从 Quickstart 开始，获取一个正在运行的代理，然后快速浏览 Concepts，了解本页默认使用的术语（agent、peer group、autonomy、SOP）。

使用 GitHub 提供方时，ZeroClaw 会以 GitHub App 身份进行认证，并以该应用自己的机器人身份（your-app[bot]）回复，因此它可在安装了该应用的任何仓库中工作。没有个人访问令牌，也没有共享用户账户。

使用 Gitea/Forgejo 提供程序时，ZeroClaw 会使用个人访问令牌针对实例的 Gitea 兼容 API 进行身份验证，并以该令牌的所有者身份进行回复。

**构建说明：**标准分发制品中包含 Git 通道，但精简的 Cargo 默认配置中不包含。自定义源码构建必须添加 channel-git；禁用默认功能的构建还必须添加 agent-runtime。channel-git 功能会引入所有已接入的 forge 提供商，因此单个二进制文件即可服务所有受支持的 forge；不存在可供选择的更小的按提供商划分的构建子集。

谁可以与代理通信

入站发送方会根据为绑定代理解析出的对等集合进行限制，该集合来自代理所属的 peer_groups 配置。匹配时会去除开头的 @，并对通道的原生发送方标识符执行不区分大小写的比对。空集合会拒绝所有人；包含 "*" 的集合会接受所有人；否则仅接受列出的外部对等方（以及对等代理）。这与网关配对（gateway.require_pairing）不同，后者验证的是 HTTP/WebSocket 客户端，而非聊天通道的发送方。

git 的 peer group 将 channel 设置为 git，在 external_peers 中列出允许的发送者（对于 git，即评论作者的 forge 用户名（登录名）；["*"] 接受任何人），可选地为跨 agent 分发指定 peer agents，配置一个 ignore 黑名单，以及一个 output_modality（mirror、voice 或 text）。有关字段说明，请参见 Peer Groups。

在何处设置：

工作原理

• 轮询，而不是 webhooks。 该通道通过 since 游标轮询 forge REST API，以获取新的 issues、pull requests 和 comments。守护进程无需公共 URL、隧道或入站暴露；它可以在 NAT 后正常工作。
• 问题范围内的对话。 同一 issue 或 PR 上的每条消息共享一个对话线程；代理作为该 issue 上的评论进行回复。
• 流式回复。 代理会先发布一条草稿评论，并在响应逐步增长时就地编辑它（编辑间隔 ≥ 2 秒，以遵守 forge 滥用限制）。
• 反应。 确认反应会映射到 forge 的反应集合（在 GitHub 中：👀 → eyes，✅ → +1，⚠️ → confused，…）；无法映射的 emoji 会被跳过。
• 冷启动。 在守护进程启动之前创建的事件永远不会被处理，因此重启无法重放历史记录。另一方面：守护进程停机期间发布的评论会被错过，因此请再次提及该应用。
• 评论编辑会被忽略。 只有新建的评论以及 issue/PR 的开启帖子才会触发该 agent。

凭证

每个提供商的身份验证方式都不同，并且每个都有完整的分步说明：

• GitHub 通过 GitHub App（App ID 加上生成的私钥）进行身份验证。请参阅 创建 GitHub App。
• Gitea / Forgejo 使用个人访问令牌通过实例的 Gitea 兼容 API 进行身份验证。参见 创建 Gitea / Forgejo 令牌（Codeberg）。

配置

在您偏好的任一表面上设置通道字段：

完整字段参考，直接来自模式：

zeroclaw config set channels.git.<alias>.access_token    # 掩码输入，加密存储

export ZEROCLAW_channels__git__<alias>__access_token=

zeroclaw config set channels.git.<alias>.api_base_url <value>

export ZEROCLAW_channels__git__<alias>__api_base_url=

zeroclaw config set channels.git.<alias>.app_id <value>

export ZEROCLAW_channels__git__<alias>__app_id=

zeroclaw config set channels.git.<alias>.events <value>

export ZEROCLAW_channels__git__<alias>__events=

zeroclaw config set channels.git.<alias>.events_backbone <value>

export ZEROCLAW_channels__git__<alias>__events_backbone=

zeroclaw config set channels.git.<alias>.excluded_tools <value>

export ZEROCLAW_channels__git__<alias>__excluded_tools=

zeroclaw config set channels.git.<alias>.installation_id <value>

export ZEROCLAW_channels__git__<alias>__installation_id=

zeroclaw config set channels.git.<alias>.listen_to_bots <value>

export ZEROCLAW_channels__git__<alias>__listen_to_bots=

zeroclaw config set channels.git.<alias>.mention_only <value>

export ZEROCLAW_channels__git__<alias>__mention_only=

zeroclaw config set channels.git.<alias>.poll_interval_secs <value>

export ZEROCLAW_channels__git__<alias>__poll_interval_secs=

zeroclaw config set channels.git.<alias>.private_key    # 掩码输入，加密存储

export ZEROCLAW_channels__git__<alias>__private_key=

zeroclaw config set channels.git.<alias>.private_key_path <value>

export ZEROCLAW_channels__git__<alias>__private_key_path=

zeroclaw config set channels.git.<alias>.provider <value>

export ZEROCLAW_channels__git__<alias>__provider=

zeroclaw config set channels.git.<alias>.proxy_url <value>

export ZEROCLAW_channels__git__<alias>__proxy_url=

zeroclaw config set channels.git.<alias>.repos <value>

export ZEROCLAW_channels__git__<alias>__repos=

default 别名是通常使用的第一个实例。一次性发送也会解析到它：zeroclaw channel send --channel-id git 会专门查找 default 别名，因此请将实例命名为 default，除非所有发送都来自绑定到其他名称别名的代理。将 repos 留空可轮询凭据可见的所有仓库，或将其设置为明确的仓库列表以降低速率使用量。仅当需要处理其他机器人账户的评论时，才设置 listen_to_bots。未知的 provider 值会产生明确的启动错误，而不是静默回退。

各个 provider 的凭据设置不同，并且每个都有自己的加密 secret；两个 walkthrough 都从头到尾涵盖了它：

• **GitHub：**App ID 加上一个私钥。参见 创建 GitHub App。
• Gitea / Forgejo： 访问令牌和 API 基础 URL。参见 创建 Gitea / Forgejo 令牌 (Codeberg)。

事件与路由

除会话之外，channel 会将仓库活动规范化为类型化事件，并按配置路由每种事件类型。将某个事件路由到 sop 会把它派发到一个 Standard Operating Procedure，这是一种具有触发器匹配和审批关卡的确定性、可审计流程。Git SOP fan-in 页面详细说明了 forge 事件如何精确地变为一次 SOP 运行。

已知事件类型：issue_comment.created、issues.opened、pull_request.opened、pull_request.closed、pull_request.merged、pull_request_review_comment.created、workflow_run.completed、workflow_run.failed、release.published。

• 默认值。 在没有 events 表时，channel 以会话式方式运行：issue_comment.created、issues.opened 和 pull_request.opened 会作为消息投递（如上所述，受 mention 门控）；其他所有内容都会被忽略。对于非空表中缺失的事件类型，适用相同的按类型默认值：列出 workflow_run.failed 不会关闭会话。既没有 message = true 也没有 sop 的条目会显式禁用该事件类型。
• 路由某个事件类型就等于订阅它。 该通道会从表中推导出要轮询哪些 API 端点：只有当相应的事件类型被路由时，才会获取审查评论、发布和 Actions 运行，因此未配置的通道成本与之前完全相同。GitHub 目前覆盖了所有列出的事件类型；Gitea/Forgejo 提供程序覆盖 issue 评论、issue/PR 创建、PR 关闭/合并转换、发布、回复、编辑、删除和反应。
• sop 路由。 sop 路由会发出一个由 channel 提供的、主题为 git.<alias>:<event_type> 的 SOP 事件，并携带结构化 JSON 负载。路由后的事件由 SOP 入口消费，而不是作为聊天消息传递。通过在 SOP.toml 中使用用于指定 channel 和实例的 channel 触发器来匹配它（channel = "git"、alias = "main"）；git.<alias>:<event_type> 字符串是由 channel 生成的事件主题，而不是触发器字段。使用可选的 condition 进一步缩小范围，例如 $.event_type == "pull_request.opened" 或 $.repo == "octo/repo"。
• 按路由进行 mention 门控。 mention_only 门控适用于消息路径上的对话事件。sop-路由事件会跳过它：路由到 pr-triage 的 PR 会被捕获，无论作者是否提到了应用。生命周期/CI/发布事件没有 mention 入口，因此从不受门控。应用自身的活动始终会被丢弃；其他 bot 的活动遵循 listen_to_bots；每次投递都会基于作者的登录名通过 peer-group allowlist。
• 回复表面。 评论、issue 和 PR 事件会回复到其 issue/PR 线程。工作流运行事件会在 forge 报告有关联的 PR 时回复到该运行关联的 PR；否则，对于发布，目标是裸仓库，且代理无法在平台上回复（将这些路由到 SOP 或通过其他工具操作）。
• Events API backbone（可选，GitHub）。 events_backbone = true 还会使用 ETag 条件请求轮询 /repos/{owner}/{repo}/events（每个 repo 每个 tick 一次请求；空闲 repo 会返回 304，几乎没有成本）。注意事项：该 feed 最多会滞后约 5 分钟，payload 会被裁剪，而且 Actions events never appear in it：workflow runs 始终使用其专用 endpoint。凡是同时出现在 feed 和目标 endpoint 中的内容都会去重，因此可以安全组合。Gitea/Forgejo 目前会忽略此选项。

操作说明

• **速率预算：**在 GitHub 上，每个安装每小时获得 5,000 个请求；会话式默认配置在每个轮询 tick 中每个仓库消耗 2 个请求（5 个仓库、30 秒间隔 ≈ 每小时 1,200 个）。每个额外路由的端点族（review comments、releases、Actions runs）会为每个仓库每个 tick 再增加 1 个请求，而 Events API 骨干会增加 1 个条件请求（空闲仓库上的 304 在实际上是免费的）。Gitea/Forgejo 的速率限制取决于实例。在收到速率限制响应时，通道会退避，直到限制窗口重置。
• 多个仓库： 当 repos 为空且凭据可见的仓库超过 100 个时，仅轮询第一页（GitHub 会记录一条警告）。在这种情况下请显式列出 repos。

安全

公开仓库上的 issue 和 PR 评论属于对抗性输入。保持 mention_only = true，通过 peer group 对发送者进行限制（空 peer 集拒绝所有人，["*"] 接受任何人），并且对于面向公众的仓库，将 autonomy 保持在 Supervised 或更低。这与 social channels 的指导相同。

相关文档

• 设置凭据： 创建 GitHub App · 创建 Gitea / Forgejo 令牌（Codeberg）
• 谁可以访问该代理： Peer Groups
• 代理可以执行的操作： Security & Autonomy · Autonomy levels
• 事件驱动自动化： 标准操作程序 · Git SOP fan-in
• 更大的视角： Agents · Channels overview