openclaw_oauth_sync/docs/TROUBLESHOOTING.md

Troubleshooting

"HTTP 401 authentication_error: OAuth token has expired"

The most common error. The OAuth token has a ~8 hour lifetime.

Check:

1. Is the sync service running? systemctl status sync-oauth-token.service
2. Is inotifywait watching? pgrep -af inotifywait
3. Is the source credentials file being updated? stat /root/.openclaw/workspaces/workspace-claude-proxy/config/.claude/.credentials.json
4. Check service logs: journalctl -u sync-oauth-token.service -f

Fix:

• If service stopped: systemctl restart sync-oauth-token.service
• If token expired everywhere: run ./scripts/refresh-claude-token.sh manually
• Nuclear option: claude login inside the Claude CLI container, then restart sync service

---

"docker compose restart doesn't reload .env"

This is a Docker Compose design behavior, not a bug.

docker compose restart only sends SIGTERM and restarts the container process. The container keeps its original environment variables from creation time.

Always use:

cd /root/openclaw
docker compose down openclaw-gateway
docker compose up -d openclaw-gateway

This destroys the container and creates a new one, reading .env fresh.

---

Auth profile has "key" field instead of "access"

OpenClaw's isValidProfile() for type: "oauth" checks for cred.access, not cred.key. If your auth profile looks like:

{
  "anthropic:default": {
    "type": "oauth",
    "provider": "anthropic",
    "key": "sk-ant-oat01-..."   <-- WRONG
  }
}

The profile is silently skipped and falls through to the env var.

Fix: Run ./scripts/fix-auth-profiles.sh

The correct format is:

{
  "anthropic:default": {
    "type": "oauth",
    "provider": "anthropic",
    "access": "sk-ant-oat01-..."  <-- CORRECT
  }
}

---

"404 model_not_found" or double /v1 in URL

This happens when you add anthropic to models.providers in openclaw.json.

Do NOT do this:

"models": {
  "providers": {
    "anthropic": {
      "baseUrl": "https://api.anthropic.com/v1",  <-- WRONG
      ...
    }
  }
}

The built-in Anthropic provider already handles routing. Adding a custom one with baseUrl ending in /v1 causes the SDK to append another /v1, resulting in https://api.anthropic.com/v1/v1/messages -> 404.

Fix: Remove any anthropic entry from models.providers. The built-in provider handles it automatically when you reference anthropic/claude-opus-4-6 as the model.

---

"No available auth profile for anthropic (all in cooldown)"

Auth profiles enter a cooldown period after repeated failures (e.g., expired tokens, wrong model names).

Fix:

./scripts/fix-auth-profiles.sh

This clears cooldownUntil, errorCount, and failureCounts from all agent auth profiles.

---

inotifywait: "No such file or directory"

The watched file or directory doesn't exist yet.

Check:

• Does the Claude CLI container exist? docker ps | grep claude
• Does the credentials path exist? ls -la /root/.openclaw/workspaces/workspace-claude-proxy/config/.claude/
• Has Claude CLI been authenticated? You may need to run claude login inside the container first.

---

Gateway starts but Anthropic model still fails

After recreating the gateway, wait a few seconds for it to fully start. Then verify:

# Check container has the new token
docker exec openclaw-openclaw-gateway-1 printenv ANTHROPIC_OAUTH_TOKEN

# Check oauth.json was picked up
docker exec openclaw-openclaw-gateway-1 cat /home/node/.openclaw/credentials/oauth.json

---

Checking logs

# Real-time sync service logs
journalctl -u sync-oauth-token.service -f

# Last 50 log entries
journalctl -u sync-oauth-token.service -n 50

# Gateway container logs
docker logs openclaw-openclaw-gateway-1 --tail 100

# Force a re-sync
systemctl restart sync-oauth-token.service

---

Complete reset procedure

If everything is broken:

1. Get a fresh token: docker exec -it claude-proxy claude login
2. Fix auth profiles: ./scripts/fix-auth-profiles.sh
3. Restart sync service: systemctl restart sync-oauth-token.service
4. Wait 10 seconds for sync to complete
5. Verify: ./scripts/verify.sh