Introduction
# claude-connect
**Connect your Claude subscription to Clawdbot in one step.**
Automatically: - ✅ Reads Claude OAuth tokens from Keychain - ✅ Writes them to Clawdbot in proper OAuth format - ✅ Auto-refreshes every 2 hours (before expiry) - ✅ Notifies you on success/failure - ✅ Works with `clawdbot onboard` (fixes OAuth auth-profiles bug)
---
## Quick Start
**1. Install the skill:** ```bash clawdhub install claude-connect cd ~/clawd/skills/claude-connect ```
**2. Ensure Claude CLI is logged in:** ```bash claude auth # Follow the browser login flow ```
**3. Run installer:** ```bash ./install.sh ```
That's it! Tokens will refresh automatically every 2 hours.
---
## What It Does
### Fixes `clawdbot onboard` OAuth Bug
When you run `clawdbot onboard --auth-choice claude-cli`, it sometimes doesn't properly write OAuth tokens to `auth-profiles.json`.
This skill: 1. Reads OAuth tokens from macOS Keychain (where Claude CLI stores them) 2. Writes them to `~/.clawdbot/agents/main/agent/auth-profiles.json` in **proper OAuth format**: ```json { "profiles": { "anthropic:claude-cli": { "type": "oauth", "provider": "anthropic", "access": "sk-ant-...", "refresh": "sk-ant-ort...", "expires": 1234567890 } } } ``` 3. Sets up auto-refresh (runs every 2 hours via launchd) 4. Keeps your connection alive 24/7
---
## Installation
### Automatic (Recommended)
```bash cd ~/clawd/skills/claude-connect ./install.sh ```
The installer will: - ✅ Verify Claude CLI is set up - ✅ Create config file - ✅ Set up auto-refresh job (launchd) - ✅ Run first refresh to test
### Manual
1. Copy example config: ```bash cp claude-oauth-refresh-config.example.json claude-oauth-refresh-config.json ```
2. Edit config (optional): ```bash nano claude-oauth-refresh-config.json ```
3. Test refresh: ```bash ./refresh-token.sh --force ```
4. Install launchd job (optional - for auto-refresh): ```bash cp com.clawdbot.claude-oauth-refresher.plist ~/Library/LaunchAgents/ launchctl load ~/Library/LaunchAgents/com.clawdbot.claude-oauth-refresher.plist ```
---
## Configuration
Edit `claude-oauth-refresh-config.json`:
```json { "refresh_buffer_minutes": 30, "log_file": "~/clawd/logs/claude-oauth-refresh.log", "notifications": { "on_success": true, "on_failure": true }, "notification_target": "YOUR_CHAT_ID" } ```
**Options:** - `refresh_buffer_minutes`: Refresh when token has this many minutes left (default: 30) - `log_file`: Where to log refresh activity - `notifications.on_success`: Notify on successful refresh (default: true) - `notifications.on_failure`: Notify on failure (default: true) - `notification_target`: Your Telegram chat ID (or leave empty to disable)
---
## Usage
### Manual Refresh
```bash # Refresh now (even if not expired) ./refresh-token.sh --force
# Refresh only if needed ./refresh-token.sh ```
### Check Status
```bash # View recent logs tail ~/clawd/logs/claude-oauth-refresh.log
# Check auth profile cat ~/.clawdbot/agents/main/agent/auth-profiles.json | jq '.profiles."anthropic:claude-cli"'
# Check Clawdbot status clawdbot models status ```
### Disable Notifications
Ask Clawdbot: ``` Disable Claude refresh success notifications ```
Or edit config: ```json { "notifications": { "on_success": false, "on_failure": true } } ```
---
## How It Works
### Refresh Process
1. **Read from Keychain:** Gets OAuth tokens from `Claude Code-credentials` 2. **Check Expiry:** Only refreshes if < 30 minutes left (or `--force`) 3. **Call OAuth API:** Gets new access + refresh tokens 4. **Update auth-profiles.json:** Writes proper OAuth format 5. **Update Keychain:** Syncs new tokens back 6. **Restart Gateway:** Picks up new tokens 7. **Notify:** Sends success/failure message (optional)
### Auto-Refresh (launchd)
Runs every 2 hours via `~/Library/LaunchAgents/com.clawdbot.claude-oauth-refresher.plist`
**Controls:** ```bash # Stop auto-refresh launchctl unload ~/Library/LaunchAgents/com.clawdbot.claude-oauth-refresher.plist
# Start auto-refresh launchctl load ~/Library/LaunchAgents/com.clawdbot.claude-oauth-refresher.plist
# Check if running launchctl list | grep claude ```
---
## Troubleshooting
### OAuth not working after onboard
**Symptom:** `clawdbot onboard --auth-choice claude-cli` completes but Clawdbot can't use tokens
**Fix:** ```bash cd ~/clawd/skills/claude-connect ./refresh-token.sh --force ```
This will write tokens in proper OAuth format.
### Tokens keep expiring
**Symptom:** Auth keeps failing after 8 hours
**Fix:** Ensure launchd job is running: ```bash launchctl load ~/Library/LaunchAgents/com.clawdbot.claude-oauth-refresher.plist launchctl list | grep claude ```
### No tokens in Keychain
**Symptom:** `No 'Claude Code-credentials' entries found`
**Fix:** Log in with Claude CLI: ```bash claude auth # Follow browser flow ```
Then run refresh again: ```bash ./refresh-token.sh --force ```
---
## Uninstall
```bash cd ~/clawd/skills/claude-connect ./uninstall.sh ```
Or manually: ```bash # Stop auto-refresh launchctl unload ~/Library/LaunchAgents/com.clawdbot.claude-oauth-refresher.plist rm ~/Library/LaunchAgents/com.clawdbot.claude-oauth-refresher.plist
# Remove skill rm -rf ~/clawd/skills/claude-connect ```
---
## Upgrade
If you previously installed an older version:
```bash cd ~/clawd/skills/claude-connect ./validate-update.sh # Check what changed clawdhub update claude-connect # Update to latest ./install.sh # Re-run installer if needed ```
---
## See Also
- [QUICKSTART.md](QUICKSTART.md) - 60-second setup guide - [UPGRADE.md](UPGRADE.md) - Upgrading from older versions - [Clawdbot docs](https://docs.clawd.bot) - Model authentication
---
**Version:** 1.1.0 **Author:** TunaIssaCoding **License:** MIT **Repo:** https://github.com/TunaIssaCoding/claude-connect