Connecting OpenClaw to GitHub: Personal Tokens, SSH Keys, or GitHub Apps?

Your OpenClaw agent lives on a server. It has Claude’s brain. It can write code, run tests, and iterate on complex problems autonomously. But there’s one thing it can’t do out of the box: push that code to your GitHub repository and open a pull request.

To close that loop, your agent needs GitHub credentials. The question is: which authentication method should you use?

After testing every approach with real OpenClaw deployments, here’s what works, what doesn’t, and why.

The Three Options

The short answer: use a fine-grained Personal Access Token (PAT). It handles both git operations and the GitHub API, it’s scoped to exactly the permissions you need, and it expires automatically.

Here’s why, and how to set it up.

Option 1: Personal Access Tokens (Recommended)

A Personal Access Token is a string that acts as your password for both git operations and the GitHub API. When your OpenClaw agent has a PAT, it can:

• Clone private repositories
• Create branches and push commits
• Open pull requests via gh pr create
• Merge pull requests
• Comment on issues

Fine-Grained vs Classic Tokens

GitHub offers two types of PATs:

Fine-Grained Tokens (recommended):

• Scoped to specific repositories (not your entire account)
• Granular permissions (e.g., “Contents: Read and write” without “Admin” access)
• Mandatory expiration (max 1 year)
• Shows which organization or user owns the token
• Available since 2022, now the recommended default

Classic Tokens:

• Broad scopes (repo, workflow, etc.)
• Access to ALL repositories you own
• Optional expiration
• Simpler to set up, but overly permissive

Use fine-grained tokens. There’s no reason to give your AI agent access to every repository on your account.

Step-by-Step: Creating a Fine-Grained PAT

1. Go to github.com/settings/tokens?type=beta
2. Click “Generate new token”
3. Give it a descriptive name: openclaw-agent-myproject
4. Set expiration: 90 days is a good balance (you’ll rotate it quarterly)
5. Under Repository access, select “Only select repositories” and choose the repo(s) your agent works on
6. Under Permissions, grant:

7. Click “Generate token” and copy it immediately (you won’t see it again)

Adding the Token to Your OpenClaw Agent

The simplest way to give your agent the token is to paste it directly into the chat. Your agent is a conversational AI — just tell it what to do:

You: "Here's my GitHub PAT: ghp_xxxxxxxxxxxxxxxxxxxx
      Please save this as an environment variable and configure git to use it."

Agent: "Done. I've saved the token and configured git credentials.
        I can now push code and create pull requests."

Your agent will store the token as an environment variable on its machine and configure git and the gh CLI to use it. The token persists across conversations since your agent runs on a persistent Fly.io machine with its own volume.

Note: Augmi doesn’t yet have a dedicated secrets management UI or config editor in the dashboard. Passing credentials directly to your agent over chat is the current workflow. A secure secrets management interface is on our roadmap (see “What’s Next” below).

What Your Agent Does With the Token

When you pass the token, your agent will configure git to use it. You can also include these instructions in your agent’s SOUL.md so it knows the setup:

## Git Configuration

When the user provides a GitHub token, configure it:

1. Save the token and configure git:
   ```bash
   export GITHUB_TOKEN="<token>"
   git config --global credential.helper store
   git config --global user.name "OpenClaw Agent"
   git config --global user.email "agent@augmi.world"

2. Clone repos using the token:

   git clone https://x-access-token:${GITHUB_TOKEN}@github.com/owner/repo.git
   

3. Authenticate the GitHub CLI:

   echo $GITHUB_TOKEN | gh auth login --with-token
   

### Creating Pull Requests

With `gh` authenticated, your agent can create PRs directly:

```bash
# Create a branch, make changes, commit
git checkout -b feature/add-login-page
# ... agent makes code changes ...
git add -A
git commit -m "Add login page with OAuth support"
git push -u origin feature/add-login-page

# Create the pull request
gh pr create \
  --title "Add login page with OAuth support" \
  --body "## Summary
- Implemented login page with Google and GitHub OAuth
- Added session management with cookies
- Included responsive design for mobile

## Test Plan
- [ ] Test Google OAuth flow
- [ ] Test GitHub OAuth flow
- [ ] Verify mobile responsiveness"

Merging Pull Requests

If you want your agent to merge PRs (after CI passes, for example):

# Merge when checks pass
gh pr merge --auto --squash

# Or merge immediately
gh pr merge --squash

Note: Whether your agent should auto-merge is a separate question. Most teams prefer the agent creates the PR and a human approves. We’ll cover this in the security section below.

Option 2: SSH Keys

SSH keys authenticate git operations (clone, push, pull) but do not work with the GitHub API. This means an SSH key alone cannot create pull requests or merge code through GitHub’s interface.

When SSH Makes Sense

• Your agent only needs to push/pull code (no PRs)
• You’re working with non-GitHub git remotes (GitLab, Bitbucket, self-hosted)
• Your organization requires SSH over HTTPS

When SSH Falls Short

• Cannot create pull requests (that’s a GitHub API operation)
• Cannot merge PRs, comment on issues, or trigger workflows
• Cannot use gh CLI for any API operations
• Deploy keys are limited to a single repository and don’t support GitHub API at all

If You Still Want SSH

You can ask your agent to generate an SSH key pair directly over chat:

You: "Generate an SSH key for GitHub access"

Agent: "Done. Here's the public key:
        ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... openclaw-agent
        Add this to your GitHub account under Settings > SSH Keys."

Your agent runs ssh-keygen -t ed25519 on its machine and gives you the public key to add to GitHub. The private key stays on the agent’s persistent volume.

Alternatively, you can add the public key as a deploy key on a specific repository for tighter scoping.

The catch: You’ll still need a PAT for pull request operations. So most users skip SSH entirely and just use the PAT for everything.

Option 3: GitHub Apps

GitHub Apps are the most sophisticated option. They’re intended for automated systems that act on behalf of an organization rather than a single user.

How It Works

1. You register a GitHub App on your organization
2. You install the app on specific repositories
3. The app generates short-lived installation tokens (expire in 1 hour)
4. Your agent uses these tokens for git and API operations

Advantages

• Tokens are short-lived (1 hour), reducing risk if leaked
• Not tied to a personal account (survives if an employee leaves)
• Fine-grained permissions per repository
• Higher API rate limits (5,000 requests/hour vs 5,000/hour for PATs)
• Audit log shows the app name, not a personal account

Disadvantages

• Significantly more complex to set up
• Requires a server-side component to refresh tokens
• Overkill for individual developers or small teams
• Requires organization admin access to install

When to Use GitHub Apps

If you’re running multiple OpenClaw agents across a team or organization, and you need centralized control over which repos each agent can access, GitHub Apps are worth the setup cost. For everyone else, a fine-grained PAT is simpler and sufficient.

Security Best Practices

Your AI agent has real capabilities. A leaked GitHub token means someone could push malicious code to your repository. Here’s how to stay safe:

1. Scope Tokens Narrowly

Never use a classic token with the repo scope – it grants access to every repository on your account. Always use fine-grained tokens scoped to specific repositories.

2. Set Expiration Dates

Fine-grained tokens require expiration (max 1 year). Set it to 90 days and rotate quarterly. Put a reminder in your calendar.

3. Use Branch Protection

Even if your agent can push to main, it shouldn’t. Set up branch protection rules:

• Require pull request reviews before merging
• Require status checks to pass (CI/CD)
• Restrict who can push to main (exclude the token)

This way, your agent creates PRs but a human approves the merge.

4. Don’t Commit Tokens to Files

Never put tokens in config files, SOUL.md, or any file that might get committed to a repository. When you pass a token to your agent over chat, it should store it as an environment variable — not write it into source files. If you’re unsure, ask your agent: “Where did you save the GitHub token? Make sure it’s not in any committed file.”

5. Monitor Token Usage

GitHub shows when a token was last used. Check periodically at github.com/settings/tokens. If you see unexpected activity, revoke immediately.

6. One Token Per Agent

Don’t share tokens across multiple agents. If one agent is compromised, you only need to revoke one token.

The Recommended Setup

For most OpenClaw users, here’s the complete setup:

GitHub Fine-Grained PAT
  |
  |-- Scoped to: specific repo(s)
  |-- Permissions: Contents (RW), Pull Requests (RW), Metadata (R)
  |-- Expiration: 90 days
  |
  v
You (paste token into agent chat)
  |
  |-- "Here's my GitHub token: ghp_xxxxxxxxxxxx"
  |
  v
OpenClaw Agent (Fly.io Machine)
  |
  |-- Saves token as environment variable
  |-- git clone https://x-access-token:$GITHUB_TOKEN@github.com/...
  |-- gh auth login --with-token <<< $GITHUB_TOKEN
  |-- gh pr create / gh pr merge
  |
  v
GitHub Repository
  |
  |-- Branch protection: require PR review
  |-- CI/CD: required status checks
  |-- Human approves merge

This gives your agent full autonomy to write code, push branches, and open PRs – while keeping a human in the loop for the final merge decision. The token lives on the agent’s persistent volume and survives restarts.

Common Issues and Fixes

“Authentication failed” when pushing

Your token might have expired, or it doesn’t have Contents: Read and write permission. Generate a new fine-grained token with the correct scopes.

“Resource not accessible by personal access token”

You’re trying to access a repository that isn’t included in the token’s repository scope. Edit the token at github.com/settings/tokens and add the repository.

Agent can push but can’t create PRs

You likely set up SSH authentication instead of a PAT. SSH only handles git transport – it can’t interact with the GitHub API. Switch to a PAT.

gh CLI says “not logged in”

Ask your agent: “Run echo $GITHUB_TOKEN | gh auth login --with-token to re-authenticate the GitHub CLI.” If GITHUB_TOKEN isn’t set, you may need to paste your token again — the environment variable might not have persisted after a machine restart.

PRs are attributed to your personal account

When using a PAT, commits and PRs show as coming from the token owner’s account. If you want them attributed to a bot account, create a dedicated GitHub account for your agent and generate the PAT from that account.

What’s Next

We’re working on deeper GitHub integration for OpenClaw agents:

• Secure secrets management UI in the Augmi dashboard — store and update tokens, API keys, and configs without pasting them into chat
• One-click GitHub connection from the Augmi dashboard (OAuth flow)
• Automatic token rotation so you never deal with expiration
• PR review agent that reviews code from other agents before merging
• GitHub webhook integration so agents can respond to issues, PR comments, and CI results automatically

For now, a fine-grained PAT pasted directly to your agent gets you 90% of the way there. Set it up, scope it tightly, and let your agent ship code.

Summary

The answer for most users: Fine-grained Personal Access Token. It’s simple, secure, and handles everything your OpenClaw agent needs to create branches, push code, and open pull requests.

Set it up in 5 minutes. Ship code autonomously. Keep a human in the loop for merges.