{"skill":{"slug":"claude-oauth-renewal","displayName":"Claude OAuth Auto-Renewal","summary":"Automatically detect and renew expired Claude Code OAuth tokens via heartbeat. 3-tier renewal: refresh token → Chrome browser automation → user alert.","description":"---\nname: claude-oauth-renewal\ndescription: \"Automatically detect and renew expired Claude Code OAuth tokens via heartbeat. 3-tier renewal: refresh token → Chrome browser automation → user alert.\"\nhomepage: https://github.com/anthropics/claude-code\nmetadata: { \"openclaw\": { \"emoji\": \"🔑\", \"requires\": { \"bins\": [\"claude\", \"security\", \"python3\"], \"platform\": \"macos\" } } }\n---\n\n# Claude Code OAuth Auto-Renewal\n\nAutomatically detect and renew expired Claude Code OAuth tokens during OpenClaw heartbeat cycles. Prevents agent downtime caused by token expiration.\n\n## When to Use\n\n✅ **USE this skill when:**\n\n- Your OpenClaw agent uses Claude Code as the AI provider\n- You want uninterrupted agent operation without manual token renewal\n- You're running OpenClaw on macOS with Chrome browser\n\n## How It Works\n\n### 3-Tier Renewal Strategy\n\n```\nHeartbeat triggers check-claude-oauth.sh\n  │\n  ├─ Token healthy (>6h remaining) → silent exit ✓\n  │\n  ├─ Tier 1: claude auth status (refresh token)\n  │   ├─ Success → silent exit ✓\n  │   └─ Fail ↓\n  │\n  ├─ Tier 2: Browser automation (osascript + Chrome JXA)\n  │   ├─ Start claude auth login\n  │   ├─ Auto-click \"Authorize\" on claude.ai\n  │   ├─ Extract auth code from callback page\n  │   ├─ Feed code back to CLI via expect\n  │   ├─ Success → silent exit ✓\n  │   └─ Fail ↓\n  │\n  └─ Tier 3: Alert user → agent notifies via configured channel\n```\n\n### Token Storage\n\nClaude Code stores OAuth tokens in **macOS Keychain** under the service name `Claude Code-credentials`. The token JSON includes:\n\n- `accessToken` — API access token (prefix `sk-ant-oat01-`)\n- `refreshToken` — Used for automatic renewal (prefix `sk-ant-ort01-`)\n- `expiresAt` — Unix timestamp in milliseconds\n\n### Prerequisites\n\n1. **macOS** with `security` CLI (Keychain access)\n2. **Claude Code** installed and previously authenticated\n3. **Google Chrome** with `View → Developer → Allow JavaScript from Apple Events` enabled (for Tier 2)\n4. **python3** available in PATH\n5. **expect** available (ships with macOS)\n\n## Setup\n\n### 1. Copy the script\n\n```bash\ncp skills/claude-oauth-renewal/scripts/check-claude-oauth.sh scripts/check-claude-oauth.sh\nchmod +x scripts/check-claude-oauth.sh\n```\n\n### 2. Add to HEARTBEAT.md\n\nAdd as the first step in your heartbeat execution:\n\n```markdown\n## Execution Order\n\n0. Run `bash scripts/check-claude-oauth.sh` — if output exists, relay as highest priority alert\n1. (your other heartbeat checks...)\n```\n\n### 3. Test\n\n```bash\n# Normal check (silent if token healthy)\nbash scripts/check-claude-oauth.sh\n\n# Force trigger by setting high threshold\nWARN_HOURS=24 bash scripts/check-claude-oauth.sh\n```\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `WARN_HOURS` | `6` | Hours before expiry to start renewal attempts |\n\n## Troubleshooting\n\n### \"无法读取 Claude Code token\"\n- Run `claude auth login` manually to establish initial credentials\n- Verify keychain access: `security find-generic-password -s \"Claude Code-credentials\" -a \"$(whoami)\" -g`\n\n### Tier 2 (browser automation) not working\n- Enable Chrome JXA: `View → Developer → Allow JavaScript from Apple Events`\n- Or via CLI: `defaults write com.google.Chrome AppleScriptEnabled -bool true` (restart Chrome)\n- Ensure you're logged into claude.ai in Chrome\n\n### JSON parsing errors\n- The script uses regex extraction (not `json.loads`) to handle truncated keychain output\n- If `security -w` truncates long values, the `-g` flag is used as fallback\n\n## Notes\n\n- Tier 1 (refresh token) handles most cases silently\n- Tier 2 (browser) is only needed when refresh token itself expires (typically weeks)\n- Tier 3 (alert) is the last resort when no automated renewal is possible\n- The script never stores or logs actual token values\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":846,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1772727755049,"updatedAt":1779077710641},"latestVersion":{"version":"1.0.0","createdAt":1772727755049,"changelog":"Initial release: 3-tier automatic Claude Code OAuth token renewal via OpenClaw heartbeat","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"chenhab03","userId":"s17bget6fg5s4a0kpbpe7w0c75884atv","displayName":"chenhab03","image":"https://avatars.githubusercontent.com/u/18511646?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089766868}}