Skill GitHub (gh) para OpenClaw — Guia Completo

Visão Geral do Skill GitHub do OpenClaw

O skill GitHub (gh) conecta o OpenClaw à plataforma GitHub através do GitHub CLI (gh) oficial. Uma vez instalado, seu agente OpenClaw pode interagir com repositórios, pull requests, issues, workflows do Actions e mais — usando comandos em linguagem natural.

Este é um dos skills mais populares e versáteis do ecossistema OpenClaw. Seja para triar issues, abrir PRs ou verificar o status do CI, o skill GitHub transforma workflows Git de múltiplas etapas em conversas simples.

Workflow típico:

1. Peça ao OpenClaw para verificar seus PRs pendentes.
2. O agente executa gh pr list em segundo plano.
3. Os resultados são retornados em um resumo legível — sem necessidade de trocar de contexto.

Pré-requisitos para o Skill GitHub

Antes de instalar o skill GitHub, certifique-se de ter:

• OpenClaw instalado e em execução (v1.0+)
• GitHub CLI (gh) instalado — guia de instalação
• Uma conta GitHub com acesso aos repositórios que deseja gerenciar
• clawhub CLI instalado para gerenciamento de skills

Verifique sua configuração:

# Verificar versão do OpenClaw
openclaw --version

# Verificar versão do GitHub CLI
gh --version

# Verificar autenticação do GitHub
gh auth status

Como Instalar o Skill GitHub

Instale o skill GitHub com um único comando:

npx clawhub@latest install github

Para verificar a instalação:

clawhub list

Você deve ver github na lista de skills instalados.

Guia de Configuração do Skill GitHub

O skill GitHub requer um Token de Acesso Pessoal (PAT) ou autenticação do GitHub CLI. Recomendamos usar gh auth login para a configuração mais simples.

Escopos do Token

Se preferir um PAT, crie um em github.com/settings/tokens com estes escopos:

| Escopo | Obrigatório | Finalidade | |--------|------------|------------| | repo | Sim | Acesso completo aos repositórios | | read:org | Recomendado | Ler associação à organização | | workflow | Opcional | Gerenciar workflows do GitHub Actions | | read:project | Opcional | Ler quadros de projeto | | gist | Opcional | Criar e gerenciar gists |

Configuração do Ambiente

# Opção 1: Usar autenticação do GitHub CLI (recomendado)
gh auth login

# Opção 2: Definir um Token de Acesso Pessoal
export GITHUB_TOKEN=ghp_your_token_here

Importante: Nunca insira tokens diretamente em arquivos de configuração. Use variáveis de ambiente ou um gerenciador de segredos (como 1Password ou Bitwarden).

Exemplos de Uso do Skill GitHub

1. Listar e Classificar Issues Abertas

Você: "Mostre as issues abertas no nosso repo principal com a label bug."

O agente executa o equivalente a gh issue list --label bug --state open e retorna um resumo formatado com números de issues, títulos e responsáveis.

Você: "Atribua a issue #42 para mim e adicione a label priority:high."

O agente executa gh issue edit 42 --add-assignee @me --add-label priority:high.

2. Criar um Pull Request

Você: "Crie um PR da branch feature/auth para main com o título 'Add OAuth2 login' e um resumo das alterações."

O agente prepara o PR usando gh pr create, preenche o título e gera uma descrição baseada no diff dos commits.

3. Revisar um Pull Request

Você: "Resuma as alterações no PR #128."

O agente obtém o diff com gh pr diff 128, analisa as alterações e fornece um resumo conciso incluindo:

• Arquivos alterados e linhas adicionadas/removidas
• Principais mudanças de lógica
• Possíveis preocupações ou sugestões

4. Verificar Status do CI

Você: "Qual é o status da última execução do Actions em main?"

O agente verifica gh run list --branch main --limit 1 e informa se a execução passou, falhou ou ainda está em andamento — junto com um link para o log completo.

Segurança e Boas Práticas

O skill GitHub pode realizar operações de escrita nos seus repositórios. Siga estas diretrizes para se manter seguro:

• Use o mínimo de privilégios. Conceda apenas os escopos de token que você realmente precisa. Se apenas lê repos, pule o escopo workflow.
• Autentique-se com gh auth login em vez de PATs de longa duração quando possível. O CLI lida com a renovação do token automaticamente.
• Revise antes de fazer merge. Sempre confirme merges de PRs e ações destrutivas. O OpenClaw pedirá aprovação por padrão.
• Rotacione tokens regularmente. Se usar um PAT, defina uma data de expiração e rotacione-o pelo menos a cada 90 dias.
• Evite conceder escopos de admin. Os escopos admin:org e delete_repo raramente são necessários. Não os conceda a menos que seja imprescindível.
• Audite a atividade. Verifique periodicamente o log de auditoria do GitHub para revisar ações realizadas via API.

Erros Comuns e Solução de Problemas

"gh: command not found"

O GitHub CLI não está instalado ou não está no seu PATH.

# macOS
brew install gh

# Ubuntu / Debian
sudo apt install gh

# Windows
winget install GitHub.cli

Após a instalação, autentique-se com gh auth login.

"HTTP 401: Bad credentials"

Seu token está ausente, expirado ou não possui os escopos necessários.

1. Execute gh auth status para verificar o estado atual de autenticação.
2. Se expirado, reautentique-se com gh auth login.
3. Se usar um PAT, verifique se ele tem o escopo repo em github.com/settings/tokens.

"Resource not accessible by integration"

Você está tentando acessar um repositório ou organização para o qual seu token não tem permissão.

1. Verifique se seu token inclui o escopo read:org.
2. Confirme que sua conta GitHub tem acesso ao repositório alvo.
3. Para repos de organização, um administrador pode precisar aprovar seu token em Settings → Third-party access.