Claude Code OAuth Auto-Renewal

---

name: claude-oauth-renewal

description: "Automatically detect and renew expired Claude Code OAuth tokens via heartbeat. 3-tier renewal: refresh token → Chrome browser automation → user alert."

homepage: https://github.com/anthropics/claude-code

metadata: { "openclaw": { "emoji": "🔑", "requires": { "bins": ["claude", "security", "python3"], "platform": "macos" } } }

---

# Claude Code OAuth Auto-Renewal

Automatically detect and renew expired Claude Code OAuth tokens during OpenClaw heartbeat cycles. Prevents agent downtime caused by token expiration.

When to Use

✅ **USE this skill when:**

How It Works

3-Tier Renewal Strategy

Heartbeat triggers check-claude-oauth.sh
  │
  ├─ Token healthy (>6h remaining) → silent exit ✓
  │
  ├─ Tier 1: claude auth status (refresh token)
  │   ├─ Success → silent exit ✓
  │   └─ Fail ↓
  │
  ├─ Tier 2: Browser automation (osascript + Chrome JXA)
  │   ├─ Start claude auth login
  │   ├─ Auto-click "Authorize" on claude.ai
  │   ├─ Extract auth code from callback page
  │   ├─ Feed code back to CLI via expect
  │   ├─ Success → silent exit ✓
  │   └─ Fail ↓
  │
  └─ Tier 3: Alert user → agent notifies via configured channel

Token Storage

Claude Code stores OAuth tokens in **macOS Keychain** under the service name `Claude Code-credentials`. The token JSON includes:

Prerequisites

1. **macOS** with `security` CLI (Keychain access)

2. **Claude Code** installed and previously authenticated

3. **Google Chrome** with `View → Developer → Allow JavaScript from Apple Events` enabled (for Tier 2)

4. **python3** available in PATH

5. **expect** available (ships with macOS)

Setup

1. Copy the script

cp skills/claude-oauth-renewal/scripts/check-claude-oauth.sh scripts/check-claude-oauth.sh
chmod +x scripts/check-claude-oauth.sh

2. Add to HEARTBEAT.md

Add as the first step in your heartbeat execution:

## Execution Order

0. Run `bash scripts/check-claude-oauth.sh` — if output exists, relay as highest priority alert
1. (your other heartbeat checks...)

3. Test

# Normal check (silent if token healthy)
bash scripts/check-claude-oauth.sh

# Force trigger by setting high threshold
WARN_HOURS=24 bash scripts/check-claude-oauth.sh

Configuration

| Environment Variable | Default | Description |

|---------------------|---------|-------------|

| `WARN_HOURS` | `6` | Hours before expiry to start renewal attempts |

Troubleshooting

"无法读取 Claude Code token"

Tier 2 (browser automation) not working

JSON parsing errors

Notes