openclaw / claude-oauth-refresher

Skill Content

---
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:
```bash
./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)

```bash
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:
```json
{
  "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:**
```bash
./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:**
```bash
# 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:**
```json
{
  "notification_channel": "telegram",
  "notification_target": "123456789"
}
```

### Slack

**Format:** 
- Direct messages: `user:U01234ABCD`
- Channels: `channel:C01234ABCD`

**How to find:**
```bash
# 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:**
```json
{
  "notification_channel": "slack",
  "notification_target": "user:U01234ABCD"
}
```

### Discord

**Format:**
- Direct messages: `user:123456789012345678`
- Channels: `channel:123456789012345678`

**How to find:**
```bash
# 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:**
```json
{
  "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:**
```json
{
  "notification_channel": "whatsapp",
  "notification_target": "+15551234567"
}
```

### iMessage

**Format (preferred):** `chat_id:123`

**How to find:**
```bash
# 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:**
```json
{
  "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:**
```json
{
  "notification_channel": "signal",
  "notification_target": "+15551234567"
}
```

---

## Configuration

**File:** `claude-oauth-refresh-config.json`

```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):**
```json
{
  "notifications": {
    "on_start": false,
    "on_success": false,
    "on_failure": true
  }
}
```

**Verbose (all notifications):**
```json
{
  "notifications": {
    "on_start": true,
    "on_success": true,
    "on_failure": true
  }
}
```

**Silent (no notifications):**
```json
{
  "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

```bash
# 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**
```bash
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:**
```bash
# 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:**
```bash
# 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:
   ```bash
   clawdbot message [channel] send --target "[your_target]" --message "Test"
   ```
3. Check Clawdbot is running: `clawdbot gateway status`
4. Verify notification settings:
   ```bash
   cat ~/clawd/skills/claude-oauth-refresher/claude-oauth-refresh-config.json | jq .notifications
   ```

---

### Problem: Token refresh fails with "invalid_grant"

**Solution:**
```bash
# 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`.

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

```bash
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)'`