claude-oauth-renewal

# 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:**

- Your OpenClaw agent uses Claude Code as the AI provider
- You want uninterrupted agent operation without manual token renewal
- You're running OpenClaw on macOS with Chrome browser

## 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:

- `accessToken` — API access token (prefix `sk-ant-oat01-`)
- `refreshToken` — Used for automatic renewal (prefix `sk-ant-ort01-`)
- `expiresAt` — Unix timestamp in milliseconds

### 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

```bash
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:

```markdown
## Execution Order

0. Run `bash scripts/check-claude-oauth.sh` — if output exists, r...

# Claude OAuth Renewal — OpenClaw Skill

Automatically detect and renew expired [Claude Code](https://docs.anthropic.com/en/docs/claude-code) OAuth tokens via [OpenClaw](https://github.com/openclaw/openclaw) heartbeat. Prevents agent downtime caused by token expiration.

## How It Works

```
Heartbeat → check-claude-oauth.sh
  │
  ├─ Token OK (>6h) → silent exit
  │
  ├─ Tier 1: claude auth status (refresh token auto-renew)
  │   └─ Handles most cases silently
  │
  ├─ Tier 2: Chrome browser automation
  │   ├─ Start claude auth login → opens browser
  │   ├─ osascript clicks "Authorize" on claude.ai
  │   ├─ Extracts auth code from callback page
  │   └─ Feeds code back to CLI via expect
  │
  └─ Tier 3: Alert user via agent channel
```

## Requirements

| Dependency | Purpose |
|-----------|---------|
| macOS | Keychain token storage |
| Claude Code | `claude` CLI authenticated |
| python3 | Token expiry parsing |
| Google Chrome | Tier 2 browser automation |
| expect | CLI interaction automation |

**Chrome setup (for Tier 2):** View → Developer → Allow JavaScript from Apple Events

## Install

```bash
# In your OpenClaw workspace
cp -r skills/claude-oauth-renewal/scripts/check-claude-oauth.sh scripts/
chmod +x scripts/check-claude-oauth.sh
```

Add to `HEARTBEAT.md`:

```markdown
0. Run `bash scripts/check-claude-oauth.sh` — if output, relay as P0 alert
```

## Test

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

# Force trigger (set threshold higher than remaining hours)
WARN_HOURS=24 bash scripts/check-claude-oauth.sh
```

## Configuration

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `WARN_HOURS` | `6` | Hours before expiry to start renewal |

## Token Details

Claude Code stores OAuth credentials in macOS Keychain:

- **Service:** `Claude Code-credentials`
- **Key fields:** `accessToken`, `refreshToken`, `expiresAt` (ms timestamp)
- **Read:** `security find-generic-password -s "Claude Code...