claude-oauth-refresher – OpenClaw Skill

---

name: claude-oauth-refresher description: Keep your Claude access token fresh 24/7. Automatically refreshes OAuth tokens before expiry so you never see authentication failures.

claude-oauth-refresher

Automatic OAuth token refresh for Claude Code CLI on macOS

Keep your Claude account logged in 24/7 by automatically refreshing OAuth tokens before they expire.

---

⚠️ Requirements

This skill is macOS-only and requires:

1. macOS (uses Keychain for secure credential storage)
2. Claude Code CLI already installed (claude command available)
3. Already logged into your Claude account (run claude then login - stores tokens in Keychain)
4. Clawdbot installed and running

Not sure if you're set up? Run the verification script:

./verify-setup.sh

---

What It Does

• Monitors your Claude CLI token expiration
• Refreshes tokens automatically before they expire (default: 30 min buffer)
• Notifies you with three notification types:
  • 🔄 Start: "Refreshing Claude token..."
  • ✅ Success: "Claude token refreshed!"
  • ❌ Failure: Detailed error with troubleshooting steps
• Logs all refresh attempts for debugging

---

Installation

Quick Setup (Recommended)

cd ~/clawd/skills/claude-oauth-refresher
./install.sh

This installer runs ONCE and sets up automatic token refresh that runs every 2 hours.

The installer will:

1. Verify your system meets requirements
2. Interactively configure notification preferences
3. Auto-detect your notification target (Telegram, Slack, etc.)
4. Set up launchd for automatic refresh
5. Test the refresh immediately

After installation:

• Config changes apply automatically (refresh script reads config each run)
• Edit claude-oauth-refresh-config.json to change settings
• Ask Clawdbot to modify settings for you
• Only re-run installer if you need to reinstall or fix the job

Interactive Notification Setup

During installation, you'll be prompted:

Configure Notifications:
💡 Recommendation: Keep all enabled for the first run to verify it works.
   You can disable them later by:
   1. Editing ~/clawd/claude-oauth-refresh-config.json
   2. Asking Clawdbot: "disable Claude refresh notifications"

Enable "🔄 Refreshing token..." notification? [Y/n]: 
Enable "✅ Token refreshed!" notification? [Y/n]: 
Enable "❌ Refresh failed" notification? [Y/n]: 

Recommendation: Keep all enabled initially to verify everything works, then disable start/success notifications once you're confident.

---

Managing Notifications with Clawdbot

You can ask Clawdbot to change notification settings for you! No need to edit JSON manually.

Examples

Disable specific notification types:

"disable Claude refresh start notifications"
"disable Claude refresh success notifications"
"turn off Claude token refresh start messages"

Enable notification types:

"enable Claude refresh start notifications"
"enable all Claude refresh notifications"
"turn on Claude token refresh success messages"

Check current settings:

"show Claude refresh notification settings"
"what are my Claude token refresh notification settings?"

Disable all notifications:

"disable all Claude refresh notifications"
"turn off all Claude token notifications"

Reset to defaults:

"reset Claude refresh notifications to defaults"

How It Works

Clawdbot will:

1. Read your ~/clawd/claude-oauth-refresh-config.json
2. Update the appropriate notification flags
3. Save the file
4. Confirm the changes

Changes apply immediately on the next refresh (no need to restart anything).

---

Auto-Detection (Smart Defaults)

The install script automatically detects your notification settings!

It reads ~/.clawdbot/clawdbot.json to find:

• Which messaging channels you have enabled
• Your chat ID, phone number, or user ID
• Automatically populates claude-oauth-refresh-config.json with these values

Example: If you have Telegram enabled with chat ID 123456789, the installer creates:

{
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

To override: Simply edit claude-oauth-refresh-config.json after installation to use a different channel or target.

If auto-detection fails: The installer will prompt you to configure manually (see "Finding Your Target ID" below).

Test detection before installing:

./test-detection.sh
# Shows what would be auto-detected without modifying anything

---

Finding Your Target ID

To receive notifications, you need to configure your notification_target in claude-oauth-refresh-config.json. Here's how to find it for each channel:

Telegram

Format: Numeric chat ID (e.g., 123456789)

How to find:

# Option 1: Use Clawdbot CLI
clawdbot message telegram account list

# Option 2: Message @userinfobot on Telegram
# Send any message, it will reply with your ID

# Option 3: Check recent messages
clawdbot message telegram message search --limit 1 --from-me true

Example config:

{
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

Slack

Format:

• Direct messages: user:U01234ABCD
• Channels: channel:C01234ABCD

How to find:

# List channels
clawdbot message slack channel list

# Find user ID
clawdbot message slack user list | grep "your.email@company.com"

# Or click on your profile in Slack → More → Copy member ID

Example config:

{
  "notification_channel": "slack",
  "notification_target": "user:U01234ABCD"
}

Discord

Format:

• Direct messages: user:123456789012345678
• Channels: channel:123456789012345678

How to find:

# Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
# Then right-click your username → Copy ID

# Or list channels
clawdbot message discord channel list

Example config:

{
  "notification_channel": "discord",
  "notification_target": "user:123456789012345678"
}

WhatsApp

Format: E.164 phone number (e.g., +15551234567)

How to find:

• Use your full phone number with country code
• Format: +[country code][number] (no spaces, dashes, or parentheses)

Examples:

• US: +15551234567
• UK: +447911123456
• Australia: +61412345678

Example config:

{
  "notification_channel": "whatsapp",
  "notification_target": "+15551234567"
}

iMessage

Format (preferred): chat_id:123

How to find:

# List recent chats to find your chat_id
clawdbot message imessage thread list --limit 10

# Find the chat with yourself or your preferred device

Alternative formats:

• Phone: +15551234567 (E.164 format)
• Email: your.email@icloud.com

Example config:

{
  "notification_channel": "imessage",
  "notification_target": "chat_id:123"
}

Signal

Format: E.164 phone number (e.g., +15551234567)

How to find:

• Use your Signal-registered phone number
• Format: +[country code][number] (no spaces, dashes, or parentheses)

Example config:

{
  "notification_channel": "signal",
  "notification_target": "+15551234567"
}

---

Configuration

File: claude-oauth-refresh-config.json

{
  "refresh_buffer_minutes": 30,
  "log_file": "~/clawd/logs/claude-oauth-refresh.log",
  "notifications": {
    "on_start": true,
    "on_success": true,
    "on_failure": true
  },
  "notification_channel": "telegram",
  "notification_target": "YOUR_CHAT_ID"
}

Options

Option	Type	Default	Description
refresh_buffer_minutes	number	30	Refresh tokens this many minutes before expiry
log_file	string	~/clawd/logs/claude-oauth-refresh.log	Where to write logs
notifications.on_start	boolean	true	Send "🔄 Refreshing token..." notification
notifications.on_success	boolean	true	Send "✅ Token refreshed!" notification
notifications.on_failure	boolean	true	Send "❌ Refresh failed" notification with details
notification_channel	string	telegram	Channel to use (see above for options)
notification_target	string	YOUR_CHAT_ID	Target ID (see "Finding Your Target ID")

Notification Types Explained

🔄 Start (on_start)

• Sent when refresh process begins
• Useful for debugging or knowing when refresh runs
• Recommendation: Disable once you verify it works (can be noisy)

✅ Success (on_success)

• Sent when token successfully refreshed
• Includes validity duration (e.g., "valid for 24h")
• Recommendation: Disable once you trust the setup (can be noisy)

❌ Failure (on_failure)

• Sent when refresh fails with detailed error info
• Includes troubleshooting steps based on error type
• Recommendation: Keep enabled! You want to know about failures.

Example Configurations

Minimal (failures only):

{
  "notifications": {
    "on_start": false,
    "on_success": false,
    "on_failure": true
  }
}

Verbose (all notifications):

{
  "notifications": {
    "on_start": true,
    "on_success": true,
    "on_failure": true
  }
}

Silent (no notifications):

{
  "notifications": {
    "on_start": false,
    "on_success": false,
    "on_failure": false
  }
}

---

Detailed Failure Messages

When a refresh fails, you'll receive a detailed notification with:

1. Error message - What went wrong
2. Details - Additional context (HTTP codes, error responses, etc.)
3. Troubleshooting - Specific steps based on the error type
4. Help - Where to find logs and get support

Example Failure Notification

❌ Claude token refresh failed

Error: Network timeout connecting to auth.anthropic.com
Details: Connection timed out after 30s

Troubleshooting:
- Check your internet connection
- Verify you can reach auth.anthropic.com
- Try running manually: ~/clawd/skills/claude-oauth-refresher/refresh-token.sh

Need help? Message Clawdbot or check logs:
~/clawd/logs/claude-oauth-refresh.log

Common Errors and Solutions

Network/Timeout Errors

Troubleshooting:
- Check your internet connection
- Verify you can reach auth.anthropic.com
- Try running manually: ./refresh-token.sh

Invalid Refresh Token

Troubleshooting:
- Your refresh token may have expired
- Re-authenticate: claude auth logout && claude auth
- Verify Keychain access: security find-generic-password -s 'claude-cli-auth' -a 'default'

Keychain Access Denied

Troubleshooting:
- Check Keychain permissions
- Re-run authentication: claude auth
- Verify setup: ./verify-setup.sh

Missing Auth Profile

Troubleshooting:
- Run: claude auth
- Verify file exists: ~/.config/claude/auth-profiles.json
- Check file permissions: chmod 600 ~/.config/claude/auth-profiles.json

---

Usage

Check Status

# View recent logs
tail -f ~/clawd/logs/claude-oauth-refresh.log

# Check launchd status
launchctl list | grep claude-oauth-refresher

# Manual refresh (for testing)
cd ~/clawd/skills/claude-oauth-refresher
./refresh-token.sh

Modify Settings

Option 1: Ask Clawdbot (easiest)

"disable Claude refresh start notifications"
"show Claude refresh notification settings"

Option 2: Edit config file

nano ~/clawd/skills/claude-oauth-refresher/claude-oauth-refresh-config.json

Changes apply automatically on next refresh (every 2 hours, or when you run manually).

No need to restart anything! The refresh script reads the config file each time it runs.

---

Troubleshooting

Problem: verify-setup.sh says Claude CLI not found

Solution:

# Install Claude CLI
brew install claude

# Or download from https://github.com/anthropics/claude-cli

---

Problem: verify-setup.sh says no refresh token found

Solution:

# Authenticate with Claude
claude auth

# Follow the prompts to log in

---

Problem: Notifications not arriving

Solution:

1. Check your notification_target format matches the examples above
2. Test manually:

   clawdbot message [channel] send --target "[your_target]" --message "Test"
   

3. Check Clawdbot is running: clawdbot gateway status
4. Verify notification settings:

   cat ~/clawd/skills/claude-oauth-refresher/claude-oauth-refresh-config.json | jq .notifications
   

---

Problem: Token refresh fails with "invalid_grant"

Solution:

# Re-authenticate from scratch
claude auth logout
claude auth

# Test refresh again
cd ~/clawd/skills/claude-oauth-refresher
./refresh-token.sh

---

Problem: "Config file not found" after upgrade

Solution: The config file was renamed from config.json to claude-oauth-refresh-config.json.

# If you have an old config.json, run the installer to migrate:
cd ~/clawd/skills/claude-oauth-refresher
./install.sh
# Choose to keep existing config when prompted

---

Problem: Want to reinstall or fix the job

Solution:

# Re-run the installer (safe to run multiple times)
cd ~/clawd/skills/claude-oauth-refresher
./install.sh

The installer will:

• Detect existing config and ask if you want to keep it
• Update the launchd job
• Test the refresh

---

Uninstall

cd ~/clawd/skills/claude-oauth-refresher
./uninstall.sh

This will:

• Stop and unload the launchd service
• Remove the plist file
• Optionally delete logs and config

---

How It Works

1. Installer (install.sh) - Run ONCE to set up:

   • Auto-detects notification target
   • Interactively configures notification types
   • Creates launchd job
   • Tests refresh immediately

2. Launchd - Runs refresh-token.sh every 2 hours automatically

3. Refresh Script (refresh-token.sh) - Each run:

   • Reads config file (changes apply automatically!)
   • Checks token expiration from ~/.config/claude/auth-profiles.json
   • If token expires within buffer window (default 30 min):
     • Sends start notification (if enabled)
     • Retrieves refresh token from Keychain
     • Calls OAuth endpoint to get new tokens
     • Updates auth profile and Keychain
     • Sends success notification (if enabled)
   • If refresh fails:
     • Sends detailed failure notification with troubleshooting
   • All activity logged to ~/clawd/logs/claude-oauth-refresh.log

4. Config Changes - Applied automatically:

   • Edit claude-oauth-refresh-config.json anytime
   • Ask Clawdbot to edit for you
   • Changes take effect on next refresh
   • No restart needed!

---

Security

• Tokens are never written to logs or config files
• Refresh tokens stored securely in macOS Keychain
• Access tokens cached in ~/.config/claude/auth-profiles.json (permissions: 600)
• All HTTP requests use Claude's official OAuth endpoints
• Config file is world-readable (contains no secrets)

---

Support

Logs: ~/clawd/logs/claude-oauth-refresh.log

Issues:

1. Run ./verify-setup.sh to diagnose
2. Check logs for detailed error messages
3. Test manual refresh: ./refresh-token.sh
4. Check notification settings: cat claude-oauth-refresh-config.json | jq .notifications

Need help? Open an issue with:

• Output of ./verify-setup.sh
• Last 20 lines of logs: tail -20 ~/clawd/logs/claude-oauth-refresh.log
• macOS version: sw_vers
• Config (redacted): cat claude-oauth-refresh-config.json | jq 'del(.notification_target)'

Claude OAuth Token Refresher

Automatically refreshes your Claude tokens before they expire. No more authentication failures.

The problem: Claude tokens expire every 8 hours, interrupting your workflow with authentication errors.

This tool: Monitors and refreshes your tokens automatically so you never see auth failures again.

---

⚡ What It Does

Your tokens stay fresh automatically.

The tool:

• Checks your Claude token every few hours
• Refreshes it 30 minutes before expiry
• Updates both Keychain and Clawdbot config
• Runs silently in the background

Zero manual intervention needed.

---

🛠️ Getting Ready

Before installing this skill:

You'll need:

• macOS 10.15 (Catalina) or later with Keychain access
• Active Claude subscription (Pro, Max, Team, or Enterprise)

Install through Homebrew:

# Install jq (for JSON parsing)
brew install jq

Set up Claude Code CLI:

Step 1: Install Claude Code CLI

curl -fsSL https://claude.ai/install.sh | bash

Step 2: Log Into Your Claude Account

Start Claude Code CLI:

claude

Then run the login command:

auth

Follow the login prompts. This creates the Keychain item that stores your tokens.

How it works:

• Claude CLI creates a Keychain entry with service name "Claude Code-credentials"
• The account name varies (could be "claude", "Claude Code", your username, etc.) - this doesn't matter
• The skill automatically iterates through every "Claude Code-credentials" entry in your Keychain
• Uses the first one that has complete OAuth tokens (refreshToken + expiresAt)

No manual configuration needed - it handles duplicates and incomplete entries automatically.

---

🚀 Installation

After completing prerequisites above:

clawdhub install claude-oauth-refresher

First-Time Setup

Run the refresher to verify setup:

cd ~/clawd/skills/claude-oauth-refresher
./refresh-token.sh

Expected output:

✅ Token still valid (475 minutes remaining)
Use --force to refresh anyway

This is good! It means:

• ✅ Found your tokens in Keychain
• ✅ Your Claude account is connected
• ✅ Automatic refresh is set up

The script will refresh your token automatically 30 minutes before it expires. You don't need to run it again manually.

---

Already Have Clawdbot Running?

If you already have Clawdbot running with a model, you have two options:

Option 1: Ask Clawdbot to Run It

Just send a message to Clawdbot:

Run the Claude token refresher for me

or

cd ~/clawd/skills/claude-oauth-refresher && ./refresh-token.sh

Clawdbot will execute it and show you the output.

Option 2: Run From Terminal

cd ~/clawd/skills/claude-oauth-refresher
./refresh-token.sh

Same output as first-time setup above. Once verified, it runs automatically.

---

What Happens

The installation:

• Finds your tokens in Keychain automatically
• Validates token structure
• Sets up automatic refresh schedule
• Logs all operations to ~/clawd/logs/

---

🔧 How It Works

Result: Your tokens stay fresh without you thinking about it.

The process:

1. Reads your current token from macOS Keychain
2. Checks expiry time (refreshes 30 min before expiry)
3. Calls Anthropic OAuth API with your refresh token
4. Updates both Keychain and Clawdbot config automatically

Smart fallback: If your account name isn't "claude", it tries common alternatives: "Claude Code", "default", "oauth", "anthropic"

Example (force refresh):

./refresh-token.sh --force

Output:

[17:48:16] ✓ Received new tokens
[17:48:16] New expiry: 2026-01-24 01:48:16 (8 hours)
[17:48:16] ✓ Auth file updated
[17:48:16] ✓ Keychain updated
✅ Token refreshed successfully!

---

---

📚 Additional Information

Everything below is optional. The skill works out-of-the-box for most users.

This section contains:

• Advanced configuration options
• Implementation details for developers
• Troubleshooting for edge cases

You don't need to read this for initial installation.

---

<details> <summary><b>Configuration Options</b> (optional customization)</summary> <br>

Create claude-oauth-refresh-config.json if you need to customize:

{
  "refresh_buffer_minutes": 30,
  "keychain_service": "Claude Code-credentials",
  "keychain_account": "claude",
  "auth_file": "~/.clawdbot/agents/main/agent/auth-profiles.json"
}

Most users don't need this - the defaults work fine.

</details> <details> <summary><b>Setting Up Another Device</b></summary> <br>

The script has automatic fallback.

Usually you just:

1. Copy the skill folder
2. Run ./refresh-token.sh
3. It finds your tokens automatically

If your setup is unusual:

Check which keychain account has your tokens:

security find-generic-password -l "Claude Code-credentials"

Look for the entry with "acct"<blob>="your-account-name"

Then create a config file with your account name.

</details> <details> <summary><b>How Detection Works</b> (implementation details)</summary> <br>

The script:

1. Tries your configured account name first
2. If that fails or has incomplete data, tries common names
3. Validates each entry has refreshToken and expiresAt
4. Uses the first complete entry found

Data structure expected:

{
  "claudeAiOauth": {
    "accessToken": "sk-ant-oat01-...",
    "refreshToken": "sk-ant-ort01-...",
    "expiresAt": 1769190496000,
    "scopes": [...],
    "subscriptionType": "max",
    "rateLimitTier": "default_claude_max_20x"
  }
}

</details> <details> <summary><b>Troubleshooting</b></summary> <br>

"No refreshToken in keychain"

Your keychain account name is different.

The script should auto-discover it.

If not:

security find-generic-password -l "Claude Code-credentials"

Check which account has the tokens.

"Failed to retrieve from Keychain"

Possible causes:

• Keychain is locked
• Entry doesn't exist

Run:

security find-generic-password -s "Claude Code-credentials" -l

Token refresh fails

Check:

• Internet connection
• Refresh token hasn't been revoked
• Re-authenticate with Claude if needed

</details> <details> <summary><b>For Developers</b> (architecture)</summary> <br>

Data Flow

Keychain (claudeAiOauth JSON)
    ↓ read refreshToken, expiresAt
OAuth API (POST with refresh_token)
    ↓ returns new accessToken, refreshToken, expires_in
Update Keychain (complete JSON)
    ↓
Update auth-profiles.json (just accessToken)

Automatic Scheduling

After refresh, creates a Clawdbot cron job:

Next refresh = (new_expiry - buffer_minutes)

Portability Features

• Tries multiple common account names
• Validates data structure before using
• Helpful errors with diagnostic commands
• Works without config file using sensible defaults

</details>

---

License

MIT