GitHub
Status: ✅ Supported on Hermes and ZeroClaw (#419, #422). 📋 Planned for OpenClaw.
GitHub integration allows agents to clone repos, open pull requests, comment on issues, and search code from inside the agent's shell tool. The credential is a Personal Access Token (classic) or a fine-grained token — see Create Fine-Grained Token for One Repo below.
Use Cases
Code Review Assistant
User: Review PR #123 in myorg/myrepo
Agent: Analyzing PR #123...
Summary:
- 5 files changed, 250 lines added
- No obvious security issues
- 2 suggestions:
1. Consider adding error handling on line 45
2. Missing docstring for new function
Issue Triage
User: Summarize open issues from last week
Agent: Found 12 new issues:
Priority breakdown:
- 3 high priority (label: bug)
- 7 medium priority (label: enhancement)
- 2 low priority (label: question)
2 issues need more info (label: needs-repro)
Release Notes
User: Draft release notes for v2.1.0
Agent: Analyzing commits since v2.0.0...
## What's New
### Features
- Add OAuth support (#234)
- New dashboard widgets (#245)
### Bug Fixes
- Fix memory leak in worker (#240)
- Correct timezone handling (#238)
Create Fine-Grained Token for One Repo
- Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
- Direct link: https://github.com/settings/tokens?type=beta
- Click Generate new token
- Configure:
- Token name: Descriptive name (for example,
clawrium-myrepo) - Expiration: Set as needed
- Repository access: Select Only select repositories and pick your single repo
- Token name: Descriptive name (for example,
- Set permissions based on what you need:
| Use Case | Permission | Level |
|---|---|---|
| Read code | Contents | Read |
| Push code | Contents | Read & Write |
| Read issues | Issues | Read |
| Create/comment issues | Issues | Read & Write |
| Read PRs | Pull requests | Read |
| Create/review PRs | Pull requests | Read & Write |
- Click Generate token and copy it immediately.
Use with Clawrium
When configuring your agent:
clawctl agent configure my-agent
# Enter the fine-grained token when prompted for GitHub credentials
The key difference from classic tokens: fine-grained tokens let you scope to specific repos and grant minimal permissions per resource type.
How clawctl Wires GitHub to Each Agent Type
Hermes — env vars in ~/.hermes/.env
Hermes natively reads GITHUB_TOKEN from its environment. clawctl agent integration attach <hermes> <gh-name> followed by clawctl agent sync <hermes> renders the following into ~/.hermes/.env (mode 0600):
GITHUB_TOKEN_WORK_GH='ghp_...'
GITHUB_TOKEN='ghp_...' # tracks the alphabetically-last github integration
clawctl then runs gh auth login --with-token as the agent user (soft dep — skipped if gh is not on the host). See hermes/playbooks/configure.yaml lines 118–145.
ZeroClaw — two layers, both required
ZeroClaw's shell tool auto-strips any env var matching _TOKEN / _SECRET / _PASSWORD / API_KEY patterns unless explicitly listed in [autonomy] shell_env_passthrough. Source: zeroclaw v0.7.5 docs/book/src/security/sandboxing.md and security/autonomy.md. So GitHub credentials need to land in two places:
| Layer | Where | What it enables |
|---|---|---|
1. systemd Environment= drop-in | /etc/systemd/system/zeroclaw-<name>.service.d/10-zeroclaw-env.conf | The daemon process and all child processes (including the shell tool) inherit GITHUB_TOKEN from systemd. |
2. [autonomy] shell_env_passthrough | ~/.zeroclaw/config.toml | The agent's sandboxed shell tool sees the token. Without this, layer 1 alone is invisible to gh/git push inside chat. |
Both layers are populated automatically by clawctl agent sync <zeroclaw> after clawctl agent integration attach. The drop-in template is src/clawrium/platform/registry/zeroclaw/templates/zeroclaw-env.conf.j2; the autonomy block lives in config.toml.j2. Re-running clawctl agent sync re-renders both atomically and triggers a single service restart (daemon_reload + restart, handled by the configure playbook's restart handler).
Like hermes, a gh auth login --with-token is run as the agent user when gh is present on the host — convenience only; the env-var path works without it.
# Rendered in ~/.zeroclaw/config.toml when github integrations are assigned:
[autonomy]
level = "supervised"
approval_timeout_secs = 300
workspace_only = true
allowed_commands = ["git", "cargo", "grep", "find", "ls", "cat"]
forbidden_commands = ["shutdown", "reboot", "mkfs"]
forbidden_paths = ["/etc", "/sys", "/boot", "~/.ssh", "~/.aws"]
shell_env_passthrough = ["PATH", "HOME", "USER", "LANG", "GITHUB_TOKEN_WORK_GH", "GITHUB_TOKEN"]
# Rendered in /etc/systemd/system/zeroclaw-<name>.service.d/10-zeroclaw-env.conf:
[Service]
Environment=GITHUB_TOKEN_WORK_GH="ghp_..."
Environment=GITHUB_TOKEN="ghp_..."
Verifying the wiring (ZeroClaw)
# On the agent host:
systemctl show -p Environment zeroclaw-<name> # should list GITHUB_TOKEN
grep -E '^shell_env_passthrough' ~/.zeroclaw/config.toml
# From clawctl:
clawctl agent chat <name>
> Run: echo $GITHUB_TOKEN # should print the token
> Run: gh auth status # should print "Logged in to github.com" if gh is installed
Multi-Account Support
Both hermes and zeroclaw support multiple github integrations on a single agent:
clawctl integration registry create work-gh --type github
clawctl integration registry create personal-gh --type github
clawctl agent integration attach my-agent work-gh
clawctl agent integration attach my-agent personal-gh
clawctl agent sync my-agent
The agent then has GITHUB_TOKEN_WORK_GH and GITHUB_TOKEN_PERSONAL_GH available, plus a bare GITHUB_TOKEN set to the alphabetically-last integration (deterministic — uses Jinja's dictsort).
OpenClaw (Not Yet Supported)
OpenClaw does not yet consume GitHub credentials. Use a hermes or zeroclaw agent for GitHub workflows, or follow the workaround below for OpenClaw-only fleets.
Workaround for OpenClaw
- CLI Tools: Manually
gh auth loginon the OpenClaw host outside of clawctl. - API via curl: Make direct API calls inside chat using a hard-coded token (not recommended for production).