配置 — agent 工具的 GitHub 身份

tools.github 选择代理执行所使用的共享托管 GitHub CLI 身份，并定义哪些执行路径会收到其凭据。

tools.github¶

GitHub CLI 身份默认为原生身份。当省略 tools.github 时，本地代理工具、Codex 工具框架和 Agent Settings 遵循正常的 gh 解析顺序：优先使用 Gateway 进程中的 GH_TOKEN 或 GITHUB_TOKEN，其次是运行时用户的 gh 密钥环/配置。Git 作者信息来自所选代理的工作区。

Gateway 的 GitHub 读取和 Publish PR 账户选项会复用成功的 gh auth token --hostname github.com 读取结果，最长 60 秒，与凭据验证缓存保持一致。因此，主机上的 gh auth login、logout 或 switch 更改最多可能需要 60 秒才能在这些读取界面上生效。并发读取共享一次原生查找。OAuth 关闭、配置文件替换或轮换以及断开连接都会清除原生令牌缓存。环境令牌、托管配置文件凭据、调用者权限和会话访问仍然实时检查；发布操作会获取自己的实时原生凭据。失败的令牌读取和匿名访问缺失证明不会被缓存。

使用 Settings → Profile → GitHub connections 可同时查看 My GitHub 和 System GitHub。管理员明确选择 For the system 来配置此共享执行身份；常规连接流程对已识别用户默认为 For me。每个代理的覆盖设置仍是 Agents → Tools 下的高级管理设置。个人连接与 tools.github 是分开的：它支持明确选择的 Gateway 代理发布，并且不会更改代理 Shell 凭据、共享默认值或已验证的登录身份。请参阅 GitHub connections。

OpenClaw 会显示一次性的用户代码，并在旁边提供一个 Copy code 按钮；点击该代码可全选以便手动复制。打开固定的 https://github.com/login/device 链接，粘贴代码，并批准 repo、workflow、read:org 和 gist。后两者是 GitHub CLI 最低经典令牌契约的一部分。Gateway 负责设备代码、令牌交换、账户验证、私有托管的 gh 配置文件以及轮换的刷新令牌。设置和刷新过程不会在浏览器响应中返回凭据，也不会将其放入配置、日志、命令参数、记录文本或模型运行时环境中。OpenClaw 所有的本地执行仅通过其私有进程启动环境接收访问令牌，如下所述。

OAuth 访问令牌大约在八小时后过期。Gateway 会在过期前刷新它们，验证持久的 GitHub 账户 ID，并在同一私有配置文件中原子性地替换凭据。新的本地执行启动使用刷新后的凭据；已在运行的本地执行会保留其启动令牌直到退出。在访问令牌过期后，请重启长时间运行的 Shell。过期或被拒绝的刷新令牌会显示为 Reconnect required。刷新永远不会阻塞 Gateway 启动。

Use a PAT instead 保留了细粒度个人访问令牌设置作为明确的替代方案。浏览器会将粘贴的令牌作为一次性交接放入秘密存储中。Gateway 在向 GitHub 的 /user 端点验证所提供的凭据之前，会硬删除该交接。两种设置路径都会写入一个账户拥有的私有 gh 配置文件，而不会更改主机的全局 GitHub CLI 登录或操作系统密钥环，默认 Git 作者身份为账户的规范 GitHub noreply 身份，并且只存储不含秘密的 OpenClaw 配置：

{
  tools: {
    github: {
      profileId: "ghp_0123456789abcdef0123456789abcdef",
      kind: "oauth",
      gitAuthor: { name: "Automation User", email: "automation@example.com" },
    },
  },
  agents: {
    entries: {
      reviewer: {
        tools: {
          github: {
            profileId: "ghp_fedcba9876543210fedcba9876543210",
            gitAuthor: { name: "Review Agent" },
          },
        },
      },
    },
  },
}

省略 agents.entries.<id>.tools.github 会继承系统身份。代理对象是一个完整的托管覆盖配置。Settings 会分别显示生效身份和所选配置范围，因此编辑 System 永远不会伪装成代理覆盖。如果配置的托管配置文件缺失、无令牌或已损坏，GitHub 状态会报告 configured_unavailable，而不是报告原生账户。Gateway 代理的发布操作会验证所选配置文件自己的凭据，并为每个子操作固定该凭据；缺失的配置文件无法将发布重定向到原生身份验证。普通的代理 Shell 执行继续使用共享或每代理选择，并遵循下述执行边界。

托管身份选择 gh CLI/API 账户以及可选的 Git 作者/提交者元数据。OpenClaw 准备一个非秘密的覆盖层，其中包含私有 GH_CONFIG_DIR、环境令牌清理规则和配置的作者字段。对于本地执行，它不会安装凭据助手、重写 SSH 远程地址、添加 HTTP 授权头，或以其他方式覆盖现有仓库的 Git 网络凭据。命令仍然使用 PATH 上现有的 gh，包括任何由操作员管理的保护或缓存包装器。

对于 OpenClaw 拥有的 exec 且 host=gateway（包括 Pi exec 和 Codex gateway_exec），本地启动所有者在每次进程启动前立即读取并验证所选配置文件。它仅在私有子环境中将该访问令牌放入 GH_TOKEN，并清除 GITHUB_TOKEN；审批载荷和共享运行环境保持非秘密。缺失、无令牌或不安全的配置文件会在命令启动前拒绝本地执行，而不是允许回退到原生密钥环。这也适用于可能间接调用 gh 的命令。重试前请重新连接或更改 GitHub Identity 选择。已启动的命令即使配置文件之后消失，也会保留其选定的凭据；下一次 exec 启动时会重新读取配置文件。

Codex 原生 shell 是一个独立的边界。 原生的 exec_command 和 shell 执行仍然会收到非机密的配置文件叠加层，而不是私有的启动时凭据绑定。GH_CONFIG_DIR 不会隔离操作系统密钥环：如果所选配置文件消失或丢失其 token，GitHub CLI 可以回退到原生密钥环凭据。当需要启动绑定的托管身份保证时，请使用 gateway_exec。GitHub 状态和 Gateway 拥有的发布保证不会延伸到原生 shell 执行。

选择不同的身份或继承目标会为新运行选择另一个配置文件。已获准的运行保留其先前的配置文件选择，已启动的本地 exec 进程在退出之前保留其启动 token。已退役的配置文件会在下次 Gateway 重启时被清理，因此更改此设置并不会立即撤销凭据。

托管配置文件提供执行和协调身份；它们不是操作系统用户安全沙箱。在同一操作系统账户下具有无限制主机执行权限的进程可以访问账户拥有的文件，包括托管的 gh 配置文件。当需要对抗性隔离时，请使用 OpenClaw 沙箱、专用主机或专用操作系统用户。

OpenClaw worker-turn 云端工作进程每回合都会通过其私有启动信封收到生效的共享身份。工作进程将访问 token 写入其一次性状态目录中的私有每回合配置文件，并在下次绑定之前移除先前的配置文件；上述相同的操作系统用户限制也适用于工作进程所在的主机。密封的工作进程启动器为每个 exec 子进程提供与本地 exec 相同的启动时凭据绑定。GitHub CLI 必须安装在工作进程所在的主机上；捆绑包包含启动器，而不是 gh。对于 GitHub 仓库，检出使用会话拥有的分支和 HTTPS origin；HTTPS Git 认证使用 gh auth git-credential，并清除继承的凭据辅助程序。提交和推送直接在工作进程上进行。对账将文件内容返回给 Gateway 工作树，而不是提交历史。在每个回合开始时，当本地分支落后时，工作进程会将其检出快进到 origin 上的会话分支，引入先前工作进程推送的历史；发生分叉的本地分支则保持不变。已配对设备自身的 GitHub CLI 登录不用于此绑定。

OpenClaw 沙箱、普通节点主机 exec 和 Codex remote-exec 部署仍然不会收到 Gateway 托管的 GitHub 凭据。github_publish 工具对 remote-exec 会话仍然可用：它记录一个受约束的发布请求，而不包含凭据或仓库权限。在精确的工作区结果经过对账并被接受后，Gateway 以已验证的生效 GitHub 用户身份提交剩余更改，通过一次性 HTTPS 凭据辅助程序推送权威会话分支，并创建或复用草稿拉取请求。

发布可能会一直等待，直到请求回合结束且其工作区被接受。其结果会附加到会话记录中；这不会启动另一个 agent 回合。当授权任务还包括审查、CI 修复或落地（landing）时，agent 必须在结束请求回合之前安排单独的后续。草稿 PR 或发布回执并不能完成落地请求。

Gateway 托管的 agent 会为普通消息和内部后续检查发布可用性，包括当请求者让出控制权后子 agent 完成时。该检查使用当前会话的工作区和 GitHub 身份。如果发布不可用，github_identity_status 仍然可用，以说明身份设置或重新连接的需求，但需遵守会话的工具策略。独立的本地运行和禁用工具的运行不会暴露这些托管发布工具。

内置、Codex 和 Copilot 工具界面使用相同的主机预置可用性。Harness 选项不能取代主机的决定；工具配置文件和 Gateway 授权仍然适用。

发布使用普通的 Git 属性转换来暂存工作区更改。它保留未更改的已提交文件字节，包括现有的 CRLF 行尾，而不是重新规范化不相关的已跟踪文件。

仅限会话内的写访问权限可以通过配置的共享账户发布来自请求者自身会话的普通源代码更改。另一个会话的成员身份不授予该发布权限。对 .github/workflows/*.yml 或 .github/workflows/*.yaml 中 GitHub Actions 定义的更改需要原始请求者的完整操作员写入权限。这包括已提交的编辑、删除和重命名。如果已接受的快照更改了这些定义，发布会保留已保存的工作，并请求维护者代为发布，或要求请求者在再次请求发布之前还原这些定义。该检查将已接受的内容与已发布的分支或原始拉取请求基础分支进行比较，因此未更改的工作流定义不会阻塞普通编辑。

本地会话拥有的工作树可以在 Control UI 中使用相同的 Publish PR 操作。Gateway 根据当前会话所有权确定受管工作树、仓库、分支、基础（base）和头部（head）。它绝不会接受来自浏览器或模型的这些授权事实。发布重试使用持久的请求 ID、精确的提交标记、远程分支观察以及按 head 分支查找拉取请求，因此 Gateway 重启或响应丢失不会产生重复的提交、推送或拉取请求。

在发布期间，如果请求连接关闭或发布权限结束，已接受的 PR 响应仍然会完成其对应的回执。成功的本地分支更新同样会在执行保留工作区所有权时完成其匹配的索引事务。此结算不会授权另一次推送或 PR 创建；未确认的结果保留其现有的恢复或个人确认要求。

在创建发布提交或更改本地分支和索引之前，Gateway 会验证已接受的提交与经过身份验证的拉取请求基础分支共享 Git 历史，并且已发布的分支不存在或者是已接受的本地 head 的祖先。重新创建本地分支或使其 reflog 过期不会使共享的提交历史失效。查找失败不会被当作分支不存在。经过变基、落后或不相关的分支会在新的本地发布更改之前被拒绝，并附有恢复指导。已启动的请求所属索引事务的恢复仍然会先执行。推送以精确观察到的远程 head 或分支不存在为条件，因此并发的分支更改会被拒绝。broker 永远不会自动重写已发布的历史或本地历史。

要刷新现有 PR，请保留其已发布的历史记录，并在已发布的 head 之上应用预期编辑。如果重写历史是有意为之，请改用新的会话分支和替代 PR。不要仅仅为了让变基后的分支可推送，就将旧的已发布历史合并回来。

对于未更改内容的单独请求，当远程和本地 head 匹配、已接受的索引和工作区与该树匹配，并且 head 已有发布标记以及所有当前所需的贡献者 trailer 时，会复用所属的开放 PR，而不创建新提交。首次发布仍会创建请求拥有的标记，包括针对已提交的工作；缺少贡献者署名也需要新标记。仅限仓库的检查点发布已会将未更改的已发布树拒绝为 no_changes，并且仅扩展其已记录的已发布 head。它无法采用针对该分支的外部更改；如果已记录的 head 不再匹配，请从新的会话分支发布预期的检查点。这些路径保留其现有的重试和溯源契约。对于仅标题/正文的编辑，请直接更新 PR 文本，而不是请求工作区发布；复用 PR 不会更新其文本。

验证会证明是哪个账户响应了 GitHub API 请求。状态会报告凭据类型、访问过期时间、刷新可用性、OAuth 作用域以及 Git 作者，同时区分缺少凭据、未验证的传输失败和 GitHub 速率限制，而不返回 gh 诊断信息。特定于仓库的授权在精确的仓库操作成功之前仍未知；/user 不能证明写入访问权限。

移除代理覆盖或选择原生凭据后，配置更改会删除关联的本地刷新记录。已在运行的本地进程可能会保留旧配置及其当前访问令牌，直到它们退出、重启或令牌过期，而新运行会立即使用更新后的身份。此本地更改不会在 GitHub 上撤销授权；如有需要，请从 OAuth 应用程序的 GitHub 设置中单独撤销。

Control UI 的 issue 和拉取请求悬停预览使用所选代理的有效受管 GitHub 身份，包括继承的系统身份。不可用的受管身份会产生可操作的错误，而不是切换到其他凭据。在没有受管选择的情况下，预览会保留可选的 gateway.controlUi.github.token 服务凭据、共享的 GH_TOKEN/GITHUB_TOKEN 环境变量回退以及匿名公共访问。预览仍仅限公共访问，并且其缓存以所使用的凭据为范围。项目发现继续使用独立的服务凭据。当此 SecretRef 显式指定时，OpenClaw 会将其精确的环境或存储名称从代理执行中排除。自定义名称不会清除原生身份使用的无关 GH_TOKEN 或 GITHUB_TOKEN 值；名为 GH_TOKEN 或 GITHUB_TOKEN 的引用会排除该精确变量。

如果预览或详细视图报告“GitHub 请求已不再活动”，请重新打开它以重试。这描述的是被中断的请求，而不是你的 GitHub 账户发生了变化；无需重新连接 GitHub。