Claude OAuth Auto-Renewal

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

Security Scan

The skill's code and instructions match its stated purpose (auto‑renew Claude Code OAuth on macOS) but contain inconsistencies and behaviors that could inadvertently expose sensitive tokens (temporary logs, PTY capture) and metadata omits some required binaries; review and harden before installing.

Purpose & Capability

Name/description, SKILL.md, and the included shell script align: reading macOS Keychain, calling the 'claude' CLI, and automating Chrome via osascript/expect are expected for an OAuth auto‑renewal tool on macOS. Minor inconsistency: metadata/required binaries list includes 'claude', 'security', and 'python3' but the script also relies on 'osascript', 'expect', and the 'script' utility — these are documented in SKILL.md but not declared in the registry metadata.

Instruction Scope

The SKILL.md directs the agent to read Keychain secrets and run an included script that invokes: security find-generic-password -g (which can print secret values), 'script' to capture a PTY session to /tmp/claude-auth-pty.log, and expect which writes /tmp/claude-auth-expect.log. SKILL.md claims the script never stores or logs token values, but the implementation creates temporary logs that could contain sensitive output (auth codes, CLI prompts, or tokens). The script also automates Chrome (Apple Events) which requires elevated UI automation permissions.

Install Mechanism

Instruction-only skill with no install spec and a single shell script to copy into your workspace — this is lower risk than arbitrary remote downloads. Nothing is fetched from external URLs during install.

Credentials

No environment variables or external API keys are requested (only WARN_HOURS optional). However, the skill requires access to highly sensitive local state: macOS Keychain entries for the user's Claude credentials and the ability to control Chrome via Apple Events. Those privileges are proportional to the stated goal but are high-sensitivity and should be granted carefully.

Persistence & Privilege

The skill is not always-enabled and does not modify other skills or global agent settings; it is intended to be invoked from the heartbeat flow. Autonomous invocation is allowed (platform default) but not an additional special privilege here.

What to consider before installing

This skill is broadly coherent with its purpose (auto-renewing Claude Code OAuth tokens on macOS) but you should not install it blindly. Before using: 1) Inspect and edit the script to avoid logging sensitive data (remove or redact /tmp/claude-auth-pty.log and /tmp/claude-auth-expect.log, or write logs to a secure location), 2) Confirm and add 'expect', 'osascript' (and any other required utilities) to the declared metadata so you know what will be used, 3) Test the flow manually (run claude auth login yourself) and run the script interactively to observe what it prints, 4) Limit who/what can run the heartbeat (do not run on shared machines), 5) Only enable Chrome Apple Events (Allow JavaScript from Apple Events) if you trust the script — this grants UI automation capability, and 6) Consider replacing PTY capture with safer IPC or temporary in-memory handling if possible. If you cannot inspect and modify the script, treat it as high-risk and avoid granting the Keychain/browser automation permissions.

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

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"

• Run claude auth login manually to establish initial credentials
• Verify keychain access: security find-generic-password -s "Claude Code-credentials" -a "$(whoami)" -g

Tier 2 (browser automation) not working

• Enable Chrome JXA: View → Developer → Allow JavaScript from Apple Events
• Or via CLI: defaults write com.google.Chrome AppleScriptEnabled -bool true (restart Chrome)
• Ensure you're logged into claude.ai in Chrome

JSON parsing errors

• The script uses regex extraction (not json.loads) to handle truncated keychain output
• If security -w truncates long values, the -g flag is used as fallback

Notes

• Tier 1 (refresh token) handles most cases silently
• Tier 2 (browser) is only needed when refresh token itself expires (typically weeks)
• Tier 3 (alert) is the last resort when no automated renewal is possible
• The script never stores or logs actual token values