---
summary: "查找公共 GitHub 问题和拉取请求，并阅读聊天旁边的项目"
title: "GitHub"
doc-schema-version: 1
read_when:
  - "您希望在对话旁边打开 GitHub 链接"
  - "您需要启用或禁用 GitHub 链接预览和阅读器"
  - "您希望代理搜索选定的公共 GitHub 存储库"
---

# GitHub

捆绑的 GitHub 插件向 [Control UI](/web/control-ui) 以及 `github_read` 和 `github_search` 代理工具添加了公共存储库链接预览和只读阅读器。它与 [GitHub Copilot 模型提供者](/providers/github-copilot) 是分开的。

## <a id="upgrading-with-an-existing-plugin-allowlist"></a> 使用现有插件白名单进行升级

以前位于核心中的 GitHub 预览现在属于捆绑的 `github` 插件。非空 `plugins.allow` 列表仍然具有权威性：如果它省略 `github`，则悬浮卡和阅读器都保持不可用，并且链接会在外部打开。 OpenClaw 是否在升级或 Doctor 修复期间将 **not** 添加插件到现有允许列表中。

要恢复预览，请将 `github` 附加到 **existing** `plugins.allow` 列表，而不删除其其他条目，然后在 **Plugins** 中启用 GitHub。保持 `plugins.deny` 和显式禁用条目与您的选择一致。 Doctor 解释了当隐式白名单排除阻止该功能时的恢复情况。要有意将其关闭并静音该通知，请设置 `plugins.entries.github.enabled: false`。

## <a id="read-an-item-beside-chat"></a> 在聊天旁边阅读项目

该插件默认启用。连接到网关，然后单击聊天中的公共 GitHub 问题、拉取请求或提交链接。阅读器在对话旁边打开，带有 GitHub 图标和 GitHub**链接上的**Open。将鼠标悬停或聚焦问题或拉取请求链接以查看其预览。问题和拉取请求芯片显示完整的 `owner/repo#number` 参考，包括从会话存储库解析的速记参考。描述性链接标签保持不变。登录、OAuth、个人资料、存储库和其他常规 GitHub 页面仍然是普通链接：本机项目预览和通用页面预览后备都不会获取它们。登录重定向查询中的 PR 或问题 URL 不会使登录链接可预览。

每个阅读器选项卡都有自己的后退和前进历史记录。打开同一个 URL 会选择其现有选项卡。阅读器内的链接导航当前选项卡； **+** 按钮启动另一个选项卡。内存中最多保留十个选项卡。关闭页面会丢弃文档和历史记录。读者遵循会话面板的响应式布局；在手机上，它可以位于聊天下方或随面板展开。

阅读器包括描述、讨论评论、已发布的内联 PR 审阅评论以及文件和差异上下文、提交评论和可扩展文件差异。标头分隔项目状态、作者、更改计数和 PR 分支。 **Overview**、**Checks**、**Files** 和 **Discussion** 快捷方式无需离开读者即可跳转到相关部分。

拉取请求显示确切的头提交的检查运行和提交状态。展开检查摘要以检查各个结果并打开其源日志。默认情况下，失败的检查会展开。待处理、失败、通过、跳过、空和不可用的结果保持清晰；部分响应并不意味着所有检查都已通过。这些结果描述的是 CI，而不是批准或合并准备情况。使用 **Refresh** 再次获取当前的 PR 及其检查。

描述和回复会在散文、表格、链接标签和披露摘要中呈现命名表情符号短代码，例如 `:white_check_mark:` 和 `:rocket:`。代码、URL、未知的短代码和简单的表情符号（例如 `:)`）保持原义。

HTML 描述和回复中的评论保持隐藏，匹配 GitHub；代码内的文字注释示例仍然可见。 Markdown 图像和独立的 HTML 图像附件可以内嵌显示。 GitHub 插件通过网关匿名获取公共用户附件，包括 GitHub 的附件重定向，因此它们不需要浏览器 CORS 标头。请求不发送 GitHub 凭据、cookie 或引荐来源网址。解析器支持最多 2 个 MiB 的 PNG、JPEG、GIF 和 WebP 附件。如果解析失败，阅读器保留原始的anonymous-CORS图像路径；仍然无法加载的图像保留全尺寸的外部链接。每个加载的文档都会限制并发请求和缓存的图像数据；关闭其选项卡或替换文档会停用该缓存。脚本和连接策略不变；远程内容无法运行脚本或应用程序小部件。

## <a id="ask-the-agent-to-read-an-item"></a> 请客服人员读取项目

向代理提供公共 GitHub 问题、拉取请求或提交 URL。 `github_read` 工具通过网关读取它并返回标题、描述、适用的讨论和审查意见、文件更改和拉取请求检查。它接受 `url` 和可选的 `refresh: true` 来获取当前内容。

此工具适用于沙箱内没有 GitHub 凭据或出站网络访问权限的允许沙箱代理。网关选择调用代理的托管身份，或使用与读取器相同的服务 token/anonymous 后备。该工具无法选择其他代理或公开凭据。当前的调用、工具和身份权限在交付过程中仍然需要，包括缓存的读取。

`github_read` 包含在编码配置文件和默认沙箱工具白名单中。显式工具允许列表和拒绝规则仍然具有权威性。如果您维护自定义沙箱允许列表，请包含 `github_read` 以允许它。禁用 `github` 将删除该工具以及 UI 读卡器。该工具读取已知的参考文献；它不会搜索、发布、编辑或合并 GitHub 内容。

以下同样的限制也适用。检查 `partial`、`bodyTruncated`、`commentsTruncated`、`filesTruncated` 和单独的 comment/patch/check 标记；有界结果并不能证明完整的讨论或差异已被阅读。

## <a id="ask-the-agent-to-find-issues-or-pull-requests"></a> 要求代理查找问题或拉取请求

将 `github_search` 与选定的公共 `repository`（例如 `openclaw/openclaw`）一起使用。为每个呼叫选择 `kind: "issue"` 或 `kind: "pull"`。当您需要两种时分别搜索； GitHub 应用程序用户令牌每个查询需要单一类型。可选的 `query` 关键字与文本匹配，`state` 选择 `all`、`open` 或 `closed`。省略查询以仅使用过滤器。查询文本是文字：不接受 GitHub 限定符、引号、反斜杠和括号，并且布尔词不能扩大存储库范围。引用的关键字必须符合 GitHub 的 256 个字符的搜索限制；如果该工具拒绝长查询，请使用更少或更短的单词。

每次调用最多返回 20 个项目，按最近更新的顺序排列，其 URL 为 `github_read` 可以打开。从 `page: 1` 开始，然后对返回的 `nextPage` 重复相同的过滤器。空 `nextPage` 结束可用页面。 `incomplete: true`表示GitHub没有完成搜索； `limited: true` 表示存在超过前 1,000 个匹配项。优化查询或过滤器，而不是假设任一结果都是详尽的。随着 GitHub 上的问题和拉取请求发生变化，结果可以在页面之间移动。

搜索使用与阅读相同的网关持有的身份和当前调用权限。在搜索之前和交付结果之前，所选存储库必须是公开的。该工具包含在编码配置文件和默认沙箱白名单中；如果需要，将 `github_search` 添加到自定义白名单。显式拒绝规则和插件禁用仍然适用。速率限制错误包括 GitHub 的重试延迟（如果可用）。搜索不会发现存储库、搜索私人内容、发布、编辑或合并。

## <a id="enable-or-disable-the-plugin"></a> 启用或禁用插件

在Control UI中打开**Plugins**来管理GitHub插件。对应的配置是：

```json5
{
  plugins: {
    entries: {
      github: { enabled: false },
    },
  },
}
```

通过正常的网关配置流程应用配置。功能更新可删除禁用的阅读器，而无需重新连接浏览器。禁用后，该插件不会贡献任何读卡器或悬停卡，并且 GitHub 链接会在外部打开。

## <a id="limits-and-unavailable-content"></a> 限制和不可用的内容

- 该阅读器是公用且只读的。在 GitHub**上使用**Open 用于私有存储库、发布评论或合并拉取请求。
- 预览和阅读器文档使用所选代理的托管 GitHub 身份，或在未选择托管身份时配置的 Control UI GitHub 令牌和网关环境回退。如果没有凭据，他们可以使用 GitHub 的共享匿名 IP 配额。经过身份验证的文档仅供公开：读者在返回新的或缓存的内容之前检查存储库的可见性和身份。身份更改会中止过时的请求。附件图像保持匿名。
- 每个评论收藏仅限20条； PR 讨论和内嵌评论有单独的限制。最多显示 30 个已更改的文件。
- PR 检查每次检查运行和提交状态最多使用一页，并最多显示 100 个结果。不完整或不可用的检查保留 GitHub 的链接。
- 长文本和补丁是有界的。不完整的内容会被标记，而不是作为完整的对话或差异呈现。
- 未缓存的悬停预览共享两秒的上游请求预算。缓慢的头像或合著者查找被省略；缓慢的所需元数据返回可重试的不可用错误。完整读取器保持其较长的请求超时。
- 使用相同 GitHub 身份的读者可共享 Hover 预览一分钟。并发请求共享一次提取，但每个读取器在结果到达时仍必须具有访问权限。当后台刷新运行时，过期的预览可能会显示为陈旧的标记。缓存传递检查当前凭证一次；每个上游调度也会检查它。 **Refresh** 等待当前元数据。刷新使用 GitHub ETag 来表示未更改的项目和提交响应；身份更改、驱逐或刷新失败会废弃那些缓存的响应。每次经过身份验证的刷新都会再次检查存储库可见性。当相应的项目或提交未更改时，刷新重复使用作者和合著者头像最多五分钟。
- 慢速预览读取（500 毫秒或更长）身份准备、cache/load 等待、交付凭证检查、元数据渲染、可选装饰和上游 authentication/network 等待的日志阶段持续时间。网络计时涵盖响应标头； metadata/decorations 包括响应主体读取。这些诊断忽略了 URL、项目内容和凭据。
- **Refresh** 再次请求当前项目。速率限制、已删除的项目和不可用的服务会在阅读器和悬停卡中显示其具体说明，包括 GitHub 的重试延迟（如果可用）。缓存的预览详细信息与失败通知保持可见。使用阅读器的 **Retry** 操作或 GitHub**上的**Open ；服务器的 API 配额与您登录的浏览器会话是分开的。

## <a id="plugin-author-integration"></a> 插件作者集成

GitHub 使用 [Plugin SDK](/plugins/sdk-overview/host-hooks#docked-link-readers) 中的通用对接链接读取器贡献。该插件拥有 URL 匹配、GitHub API 请求、缓存以及将源数据映射到被动读取器模型中。 Control UI 拥有选项卡、布局、安全渲染和键盘交互。