An automated background utility for macOS that ensures your Claude Code CLI access tokens never expire by monitoring and refreshing them via Keychain.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install claude-oauth-refresher
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install claude-oauth-refresher using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Claude OAuth Refresher?
Claude OAuth Refresher is a robust automation tool specifically engineered for developers using the Claude Code CLI on macOS. By leveraging the native macOS Keychain for secure credential storage, this skill eliminates the manual overhead of re-authenticating your AI sessions. As a core part of the Openclaw Skills ecosystem, it provides a persistent connection to Anthropic's models, ensuring that background agents and long-running terminal sessions remain authenticated without interruption.
The skill operates as a lightweight background service that proactively checks your token validity. It integrates with your existing notification stack—including Telegram, Slack, and Discord—to keep you informed of your authentication status. Whether you are running complex autonomous workflows or daily coding tasks, this utility provides the reliability required for a seamless developer experience within Openclaw Skills.
Claude OAuth Refresher Use Cases
- Maintain a persistent 24/7 login state for Claude Code CLI without manual intervention.
- Prevent workflow interruptions caused by expired OAuth tokens during long coding sessions.
- Receive instant notifications across multiple platforms like Slack or WhatsApp when tokens are renewed.
- Securely manage AI credentials using macOS Keychain integration rather than plaintext files.
- Monitor authentication health for headless or automated agent environments running Openclaw Skills.
How Claude OAuth Refresher Works
- The installation script configures a launchd service to run the refresh logic every two hours.
- Upon execution, the script analyzes the local Claude auth-profiles to determine the current token's expiration timestamp.
- If the token is set to expire within the defined buffer window, the skill initiates a refresh sequence.
- It securely fetches the required refresh token from the macOS Keychain.
- A request is sent to the official Claude OAuth endpoints to generate a new pair of access and refresh tokens.
- The local environment is updated with the new credentials, and a success or failure notification is sent via the chosen Openclaw Skills communication channel.
Claude OAuth Refresher Setup
To install the Claude OAuth Refresher, ensure you have already logged into the Claude CLI on your macOS machine. Follow these steps:
cd ~/clawd/skills/claude-oauth-refresher
./install.sh
The installer will interactively guide you through notification setup and verify your system dependencies. To confirm your configuration is correct, you can run the verification utility:
./verify-setup.sh
Claude OAuth Refresher Data Schema & Taxonomy
The skill organizes its operation through a central configuration file and standard macOS paths:
| Component | Path / Detail | Purpose |
|---|---|---|
| Configuration | claude-oauth-refresh-config.json |
Defines refresh buffers and notification targets. |
| Logs | ~/clawd/logs/claude-oauth-refresh.log |
Stores a detailed history of refresh attempts and errors. |
| Auth Profiles | ~/.config/claude/auth-profiles.json |
Managed by the skill to store active access tokens. |
| Secure Storage | macOS Keychain | Used to store the persistent refresh token securely. |
Claude OAuth Refresher Advanced Features
- Natural Language Management: Use Clawdbot to enable, disable, or check notification settings using simple voice or text commands.
- Smart Auto-Detection: The installer automatically pulls chat IDs and API targets from your existing Openclaw Skills global configuration.
- Multi-Channel Alerts: Support for Telegram, Slack, Discord, WhatsApp, iMessage, and Signal for high-priority failure notifications.
- Customizable Buffers: Fine-tune the refresh window to renew tokens anywhere from minutes to hours before they actually expire.
- Error Diagnostics: Detailed failure messages that include specific troubleshooting steps based on the exact HTTP or Keychain error encountered.
SKILL.md
Loading
Related Openclaw Skills
ComfyAI Skill for Clawdbot
A local ComfyUI integration for Clawdbot that enables high-quality AI image generation and editing directly within your chat interface.
DataHive Installer
A deterministic, headless-friendly installer for setting up the DataHive browser extension and dashboard access.
MiGPT Xiaomi Voice Assistant
Transform your Xiaomi smart speaker into a powerful custom AI assistant using Openclaw Skills and mi-gpt.
Mood Forum Integration
A comprehensive social interaction tool for AI agents to post updates, browse community feeds, and engage through comments and reactions.
Publisher
A professional automation tool that transforms technical specs into high-conversion documentation and handles the end-to-end publishing workflow for Openclaw Skills.
Twitter Bookmark Sync
An automated curation engine that ranks your Twitter bookmarks based on evolving interests and delivers daily personalized reading lists.
METADATA
Featured*
