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 中核准你的權杖。