OpenClaw GitHub (gh) 技能指南

OpenClaw GitHub 技能概述

GitHub (gh) 技能 通过官方 GitHub CLI (gh) 将 OpenClaw 连接到 GitHub 平台。安装后，你的 OpenClaw 智能体可以使用自然语言与仓库、Pull Request、Issue、Actions 工作流等进行交互。

这是 OpenClaw 生态系统中最受欢迎、功能最全面的技能之一。无论是处理 Issue、创建 PR，还是检查 CI 状态，GitHub 技能都能将多步骤的 Git 工作流转化为简单的对话。

典型工作流：

1. 让 OpenClaw 查看你的待处理 PR。
2. 智能体在后台运行 gh pr list。
3. 结果以可读的摘要形式返回 — 无需切换上下文。

安装前的准备工作

在安装 GitHub 技能之前，请确保你已具备：

• 已安装并运行 OpenClaw（v1.0+）
• 已安装 GitHub CLI (gh) — 安装指南
• 拥有 GitHub 账户 并有权访问你要管理的仓库
• 已安装 clawhub CLI 用于技能管理

验证你的环境：

# 检查 OpenClaw 版本
openclaw --version

# 检查 GitHub CLI 版本
gh --version

# 验证 GitHub 认证状态
gh auth status

如何安装 GitHub 技能

使用一条命令安装 GitHub 技能：

npx clawhub@latest install github

验证安装结果：

clawhub list

你应该能在已安装技能列表中看到 github。

GitHub 技能配置指南

GitHub 技能需要个人访问令牌（PAT）或 GitHub CLI 认证。我们推荐使用 gh auth login 进行最简单的配置。

令牌权限范围

如果你更倾向于使用 PAT，请在 github.com/settings/tokens 创建一个具有以下权限的令牌：

| 权限范围 | 是否必需 | 用途 | |---------|---------|------| | repo | 是 | 完整的仓库访问权限 | | read:org | 推荐 | 读取组织成员信息 | | workflow | 可选 | 管理 GitHub Actions 工作流 | | read:project | 可选 | 读取项目看板 | | gist | 可选 | 创建和管理 Gist |

环境配置

# 方式一：使用 GitHub CLI 认证（推荐）
gh auth login

# 方式二：设置个人访问令牌
export GITHUB_TOKEN=ghp_your_token_here

重要提示： 切勿将令牌硬编码在配置文件中。请使用环境变量或密钥管理工具（如 1Password 或 Bitwarden）。

GitHub 技能使用示例

1. 列出和处理待办 Issue

你： "显示主仓库中标记为 bug 的待处理 Issue。"

智能体会运行相当于 gh issue list --label bug --state open 的命令，并返回包含 Issue 编号、标题和指派人的格式化摘要。

你： "将 Issue #42 指派给我，并添加 priority:high 标签。"

智能体会执行 gh issue edit 42 --add-assignee @me --add-label priority:high。

2. 创建 Pull Request

你： "从 feature/auth 分支向 main 创建一个 PR，标题为 'Add OAuth2 login'，并总结变更内容。"

智能体会使用 gh pr create 创建 PR，填写标题，并根据提交差异生成描述。

3. 审查 Pull Request

你： "总结 PR #128 中的变更。"

智能体会使用 gh pr diff 128 获取差异，分析变更内容，并提供简洁的摘要，包括：

• 修改的文件及增删行数
• 关键逻辑变更
• 潜在问题或建议

4. 检查 CI 状态

你： "main 分支上最近一次 Actions 运行的状态如何？"

智能体会检查 gh run list --branch main --limit 1，并报告运行是通过、失败还是仍在进行中 — 同时附上完整日志的链接。

安全与最佳实践

GitHub 技能可以对你的仓库执行写操作。请遵循以下准则以确保安全：

• 使用最小权限。 仅授予你实际需要的令牌权限范围。如果只需读取仓库，可以跳过 workflow 权限。
• 尽可能使用 gh auth login 认证，而非长期有效的 PAT。CLI 会自动处理令牌刷新。
• 合并前先审查。 始终确认 PR 合并和破坏性操作。OpenClaw 默认会提示你确认。
• 定期轮换令牌。 如果使用 PAT，请设置过期时间并至少每 90 天轮换一次。
• 避免授予管理员权限。 admin:org 和 delete_repo 权限范围很少需要。除非必要，否则不要授予。
• 审计活动。 定期检查 GitHub 审计日志，查看通过 API 执行的操作。

常见错误与故障排除

"gh: command not found"

GitHub CLI 未安装或不在你的 PATH 中。

# macOS
brew install gh

# Ubuntu / Debian
sudo apt install gh

# Windows
winget install GitHub.cli

安装后，使用 gh auth login 进行认证。

"HTTP 401: Bad credentials"

你的令牌缺失、已过期或缺少所需权限范围。

1. 运行 gh auth status 检查当前认证状态。
2. 如果已过期，使用 gh auth login 重新认证。
3. 如果使用 PAT，请在 github.com/settings/tokens 验证是否具有 repo 权限。

"Resource not accessible by integration"

你正在尝试访问你的令牌没有权限的仓库或组织。

1. 检查你的令牌是否包含 read:org 权限范围。
2. 确认你的 GitHub 账户有权访问目标仓库。
3. 对于组织仓库，管理员可能需要在 Settings → Third-party access 中批准你的令牌。