claude-oauth-refresher_skill

This skill keeps Claude access tokens fresh by automatically refreshing OAuth tokens to prevent authentication failures.

Python

2.5k

GitHub Stars

19

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill openclaw/skills --skill claude-oauth-refresher

_meta.json1.2 KB
AUTO-DETECTION-FLOW.md6.9 KB
CHANGES.md10.8 KB
claude-oauth-refresh-config.example.json916 B
COMPLETION-REPORT.md9.3 KB
DELIVERABLES.txt12.4 KB
detect-notification-config.sh3.7 KB
DETECTION-EXAMPLES.md3.0 KB
install.sh10.4 KB
QUICKSTART.md3.3 KB
README.md6.8 KB
refresh-token.sh10.5 KB
SKILL.md15.3 KB
SUMMARY.md8.7 KB
test-detection.sh2.7 KB
uninstall.sh3.8 KB
UPGRADE.md8.1 KB
validate-update.sh6.0 KB
verify-setup.sh8.6 KB

Overview

This skill keeps your Claude CLI OAuth access token fresh 24/7 on macOS by automatically refreshing tokens before they expire. It uses macOS Keychain for secure storage, integrates with Clawdbot for notifications and config changes, and runs as a launchd job so you rarely need to intervene. Installation is interactive and auto-detects notification targets.

How this skill works

The installer sets up a launchd job that runs a refresh script every two hours. Each run reads your claude-oauth-refresh-config.json, checks expiration in ~/.config/claude/auth-profiles.json, and refreshes tokens if they fall inside the configured buffer window. Notifications (start, success, failure) and logs provide visibility and troubleshooting details.

When to use it

You want uninterrupted Claude CLI access on macOS
You run automated workflows that depend on Claude authentication
You need proactive alerts when token refreshes fail
You prefer a hands-off launchd-managed background job
You want config changes to apply immediately without restarting services

Best practices

Keep on_failure notifications enabled so you see problems promptly
Start with all notifications enabled to validate setup, then disable start/success if noisy
Verify Clawdbot and notification target before installing (use test-detection.sh)
Store logs and configs in the default ~/clawd paths so the installer auto-detects them
Use the installer for automatic launchd setup rather than manual crontab editing

Example use cases

Run long-lived Claude-powered automations without manual re-authentication
Keep a development or CI machine authenticated to Claude around the clock
Receive immediate failure alerts to your Telegram/Slack/Discord when refreshes break
Let Clawdbot toggle notification preferences for you without editing files
Test token refresh manually during onboarding with ./refresh-token.sh

FAQ

macOS only. The skill relies on Keychain for secure token storage and launchd for scheduling.

What if notifications stop arriving?

Verify notification_target format, confirm Clawdbot is running, and test with clawdbot message [channel] send. Check the refresh log at ~/clawd/logs/claude-oauth-refresh.log for errors.

How do I recover from an invalid refresh token?

Re-authenticate: claude auth logout && claude auth. Then run ./refresh-token.sh to confirm refresh succeeds.