本页内容
本页内容
网关
配置 — 代理工具的 GitHub 身份
tools.github 选择代理执行所使用的共享托管 GitHub CLI 身份，并定义哪些执行路径接收其凭证。
tools.github
默认情况下，GitHub CLI 身份是本机的。当省略 tools.github 时，本地代理工具、Codex 工具和代理设置将遵循正常的 gh 分辨率：网关进程中的 GH_TOKEN 或 GITHUB_TOKEN 优先，其次是运行时用户的 gh keyring/config. Git 作者来自所选代理的工作区。
网关 GitHub 读取和发布 PR 帐户选项可重复使用成功的 gh auth token --hostname github.com 读取长达 60 秒，与凭证验证缓存匹配。因此，主机 gh auth login、logout 或 switch 更改最多可能需要 60 秒才能出现在这些读取表面上。并发读取共享一个本机查找。 OAuth 关闭、配置文件替换或轮换以及断开连接清除本机令牌缓存。环境令牌、托管配置文件凭据、调用者权限和会话访问仍会实时检查；出版物获得自己的实时本地凭证。失败的令牌读取和匿名访问缺席证明不会被缓存。
使用设置→配置文件→GitHub连接一起查看我的GitHub和系统GitHub。管理员明确选择为系统来配置这个共享执行标识；一般连接流默认为 对于我来说 对于已识别的用户。每个代理覆盖仍然是 Agents → Tools 下的高级管理设置。个人连接与 tools.github 是分开的：它支持显式选择的网关代理发布，并且不会更改代理 shell 凭据、共享默认值或经过验证的登录身份。请参阅 GitHub 连接。
OpenClaw 显示一次性用户代码，旁边有 复制代码 按钮；单击代码会完整选择它以进行手动复制。打开固定的 https://github.com/login/device 链接，粘贴代码，并批准 repo、workflow、read:org 和 gist。后两者是 GitHub CLI 最小经典代币合约的一部分。网关拥有设备代码、令牌交换、帐户验证、私人管理的 gh 配置文件和轮换刷新令牌。设置和刷新不会在浏览器响应中返回凭据，也不会将其放入配置、日志、命令参数、脚本或模型运行时环境中。 OpenClaw-owned 本地执行程序仅通过其私有进程启动环境接收访问令牌，如下所述。
OAuth 访问令牌将在大约八小时后过期。网关在到期前刷新它们，验证持久的 GitHub 帐户 ID，并自动替换同一私有配置文件中的凭证。新的本地执行启动使用刷新后的凭据；已经运行的本地执行程序会保留其启动令牌，直到退出。在访问令牌过期后重新启动长时间运行的 shell。过期或被拒绝的刷新令牌显示为 Reconnect required。刷新永远不会阻止网关启动。
托管配置文件和个人出版物使用 github.com 及其公共帐户验证端点。企业存储库设置保留该颁发者绑定。 Enterprise 存储库读取和共享发布需要绑定到所选 Enterprise 主机的本机凭证；单独的发现服务凭证还保留其声明的主机绑定。
使用 PAT 代替 保留细粒度的个人访问令牌设置作为显式替代方案。浏览器将粘贴的令牌放置在秘密存储中作为一次性切换。在使用 GitHub 的 /user 端点验证提供的凭证之前，网关会硬删除该切换。两个设置路径都会写入帐户拥有的私有 gh 配置文件，而不更改主机的全局 GitHub CLI 登录名或 OS 密钥环，默认 Git 作者身份为帐户的标准 GitHub noreply 身份，并且仅存储无秘密的 OpenClaw 配置：
省略 agents.entries.<id>.tools.github 将继承系统标识。代理对象是完全托管的覆盖。设置分别显示有效身份和选定的配置范围，因此编辑 System 永远不会伪装成代理覆盖。如果配置的托管配置文件丢失、无令牌或损坏，GitHub 状态将报告 configured_unavailable，而不是报告本机帐户。网关代理的发布验证所选配置文件自己的凭据并将其固定到每个子操作；丢失的配置文件无法将发布重定向到本机身份验证。普通代理 shell 执行继续使用共享或每个代理选择，执行边界如下所述。
托管身份选择 gh CLI/API 帐户和可选的 Git author/committer 元数据。 OpenClaw 准备一个非秘密覆盖，其中包含私有 GH_CONFIG_DIR、环境令牌清理和配置的作者字段。对于本地执行，它不会安装凭据帮助程序、重写 SSH 远程文件、添加 HTTP 授权标头或以其他方式覆盖现有存储库的 Git 网络凭据。命令仍然使用 PATH 上现有的 gh，包括任何操作员管理的保护或缓存包装器。
对于 OpenClaw- 拥有的 exec 和 host=gateway，包括 Pi exec 和 Codex gateway_exec，本地启动所有者会在每个进程启动之前立即读取并验证所选配置文件。它将 GH_HOST 固定到该配置文件的主机，并将访问令牌仅放置在匹配的私有子凭证系列中：github.com 和 *.ghe.com 的 GH_TOKEN，或 GitHub Enterprise Server 的 GH_ENTERPRISE_TOKEN。另一个系列以及GITHUB_TOKEN和GITHUB_ENTERPRISE_TOKEN均被清除； GH_HOST 是默认值，而不是对显式 CLI 主机选择的限制。批准有效负载和共享运行环境仍然是非秘密的。丢失、无令牌、错误主机或不安全的配置文件会在命令启动之前拒绝本地执行，而不是允许本机密钥环回退。这也适用于可能间接调用 gh 的命令。重试之前重新连接或更改 GitHub 身份选择。即使配置文件随后消失，启动的命令也会保留其选定的凭据；下一次执行启动时会再次读取配置文件。
托管 Codex 执行使用相同的主机拥有的边界。 当选择托管 GitHub 身份运行时，OpenClaw 将禁用 Codex-native shell 执行并通过其主机拥有的执行工具路由命令。这些工具保留执行代理的选定配置文件、调用者权限、批准检查和取消生命周期。丢失或不可用的托管配置文件会拒绝执行，而不是回退到本机帐户；重试之前，请重新连接或更改“设置”中的身份。如果没有托管选择，本机 Codex 默认值将保持不变。此路由不会将网关凭据导出到普通的配对节点执行。
选择不同的身份或继承目标将为新运行选择另一个配置文件。已承认的运行会保留其先前的配置文件选择，并且已启动的本地执行进程会保留其启动令牌，直到退出。停用的配置文件将在下次网关重新启动时清除，因此更改此设置不会立即撤销凭据。
如果清理无法读取目录的标识，它将保持该目录不变，记录包含路径和原因的警告，并继续检查其余配置文件。丢失的目录将被跳过而不发出警告。
托管配置文件提供执行和协调身份；它们不是 OS-user 安全沙箱。在同一 OS 帐户下具有不受限制的主机执行的进程可以访问帐户拥有的文件，包括托管 gh 配置文件。当需要对抗性隔离时，使用 OpenClaw 沙箱、专用主机或专用 OS 用户。
OpenClaw worker-turn 云工作人员通过其私有启动信封接收最后一个后台准备的共享身份。绑定身份不会等待转弯路径上的 GitHub 发现。此绑定不依赖于 allowInSandbox 或角色的 sandbox: "required" 策略，因此请勿让不得使用共享帐户的人员远离工作人员配置文件。工作人员将访问令牌写入其一次性状态目录中的私有每回合配置文件。当存储库绑定的轮次保持授权时，工作人员心跳会从同一选定帐户更新该配置文件；稍后的 exec 启动使用更新的令牌，而运行命令则保留其启动令牌。当调用者、会话编写者、布置或所选配置文件失去权限时，续订将停止。在回合承认的命令和飞行中的凭证写入解决后，配置文件将被删除；上述 OS-user 限制同样适用于工作主机。密封的工作启动器为每个 exec 子级提供与本地执行程序相同的启动时凭证绑定。 GitHub CLI必须安装在worker主机上；该捆绑包包括启动器，而不是 gh。签出使用会话拥有的分支和 GitHub 存储库的 HTTPS origin； HTTPS Git 身份验证使用 gh auth git-credential，并清除了继承的凭据帮助程序。提交和推送直接发生在工作人员身上。协调将文件内容返回到网关工作树，而不是提交历史记录。每次启动时，当本地分支落后时，工作人员都会将其结帐快进到 origin 上的会话分支，从而引入较早工作人员推送的历史记录；一个分歧的本地分支保持不变。配对设备自己的 GitHub CLI 登录名不用于此绑定。
默认情况下，OpenClaw 沙箱不包括网关的托管 GitHub 凭证； per-agent 沙箱选择加入 使它们能够用于代理自己的 Docker 或 Podman 沙箱。普通节点主机 exec 和 Codex remote-exec 放置仍然不会收到这些凭据。 github_publish 工具仍然可用于远程执行会话：它记录没有凭据或存储库权限的有界发布请求。在协调并接受确切的工作区结果后，网关以经过验证的有效 GitHub 用户身份提交剩余的更改，通过一次性 HTTPS 凭证助手推送权威会话分支，并创建或重用草稿拉取请求。
默认沙箱工具策略还允许 github_publish 进行符合发布条件的托管会话。该工具使用相同的网关发布者，并且不需要沙箱内的 allowInSandbox、托管 GitHub 配置文件安装或 GitHub 凭据。明确的工具拒绝和限制性自定义许可名单仍然适用；将工具添加到默认策略不会为未绑定工作区或不可用的 GitHub 帐户创建发布可用性。
发布可以等到请求的轮次完成并且其工作空间被接受为止。其结果附加到会话记录中；这不会启动另一个代理回合。当授权任务还包括审查、CI 维修或着陆时，代理必须在结束请求的回合之前安排单独的延续。草稿 PR 或发布收据未完成登陆请求。
具有完全操作员写入权限的人员可以请求登陆同一对话，包括来宾创建的沙盒会话。代理使用 github_publish 和 action: "inspect" 来读取会话已完成的共享发布及其当前的 GitHub 状态。经过审查和必要的检查后，action: "ready" 将其草稿标记为就绪，并 action: "merge" 将其合并。要关闭PR而不合并，请在检查后使用action: "close"。这三个写入都需要检查requestId和expectedHeadCommit； merge 还需要显式 mergeMethod（merge、squash 或 rebase）。 GitHub 仍然强制执行存储库权限和合并要求。这些操作不会启用自动合并或删除分支、工作区或对话。
对于委派工作，代理必须明确选择孩子的 publishingSessionKey。即使授权人员自己的工作区不符合发布条件，其托管父级对话也会收到这些 PR 操作；该父级的发布仍然不可用。网关验证发布会话是否属于此会话，并将操作绑定到其记录的 PR。更改的出版物或 GitHub 标题需要再次检查和审查。如果操作的响应被中断，请在重试之前检查同一出版物；已经准备好、已经合并或已经关闭的请求将返回其观察到的状态，而无需再次写入。关闭会保留分支、工作区和对话历史记录；它不会重新打开已关闭的 PR。检查失败或凭据不可用会使保存的工作完好无损。
只有当前的完整编写人员的工具架构和指令才会公开这些 PR 操作。来宾轮流保留草稿发布模式，包括在管理员参与对话之后。每个操作还会重新检查发起人在网关上的当前权限。管理员参与不会提升会话或以后的访客请求，并且访客发布仍仅为草稿。网关保留发布者凭据并仅执行请求的操作；代理仍然负责审查、测试和排序着陆请求。
网关在启动时以及 GitHub 配置、凭据或会话工作区绑定更改时在后台准备发布可用性和共享身份。普通消息和内部延续同步读取最后发布的结果；他们从不等待 GitHub 的发现。在第一个结果准备好之前，或者如果发布不可用，github_identity_status 仍然可以解释身份设置或重新连接需求，具体取决于会话的工具策略。独立本地运行和禁用工具的运行不会公开这些托管发布工具。
后台刷新完成后，下一回合的工具列表中可能会出现最近的身份更改。本机 GitHub CLI 登录更改通过定期后台刷新获取。发布和流程启动仍会在生效点验证其选定的凭据，因此发现不会授权使用已撤销的配置文件。
内置 Codex 和 Copilot 工具表面使用相同的后台准备可用性。harness选项不能取代主持人的决定；工具配置文件和网关授权仍然适用。
发布阶段工作空间通过普通的 Git 属性转换进行更改。它保留未更改的提交文件字节，包括现有的 CRLF 行结尾，而不是重新规范化不相关的跟踪文件。
仅会话写入访问权限可以通过配置的共享帐户从请求者自己的会话发布普通源更改。另一届会话的成员资格并不授予该出版权。对 .github/workflows/*.yml 或 .github/workflows/*.yaml 中的 GitHub 操作定义的更改需要原始请求者的完全操作员写入权限。这包括已提交的编辑、删除和重命名。如果接受的快照更改了这些定义，发布将保留保存的工作并要求维护者发布它，或者要求请求者在再次请求发布之前恢复定义。该检查将确切的路径、模式和 blob（包括删除的定义）与已发布的分支或原始拉取请求基础进行比较。仍然允许未更改的已发布定义。当已发布的定义仍然与其明确的共同祖先匹配时，也允许从经过身份验证的目标分支继承不变的更新。新编写的更改和冲突的解决方案仍然需要完全写入权限，即使结果与目标分支匹配也是如此。仅限存储库的检查点无法证明来自与目标不同的源库的明确继承，也无法从先前复制的工作流内容推断出合并；这些模棱两可的更新仍然需要维护者。
此检查仅涵盖工作流程定义文件。工作流通常运行来自拉取请求分支的代码，例如包脚本、.github/actions/ 下的本地操作和存储库脚本。当签出的 origin 是上游存储库时，发布会将会话分支推送到该存储库，并且其 pull_request 工作流使用存储库机密运行。如果具有仅会话访问权限的人员进行发布，请将结帐的 origin 指向共享帐户拥有的分叉。然后，发布推送到分支并针对父存储库的默认分支打开拉取请求，并且共享帐户不再需要上游写入访问权限才能发布。默认情况下，GitHub 保留来自分叉触发的 pull_request 工作流程的存储库机密。当私有存储库发送秘密以分叉拉取请求时，或者对于运行拉取请求代码的 pull_request_target 工作流时，这种隔离不成立；单独审查这些工作流程。发布本身会创建拉取请求草稿，并且不会合并、批准或标记拉取请求以供审核。同一对话登陆需要共享帐户具有对 PR 基础存储库的合并访问权限。通过必要的审查和检查来保护该基础分支，而无需授予共享帐户绕过权限。仅用于发布的帐户可能仍然无法合并。
本地会话拥有的工作树可以在 Control UI 中使用相同的 Publish PR 操作。网关从当前会话所有权派生受管工作树、存储库、分支、基础和头。它从不接受来自浏览器或模型的那些权威事实。发布重试使用持久请求 ID、精确提交标记、远程分支观察和头分支的拉取请求查找，因此网关重新启动或丢失响应不会创建重复的提交、推送或拉取请求。
在发布期间，如果请求连接关闭或发布权限结束，已接受的 PR 响应仍会完成其拥有的接收。成功的本地分支更新同样会完成其匹配的索引事务，同时执行保留工作区所有权。本和解不授权再次推送或PR创建；未经确认的结果保留其现有的恢复或个人确认要求。
在创建发布提交或更改本地分支和索引之前，网关会验证接受的提交是否与经过身份验证的拉取请求基础共享 Git 历史记录，以及发布的分支是否不存在或是否是接受的本地头的祖先。重新创建本地分支或使其引用日志过期不会使共享提交历史记录失效。失败的查找不会被视为不存在的分支。在新的本地发布更改之前，重新定位的、落后的或不相关的分支将被拒绝并带有恢复指南。已启动的请求拥有的索引事务的恢复仍首先运行。推送是以精确观察到的远程头或分支缺失为条件的，因此并发分支更改会被拒绝。代理从不重写已发布的历史记录或自动重写本地历史记录。
要刷新现有的 PR，请保留其已发布的历史记录并在已发布的头部上应用预期的编辑。如果有意重写历史记录，请使用新的会话分支和替换 PR。不要仅仅为了使重新定位的分支可推送而合并回旧的已发布历史记录。
当远程和本地头匹配、接受的索引和工作区与该树匹配、并且头已经具有发布标记和所有当前所需的贡献者预告片时，对未更改内容的单独请求会重用拥有的开放 PR，而无需新的提交。第一个发布仍然创建一个请求拥有的标记，包括已经提交的工作；缺少贡献者信用也需要一个新的标记。仅存储库检查点发布已经拒绝未更改的发布树，如 no_changes，并仅扩展其记录的发布头。它不能对该分支进行外部更改；如果记录的头不再匹配，则从新会话分支发布预期的检查点。这些路径保留其现有的重试和来源合同。对于 title/body-only 编辑，直接更新 PR 文本，而不是请求工作区发布；重复使用 PR 不会更新其文本。
验证证明哪个帐户回答了 GitHub API 请求。状态报告凭证类型、访问过期、刷新可用性、OAuth 范围和 Git 作者，同时区分丢失的凭证、未经验证的传输故障和 GitHub 速率限制，而不返回 gh 诊断。在确切的存储库操作成功之前，存储库特定的授权仍然未知； /user 不证明写访问权限。
删除代理覆盖或选择本机凭据会在配置更改后删除关联的本地刷新记录。已经运行的本地进程可能会保留旧的配置文件及其当前的访问令牌，直到它们退出、重新启动或令牌过期，而新的运行会立即使用更新的身份。此本地更改不会撤销 GitHub 处的授权；需要时，将其与 OAuth 应用程序的 GitHub 设置分开撤销。
Control UI 问题和拉取请求悬停预览使用所选代理的有效托管 GitHub 标识，包括继承的系统标识。不可用的托管身份会产生可操作的错误，而不是切换到另一个凭据。如果没有托管选择，预览将保留可选的 gateway.controlUi.github.token 服务凭据、github.com 的共享 GH_TOKEN/GITHUB_TOKEN 环境回退以及匿名公共访问。设置gateway.controlUi.github.host与企业服务接入的gateway.github.host匹配；省略的凭证主机表示 github.com。预览版仍仅供公开，其缓存范围仅限于凭证和主机。项目发现继续使用单独的服务凭证。当此 SecretRef 是显式的时，OpenClaw 会从代理执行中排除其确切的环境或存储名称。自定义名称不会清除本机身份使用的不相关的 GH_TOKEN 或 GITHUB_TOKEN 值；名为 GH_TOKEN 或 GITHUB_TOKEN 的引用排除该确切变量。
如果预览或详细视图报告“GitHub 请求不再有效”，请再次打开它以重试。这描述的是中断的请求，而不是对您的 GitHub 帐户的更改；无需重新连接 GitHub。
沙箱选择加入
agents.entries.<id>.tools.github.allowInSandbox 是一个可选布尔值，默认为 false。当代理需要在其自己的 Docker 或 Podman 沙箱内进行 GitHub 访问时，在代理的托管身份上启用它，例如网关上的发布代理，其中每个人类角色都需要沙箱：
使用代理现有生成的profileId；该示例是一个占位符。此设置仅适用于代理，并且在全局 tools.github 下不被接受。替换或重新连接代理的托管标识会保留此设置；删除代理覆盖会清除它。省略它或将其设置为 false 会保留现有的沙箱行为：GH_CONFIG_DIR 不存在，并且 GH_TOKEN 和 GITHUB_TOKEN 为空白。
通过选择加入，OpenClaw 通过现有沙箱绑定管道仅在 /openclaw/github 上以只读方式安装该代理选定的托管配置文件，并将 GH_CONFIG_DIR 设置为该容器路径。沙盒 exec 接收与主机 exec 相同配置的 Git 作者和提交者元数据。启动所有者在每次 exec 启动之前验证配置文件，并在上述匹配的 GH_TOKEN 或 GH_ENTERPRISE_TOKEN 系列中私下转发其访问令牌，而另一个系列以及 GITHUB_TOKEN 和 GITHUB_ENTERPRISE_TOKEN 都被清除。所选配置文件的 GH_HOST 通过容器启动得以保留。丢失、无令牌或不安全的配置文件将拒绝执行；它不会退回到另一个身份。网关继续拥有凭证刷新，现有进程保留其启动令牌。
启用或禁用此设置会更改容器的安装。如果其沙箱已在运行，请在重试之前使用 openclaw sandbox recreate --agent <id>； OpenClaw 保留正在运行的容器并拒绝重复使用过时的安装。
沙箱镜像必须包含 GitHub CLI 命令的 gh，并且 GitHub 请求仍然需要沙箱现有网络策略下的网络访问权限。 OpenClaw 不安装 Git 凭证助手或更改 Git 网络身份验证； Git 使用沙箱内配置的遥控器和凭证助手，就像在主机上一样。该配置文件是只读的，因此通过网关而不是沙箱内的 gh auth login 运行凭证设置或轮换。
有效的 scope: "shared" 拒绝身份注入并记录命名代理的警告，因为该容器可以为其他代理提供服务。角色所需的沙箱使用其有效的每个创建者隔离，并支持选择加入，即使配置的默认范围是 "shared" 也是如此。当启用选择加入时，其他沙箱后端会拒绝配置；他们不会将托管配置文件复制到远程环境。
只读安装可保护配置文件免遭修改，但沙盒代码可以读取和使用其凭据。每个选择加入的代理都会在 openclaw security audit 中生成 WARN 结果。仅对其沙盒代码受该帐户的 GitHub 访问权限信任的代理启用此功能。