配置 — 代理工具的 GitHub 身份
tools.github 选择代理执行所使用的共享托管 GitHub CLI 身份,并定义哪些执行路径会获得其凭据。
tools.github¶
默认情况下,GitHub CLI 身份为原生身份。当省略 tools.github 时,本地代理工具、Codex harness 和 Agent Settings 遵循正常的 gh 解析顺序:来自 Gateway 进程的 GH_TOKEN 或 GITHUB_TOKEN 优先,其次是运行用户自己的 gh 密钥环/配置。Git author 来自所选代理的工作区。
Gateway GitHub 读取和 Publish PR 账户选项会复用成功的 gh auth token --hostname github.com 读取结果长达 60 秒,与凭据验证缓存保持一致。因此,主机上的 gh auth login、logout 或 switch 变更最多可能需要 60 秒才会反映到这些读取表面。并发读取共享一次原生查找。OAuth 关闭、配置文件替换或轮换以及断开连接都会清除原生令牌缓存。环境令牌、托管配置文件凭据、调用方权限和会话访问仍会实时检查;发布操作会获取自己的实时原生凭据。失败的令牌读取和匿名访问不存在的证明不会被缓存。
使用 设置 → 个人资料 → GitHub 连接 可以同时查看 我的 GitHub 和 系统 GitHub。管理员显式选择 用于系统 来配置此共享执行身份;常规连接流程对于已识别用户默认为 用于我。逐代理覆盖仍是 代理 → 工具 下的高级管理设置。个人连接与 tools.github 是分开的:它支持显式选择的 Gateway 代理发布,并且不会更改代理 shell 凭据、共享默认值或已验证的登录身份。参见 GitHub 连接。
OpenClaw 会显示一个一次性用户代码,旁边有一个 复制代码 按钮;点击该代码会将其完整选中,以便手动复制。打开固定的 https://github.com/login/device 链接,粘贴代码,并批准 repo、workflow、read:org 和 gist。后两者是 GitHub CLI 最小 classic-token 契约的一部分。Gateway 持有设备代码、令牌交换、账户验证、私有托管 gh 配置文件以及轮换刷新令牌。设置和刷新不会在浏览器响应中返回凭据,也不会将它们放入配置、日志、命令参数、记录或模型运行时环境中。OpenClaw 拥有的本地 exec 仅通过其私有进程启动环境接收访问令牌,如下所述。
OAuth 访问令牌大约在八小时后过期。Gateway 会在过期前刷新它们,验证持久的 GitHub 账户 ID,并在同一私有配置文件内原子替换凭据。新的本地 exec 启动会使用刷新后的凭据;已运行的本地 exec 会保留其启动令牌直到退出。在访问令牌过期后,请重启长时间运行的 shell。过期或被拒绝的刷新令牌显示为 需要重新连接。刷新永远不会阻塞 Gateway 启动。
托管配置文件和个人发布使用 github.com 及其公开账户验证端点。企业仓库设置会保留该颁发者绑定。企业仓库读取和共享发布需要绑定到所选 Enterprise 主机的原生凭据;单独的服务发现凭据也会保留其声明的主机绑定。
改用 PAT 将细粒度个人访问令牌设置保留为一种显式替代方案。浏览器会将粘贴的令牌作为一次性的交接凭据放入密钥存储中。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 将继承系统身份。一个 agent 对象是一个完整的托管覆盖。设置会分别显示有效身份和所选配置作用域,因此编辑 系统 绝不会伪装成代理覆盖。如果配置的托管配置文件缺失、无令牌或已损坏,GitHub 状态会报告 configured_unavailable,而不是报告原生账户。Gateway 代理发布会验证所选配置文件自己的凭据,并在每个子操作中固定该凭据;配置文件缺失不能将发布重定向到原生身份验证。普通的代理 shell 执行会继续使用共享选择或逐代理选择,并遵循下文所述执行边界。
托管身份选择 gh CLI/API 账户以及可选的 Git author/committer 元数据。OpenClaw 准备一个不含机密的覆盖层,其中包含私有 GH_CONFIG_DIR、环境令牌清除规则和配置的 author 字段。对于本地执行,它不会安装凭据助手、重写 SSH remote、添加 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 无法隔离操作系统密钥环:如果所选配置文件消失或丢失其令牌,GitHub CLI 可能回退到原生密钥环凭据。当需要启动绑定的托管身份保证时,请使用 gateway_exec。GitHub 状态和 Gateway 拥有的发布保证不扩展到原生 shell 执行。
选择不同的身份或继承目标会为新运行选择另一个配置文件。已接纳的运行保留其先前的配置文件选择,已启动的本地 exec 进程在退出前保留其启动令牌。已退役的配置文件将在下次 Gateway 重启时清理,因此更改此设置并非立即撤销凭据。
托管配置文件提供执行和协调身份;它们不是操作系统用户安全沙箱。在同一操作系统账户下具有不受限制主机执行权限的进程可以访问账户拥有的文件,包括受管的 gh 配置文件。当需要对抗性隔离时,请使用 OpenClaw 沙箱、专用主机或专用操作系统用户。
OpenClaw worker-turn 云工作进程每轮通过其私有启动封装接收有效的共享身份。工作进程将访问令牌写入其一次性状态目录中的每轮私有配置文件,并在下一次绑定之前移除先前的配置文件;上述操作系统用户限制同样适用于工作进程主机。密封的工作进程启动器为每个 exec 子进程提供与本地 exec 相同的启动时凭据绑定。GitHub CLI 必须安装在工作进程主机上;捆绑包包含启动器,而非 gh。检出使用会话拥有的分支和 HTTPS origin 用于 GitHub 仓库;HTTPS Git 身份验证使用 gh auth git-credential,并清除继承的凭据助手。提交和推送直接在工作进程上进行。对账将文件内容返回至 Gateway 工作树,而非提交历史。在每轮开始时,如果本地分支落后,工作进程会将其检出快进到 origin 上的会话分支,引入先前工作进程推送的历史;已分叉的本地分支则保持不变。配对设备自身的 GitHub CLI 登录不用于此绑定。
OpenClaw 沙箱默认排除 Gateway 的托管 GitHub 凭据;按代理沙箱选择加入 可为代理自身的 Docker 或 Podman 沙箱启用这些凭据。普通的节点主机 exec 和 Codex remote-exec 部署仍不会接收这些凭据。github_publish 工具对 remote-exec 会话仍然可用:它记录有界的发布请求,不包含凭据或仓库权限。在精确的工作区结果被对账并接受后,Gateway 以已验证的有效 GitHub 用户身份提交剩余更改,通过一次性 HTTPS 凭据助手推送权威会话分支,并创建或复用草稿拉取请求。
发布可能会等待,直到请求轮次结束且其工作区被接受。其结果会附加到会话记录中;这不会启动另一个代理轮次。当授权任务还包括审查、CI 修复或落地时,代理必须在结束请求轮次前安排单独的延续。草稿 PR 或发布回执不能完成落地请求。
Gateway 托管的代理会检查普通消息和内部延续的发布可用性,包括在请求者让出后子代理完成时。该检查使用当前会话工作区和 GitHub 身份。如果发布不可用,github_identity_status 仍然可用,以解释身份设置或重新连接需求,但须遵守会话的工具策略。独立的本地运行和禁用工具的运行不会暴露这些托管发布工具。
内置、Codex 和 Copilot 工具界面使用相同的主机预备可用性。Harness 选项无法取代主机的决定;工具配置文件和 Gateway 授权仍然适用。
发布使用普通的 Git 属性转换暂存工作区更改。它保留未更改的已提交文件字节,包括现有的 CRLF 行尾,而不是重新规范化无关的已跟踪文件。
仅会话写入访问可以通过配置的共享账户发布来自请求者自身会话的普通源代码更改。在另一个会话中的成员资格不授予该发布权限。对 .github/workflows/*.yml 或 .github/workflows/*.yaml 中 GitHub Actions 定义的更改需要原始请求者的完整操作员写入权限。这包括已提交的编辑、删除和重命名。如果接受的快照更改了这些定义,发布将保留已保存的工作并请维护者发布,或请请求者在再次请求发布之前恢复这些定义。该检查将精确的路径、模式和 blob(包括已删除的定义)与已发布分支或原始拉取请求基础分支进行比较。未更改的已发布定义仍然允许。当已发布定义仍与其明确的共同祖先匹配时,从经过身份验证的目标分支继承的未更改更新也允许。新编写的更改和冲突解决方案仍然需要完整写入权限,即使结果与目标分支匹配。仅仓库检查点无法证明来自与目标分叉的源基础分支的明确继承,也无法从先前复制的工作流内容推断出合并;这些不明确的更新仍需要维护者。
本地会话拥有的工作树可以在 Control UI 中使用相同的 Publish PR 操作。Gateway 从当前会话所有权派生托管工作树、仓库、分支、基础分支和头部分支。它从不接受来自浏览器或模型的这些权限事实。发布重试使用持久请求 ID、精确提交标记、远程分支观察以及按头部分支进行的拉取请求查找,以便 Gateway 重启或响应丢失不会产生重复的提交、推送或拉取请求。
在发布过程中,即使请求连接关闭或发布权限结束,已接受的 PR 响应仍会完成其拥有的回执。本地分支更新成功时,同样会在执行仍持有工作区所有权期间完成其匹配的索引事务。此结算并不授权另一次推送或 PR 创建;未确认的结果保留其现有的恢复或个人确认要求。
在创建发布提交或更改本地分支和索引之前,Gateway 会验证所接受的提交是否与已认证拉取请求的基础分支共享 Git 历史,并且已发布分支要么不存在,要么是所接受本地头的祖先。重新创建本地分支或让其 reflog 过期并不会使共享提交历史失效。查找失败不视为分支不存在。已变基、落后或无关的分支会在新的本地发布更改之前被拒绝并附带恢复指引。已启动的请求拥有的索引事务的恢复仍然首先运行。推送以精确观察到的远程头或分支缺失为条件,因此并发的分支更改会被拒绝。代理永远不会自动重写已发布历史或本地历史。
要刷新现有 PR,请保留其已发布历史,并在已发布头上方应用预期编辑。如果重写历史是有意为之,请改用新的会话分支和替代 PR。不要仅仅为了让变基后的分支可推送而将旧发布历史合并回去。
当远程和本地头匹配、已接受的索引和工作区与对应树匹配,且该头已有发布标记以及所有当前必需的贡献者尾注时,针对未更改内容的单独请求会重用已拥有的开放 PR,而无需新提交。首次发布仍会创建请求拥有的标记,包括针对已提交的工作;缺少贡献者署名也需要新标记。仅仓库的检查点发布已经将未更改的已发布树拒绝为 no_changes,并且只扩展其记录的已发布头。它无法采用该分支上的外部更改;如果记录的头不再匹配,请从新的会话分支发布预期检查点。这些路径保留其现有的重试和溯源契约。对于仅标题/正文的编辑,请直接更新 PR 文本,而不是请求工作区发布;重用 PR 不会更新其文本。
验证用于证明哪个账户响应了 GitHub API 请求。状态会报告凭据类型、访问过期时间、刷新可用性、OAuth 范围以及 Git 作者,同时区分缺失凭据、未验证的传输故障和 GitHub 速率限制,且不返回 gh 诊断信息。在精确的仓库操作成功之前,仓库特定的授权仍然未知;/user 并不能证明写入权限。
移除代理覆盖或选择原生凭据后,配置更改会删除关联的本地刷新记录。已在运行的本地进程可能会保留旧配置文件及其当前访问令牌,直到它们退出、重启或令牌过期,而新的运行会立即使用更新后的身份。此本地更改不会撤销 GitHub 上的授权;如有需要,请从 OAuth 应用程序的 GitHub 设置中单独撤销。
控制台 UI 的 issue 和拉取请求悬停预览使用所选代理的有效托管 GitHub 身份,包括继承的系统身份。不可用的托管身份会产生可操作的错误,而不是切换到其他凭据。在没有托管选择的情况下,预览保留可选的 gateway.controlUi.github.token 服务凭据、共享的 GH_TOKEN/GITHUB_TOKEN 环境变量回退(用于 github.com)以及匿名公共访问。将 gateway.controlUi.github.host 设置为与 gateway.github.host 匹配,以用于 Enterprise 服务访问;省略凭据主机表示 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 时,请在其托管身份上启用此选项,例如在 Gateway 上每个人工角色都需要沙箱化的发布代理:
{
agents: {
entries: {
release: {
sandbox: { mode: "all", scope: "agent" },
tools: {
github: {
profileId: "ghp_0123456789abcdef0123456789abcdef",
allowInSandbox: true,
gitAuthor: { name: "Release Agent", email: "release@example.com" },
},
},
},
},
},
}
使用代理已有的生成 profileId;示例只是一个占位符。此设置仅适用于代理,不接受放在全局 tools.github 下。替换或重新连接代理的托管身份会保留此设置;移除代理覆盖会清除该设置。省略它或将其设置为 false 会保持现有沙箱行为:GH_CONFIG_DIR 不存在,GH_TOKEN 和 GITHUB_TOKEN 会被置空。
启用后,OpenClaw 会通过现有的沙箱绑定机制,仅将该代理选中的托管配置文件以只读方式挂载到 /openclaw/github,并将 GH_CONFIG_DIR 设置为该容器路径。沙箱内的 exec 会收到与主机 exec 相同的已配置 Git 作者和提交者元数据。启动方会在每次 exec 启动前立即验证配置文件,并将其访问令牌作为 GH_TOKEN 私下转发,同时清空 GITHUB_TOKEN。缺失、无令牌或不安全的配置文件会拒绝执行;不会回退到其他身份。Gateway 继续负责凭据刷新,现有进程保留其启动时令牌。
启用或禁用此设置会更改容器的挂载。如果其沙箱已在运行,请先使用 openclaw sandbox recreate --agent <id> 再重试;OpenClaw 会保留正在运行的容器,并拒绝复用过期的挂载。
沙箱镜像必须包含 gh,以便执行 GitHub CLI 命令;并且 GitHub 请求在沙箱现有的网络策略下仍然需要网络访问。OpenClaw 不会安装 Git 凭据助手,也不会更改 Git 网络认证;Git 使用沙箱内配置的远程仓库和凭据助手,就像在主机上一样。配置文件是只读的,因此请通过 Gateway 运行凭据设置或轮换,而不是在沙箱内运行 gh auth login。
生效的 scope: "shared" 会拒绝身份注入,并记录一条指出该智能体的警告,因为该容器可能服务其他智能体。需要角色的沙箱采用其实际生效的按创建者隔离方式,并且即使配置的默认作用域是 "shared",也支持选择加入。当启用该选择加入选项时,其他沙箱后端会拒绝预配;它们不会将受管理的配置文件复制到远程环境。
只读挂载可保护配置文件免遭修改,但沙箱中的代码仍可读取并使用其凭据。每个选择加入的智能体都会在 openclaw security audit 中产生一条 WARN 发现项。仅为那些其沙箱代码被信任可访问该账户 GitHub 访问权限的智能体启用此选项。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw