feat(models): add oauth auth health
This commit is contained in:
Peter Steinberger
@@ -1,79 +1,82 @@
|
||||
---
|
||||
summary: "Model authentication: OAuth, API keys, and Claude Code token reuse"
|
||||
read_when:
|
||||
- Debugging model auth or OAuth expiry
|
||||
- Documenting authentication or credential storage
|
||||
---
|
||||
# Authentication
|
||||
|
||||
Clawdbot uses Claude Code's authentication system for API access. By default, OAuth tokens expire every ~24 hours, requiring frequent re-authentication. For a better experience, you can set up a long-lived token that lasts **1 year**.
|
||||
Clawdbot supports OAuth and API keys for model providers. For Anthropic
|
||||
subscription accounts, the most stable path is to **reuse Claude Code OAuth
|
||||
credentials**, including the 1‑year token created by `claude setup-token`.
|
||||
|
||||
## Long-Lived Token Setup (Recommended)
|
||||
See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
|
||||
layout.
|
||||
|
||||
Instead of daily re-auth, set up a 1-year token:
|
||||
## Recommended: long‑lived Claude Code token
|
||||
|
||||
Run this on the **gateway host** (the machine running the Gateway):
|
||||
|
||||
```bash
|
||||
claude setup-token
|
||||
```
|
||||
|
||||
This command will:
|
||||
1. Prompt you to visit the Anthropic console
|
||||
2. Create or copy an API key
|
||||
3. Store it for Claude Code (and Clawdbot)
|
||||
|
||||
After running `setup-token`, sync the credentials to Clawdbot:
|
||||
This issues a long‑lived **OAuth token** (not an API key) and stores it for
|
||||
Claude Code. Then sync and verify:
|
||||
|
||||
```bash
|
||||
clawdbot doctor --yes
|
||||
clawdbot models status
|
||||
clawdbot doctor
|
||||
```
|
||||
|
||||
## Checking Auth Status
|
||||
|
||||
To check your current authentication status:
|
||||
Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
|
||||
|
||||
```bash
|
||||
# If you have the auth scripts installed
|
||||
~/clawdbot/scripts/claude-auth-status.sh
|
||||
|
||||
# Or check manually
|
||||
cat ~/.claude/.credentials.json | jq '.claudeAiOauth.expiresAt'
|
||||
clawdbot models status --check
|
||||
```
|
||||
|
||||
## How It Works
|
||||
Optional ops scripts (systemd/Termux) are documented here:
|
||||
[/automation/auth-monitoring](/automation/auth-monitoring)
|
||||
|
||||
1. **Claude Code** stores credentials in `~/.claude/.credentials.json`
|
||||
2. **Clawdbot** syncs from Claude Code to `~/.clawdbot/agents/main/agent/auth-profiles.json`
|
||||
3. The `clawdbot doctor --yes` command triggers this sync automatically
|
||||
`clawdbot models status` loads Claude Code credentials into Clawdbot’s
|
||||
`auth-profiles.json` and shows expiry (warns within 24h by default).
|
||||
`clawdbot doctor` also performs the sync when it runs.
|
||||
|
||||
## Token Types
|
||||
> `claude setup-token` requires an interactive TTY.
|
||||
|
||||
| Type | Duration | Setup |
|
||||
|------|----------|-------|
|
||||
| OAuth (default) | ~24 hours | Automatic on first run |
|
||||
| Long-lived token | 1 year | `claude setup-token` |
|
||||
## Checking model auth status
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
clawdbot doctor
|
||||
```
|
||||
|
||||
## How sync works
|
||||
|
||||
1. **Claude Code** stores credentials in `~/.claude/.credentials.json` (or
|
||||
Keychain on macOS).
|
||||
2. **Clawdbot** syncs those into
|
||||
`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` when the auth store is
|
||||
loaded.
|
||||
3. OAuth refresh happens automatically on use if a token is expired.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No credentials found" error
|
||||
### “No credentials found”
|
||||
|
||||
Run the doctor to sync credentials:
|
||||
If the Anthropic OAuth profile is missing, run `claude setup-token` on the
|
||||
**gateway host**, then re-check:
|
||||
|
||||
```bash
|
||||
clawdbot doctor --yes
|
||||
clawdbot models status
|
||||
```
|
||||
|
||||
Then restart the service:
|
||||
### Token expiring/expired
|
||||
|
||||
```bash
|
||||
systemctl --user restart clawdbot
|
||||
```
|
||||
|
||||
### Token expired
|
||||
|
||||
If your token has expired, run `claude setup-token` again in a terminal (not from within Claude Code, as it requires an interactive TTY).
|
||||
|
||||
### Checking token expiry
|
||||
|
||||
```bash
|
||||
# Check both Claude Code and Clawdbot auth
|
||||
cat ~/.claude/.credentials.json | jq '.claudeAiOauth.expiresAt' | xargs -I{} date -d @$(({}/1000))
|
||||
```
|
||||
Run `clawdbot models status` to confirm which profile is expiring. If the profile
|
||||
is `anthropic:claude-cli`, rerun `claude setup-token`.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Max or Pro subscription (for `setup-token`)
|
||||
- Claude Max or Pro subscription (for `claude setup-token`)
|
||||
- Claude Code CLI installed (`claude` command available)
|
||||
|
||||
@@ -61,6 +61,7 @@ cat ~/.clawdbot/clawdbot.json
|
||||
- Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
|
||||
- State integrity and permissions checks (sessions, transcripts, state dir).
|
||||
- Config file permission checks (chmod 600) when running locally.
|
||||
- Model auth health: checks OAuth expiry and can refresh expiring tokens.
|
||||
- Legacy workspace dir detection (`~/clawdis`, `~/clawdbot`).
|
||||
- Sandbox image repair when sandboxing is enabled.
|
||||
- Legacy service migration and extra gateway detection.
|
||||
@@ -135,33 +136,40 @@ Doctor checks:
|
||||
- **Config file permissions**: warns if `~/.clawdbot/clawdbot.json` is
|
||||
group/world readable and offers to tighten to `600`.
|
||||
|
||||
### 5) Sandbox image repair
|
||||
### 5) Model auth health (OAuth expiry)
|
||||
Doctor inspects OAuth profiles in the auth store, warns when tokens are
|
||||
expiring/expired, and can refresh them when safe. If the Anthropic Claude Code
|
||||
profile is stale, it suggests `claude setup-token` on the gateway host.
|
||||
Refresh prompts only appear when running interactively (TTY); `--non-interactive`
|
||||
skips refresh attempts.
|
||||
|
||||
### 6) Sandbox image repair
|
||||
When sandboxing is enabled, doctor checks Docker images and offers to build or
|
||||
switch to legacy names if the current image is missing.
|
||||
|
||||
### 6) Gateway service migrations and cleanup hints
|
||||
### 7) Gateway service migrations and cleanup hints
|
||||
Doctor detects legacy Clawdis gateway services (launchd/systemd/schtasks) and
|
||||
offers to remove them and install the Clawdbot service using the current gateway
|
||||
port. It can also scan for extra gateway-like services and print cleanup hints
|
||||
to ensure only one gateway runs per machine.
|
||||
|
||||
### 7) Security warnings
|
||||
### 8) Security warnings
|
||||
Doctor emits warnings when a provider is open to DMs without an allowlist, or
|
||||
when a policy is configured in a dangerous way.
|
||||
|
||||
### 8) systemd linger (Linux)
|
||||
### 9) systemd linger (Linux)
|
||||
If running as a systemd user service, doctor ensures lingering is enabled so the
|
||||
gateway stays alive after logout.
|
||||
|
||||
### 9) Skills status
|
||||
### 10) Skills status
|
||||
Doctor prints a quick summary of eligible/missing/blocked skills for the current
|
||||
workspace.
|
||||
|
||||
### 10) Gateway health check + restart
|
||||
### 11) Gateway health check + restart
|
||||
Doctor runs a health check and offers to restart the gateway when it looks
|
||||
unhealthy.
|
||||
|
||||
### 11) Supervisor config audit + repair
|
||||
### 12) Supervisor config audit + repair
|
||||
Doctor checks the installed supervisor config (launchd/systemd/schtasks) for
|
||||
missing or outdated defaults (e.g., systemd network-online dependencies and
|
||||
restart delay). When it finds a mismatch, it recommends an update and can
|
||||
@@ -174,24 +182,24 @@ Notes:
|
||||
- `clawdbot doctor --repair --force` overwrites custom supervisor configs.
|
||||
- You can always force a full rewrite via `clawdbot daemon install --force`.
|
||||
|
||||
### 12) Gateway runtime + port diagnostics
|
||||
### 13) Gateway runtime + port diagnostics
|
||||
Doctor inspects the daemon runtime (PID, last exit status) and warns when the
|
||||
service is installed but not actually running. It also checks for port collisions
|
||||
on the gateway port (default `18789`) and reports likely causes (gateway already
|
||||
running, SSH tunnel).
|
||||
|
||||
### 13) Gateway runtime best practices
|
||||
### 14) Gateway runtime best practices
|
||||
Doctor warns when the gateway service runs on Bun or a version-managed Node path
|
||||
(`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram providers require Node,
|
||||
and version-manager paths can break after upgrades because the daemon does not
|
||||
load your shell init. Doctor offers to migrate to a system Node install when
|
||||
available (Homebrew/apt/choco).
|
||||
|
||||
### 14) Config write + wizard metadata
|
||||
### 15) Config write + wizard metadata
|
||||
Doctor persists any config changes and stamps wizard metadata to record the
|
||||
doctor run.
|
||||
|
||||
### 15) Workspace tips (backup + memory system)
|
||||
### 16) Workspace tips (backup + memory system)
|
||||
Doctor suggests a workspace memory system when missing and prints a backup tip
|
||||
if the workspace is not already under git.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user