Step-by-Step Fix
1. Identify the Exact Failure Type
In your OpenClaw run log, find the git push command output. The error message determines your fix:
Authentication failedorInvalid username or password→ credentials problem (steps 2-3)Permission denied (publickey)→ SSH key not configured (step 4)Name or service not knownorCould not resolve host→ DNS failure (step 6)remote: Repository not found→ wrong repo URL or token lacks read access403 Forbidden→ token lacks write access (step 3)
2. Configure HTTPS Authentication with a Personal Access Token
This is the simplest approach for most users. In your workflow:
Step 2a: Add the token as an environment variable in OpenClaw:
- Go to your workflow settings > Environment Variables
- Add
GIT_TOKENwith your GitHub/GitLab PAT value
Step 2b: Add a bash setup step to your agent at the start of each run:
# Configure git to use the token
git config --global credential.helper store
echo "https://x-token-auth:${GIT_TOKEN}@github.com" > ~/.git-credentials
# Or use the inline helper approach
git config --global credential.helper \
'!f() { echo username=x-token-auth; echo password=$GIT_TOKEN; }; f'
Step 2c: Verify the push works:
git push origin main
3. Verify the Token Has Write Access
Test your token's permissions directly:
# Test read access
curl -s -H "Authorization: token $GIT_TOKEN" \
https://api.github.com/user | grep login
# Test write access (will return 200 if push access exists)
curl -s -H "Authorization: token $GIT_TOKEN" \
https://api.github.com/repos/YOUR_ORG/YOUR_REPO | grep permissions
If push shows false, regenerate the token with the correct scopes at GitHub > Settings > Developer Settings > Personal Access Tokens.
4. Configure SSH Key Authentication
If you prefer SSH over HTTPS:
Step 4a: Add your private key content as an environment variable in OpenClaw: SSH_PRIVATE_KEY
Step 4b: Write the key to the container's SSH config in a setup bash step:
mkdir -p ~/.ssh
echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
# Trust GitHub's host key
ssh-keyscan github.com >> ~/.ssh/known_hosts 2>/dev/null
# Test the connection
ssh -T git@github.com
Step 4c: Confirm your repo remote is using the SSH URL format (git@github.com:user/repo.git) not the HTTPS format.
5. Configure Git User Identity
OpenClaw containers have no git identity configured by default. Without it, commits may fail:
git config --global user.email "automation@yourcompany.com"
git config --global user.name "OpenClaw Bot"
Add this to your agent's setup step.
6. Handle DNS Failures
If nslookup github.com fails in your agent, this is a platform-level network issue. As a workaround:
- Use the IP address directly in a test — but this is not a sustainable solution for git push
- Contact OpenClaw support with the run ID and the DNS failure output
- If you are on a self-hosted git server, verify that OpenClaw's outbound network can reach your server's hostname
7. Handle Corporate Proxy or Firewall Environments
If your git server is behind a corporate firewall, configure git to use the proxy:
git config --global http.proxy http://your-proxy:8080
git config --global https.proxy http://your-proxy:8080
Add proxy credentials as environment variables rather than hardcoding them in the config.
Why This Happens
OpenClaw runs agents in ephemeral containers that are destroyed after each run. These containers have no persistent state — no stored credentials, no SSH agent, no known_hosts file. Every git operation that requires authentication must be re-configured at the start of each run. This is intentional for security isolation but requires explicit credential setup in automation workflows. DNS failures are rarer and indicate a network configuration issue in OpenClaw's infrastructure or a firewall rule blocking outbound connections to common git hosting domains.
Common Mistakes to Avoid
- Not configuring credentials in the workflow environment: Assuming the agent inherits your local git credentials is the most common mistake. It does not. Every auth-required git operation must have credentials explicitly provided.
- Using a token without write scope: GitHub read tokens will let your agent clone and fetch, but git push will fail with a 403. Double-check the token's scopes match the operations you need.
- Forgetting ssh-keyscan for SSH auth: If you skip the step that adds GitHub's host key to known_hosts, SSH will prompt "Are you sure you want to continue connecting?" which hangs the automation indefinitely.
- Embedding credentials in the repo URL: Never write
https://user:password@github.com/repo.gitin your agent config files — use environment variables for credentials.
FAQ
Q: Does OpenClaw support fine-grained GitHub tokens or only classic PATs?
OpenClaw supports both. Fine-grained personal access tokens (the newer GitHub format) work as long as you grant Contents: Read and Write access for the target repository. Classic PATs work with the repo scope for private repositories or public_repo for public ones. Fine-grained tokens are recommended because they limit access to specific repositories rather than all repos in your account, reducing the blast radius if the token is ever exposed.
Q: My git push fails only on the first run but succeeds on retry. Why?
Intermittent first-run failures are usually a race condition: the git credential setup step is running concurrently with the push step. Ensure your credential configuration bash step is a separate, sequential step that completes before any git push command. If using an OpenClaw workflow YAML, place the credential setup in a dedicated setup or pre-run step that runs before your main agent steps. Adding a short sleep (2-3 seconds) after credential setup as a workaround confirms whether timing is the cause.