feat(models): add oauth auth health
This commit is contained in:
Peter Steinberger
41
docs/automation/auth-monitoring.md
Normal file
41
docs/automation/auth-monitoring.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
summary: "Monitor OAuth expiry for model providers"
|
||||
read_when:
|
||||
- Setting up auth expiry monitoring or alerts
|
||||
- Automating Claude Code / Codex OAuth refresh checks
|
||||
---
|
||||
# Auth monitoring
|
||||
|
||||
Clawdbot exposes OAuth expiry health via `clawdbot models status`. Use that for
|
||||
automation and alerting; scripts are optional extras for phone workflows.
|
||||
|
||||
## Preferred: CLI check (portable)
|
||||
|
||||
```bash
|
||||
clawdbot models status --check
|
||||
```
|
||||
|
||||
Exit codes:
|
||||
- `0`: OK
|
||||
- `1`: expired or missing credentials
|
||||
- `2`: expiring soon (within 24h)
|
||||
|
||||
This works in cron/systemd and requires no extra scripts.
|
||||
|
||||
## Optional scripts (ops / phone workflows)
|
||||
|
||||
These live under `scripts/` and are **optional**. They assume SSH access to the
|
||||
gateway host and are tuned for systemd + Termux.
|
||||
|
||||
- `scripts/claude-auth-status.sh` now uses `clawdbot models status --json` as the
|
||||
source of truth (falling back to direct file reads if the CLI is unavailable),
|
||||
so keep `clawdbot` on `PATH` for timers.
|
||||
- `scripts/auth-monitor.sh`: cron/systemd timer target; sends alerts (ntfy or phone).
|
||||
- `scripts/systemd/clawdbot-auth-monitor.{service,timer}`: systemd user timer.
|
||||
- `scripts/claude-auth-status.sh`: Claude Code + Clawdbot auth checker (full/json/simple).
|
||||
- `scripts/mobile-reauth.sh`: guided re‑auth flow over SSH.
|
||||
- `scripts/termux-quick-auth.sh`: one‑tap widget status + open auth URL.
|
||||
- `scripts/termux-auth-widget.sh`: full guided widget flow.
|
||||
- `scripts/termux-sync-widget.sh`: sync Claude Code creds → Clawdbot.
|
||||
|
||||
If you don’t need phone automation or systemd timers, skip these scripts.
|
||||
@@ -479,6 +479,9 @@ Options:
|
||||
Options:
|
||||
- `--json`
|
||||
- `--plain`
|
||||
- `--check` (exit 1=expired/missing, 2=expiring)
|
||||
|
||||
Always includes the auth overview and OAuth expiry status for profiles in the auth store.
|
||||
|
||||
### `models set <model>`
|
||||
Set `agent.model.primary`.
|
||||
|
||||
@@ -71,7 +71,14 @@ Shows configured models by default. Useful flags:
|
||||
### `models status`
|
||||
|
||||
Shows the resolved primary model, fallbacks, image model, and an auth overview
|
||||
of configured providers. `--plain` prints only the resolved primary model.
|
||||
of configured providers. It also surfaces OAuth expiry status for profiles found
|
||||
in the auth store (warns within 24h by default). `--plain` prints only the
|
||||
resolved primary model.
|
||||
OAuth status is always shown (and included in `--json` output). If a configured
|
||||
provider has no credentials, `models status` prints a **Missing auth** section.
|
||||
JSON includes `auth.oauth` (warn window + profiles) and `auth.providers`
|
||||
(effective auth per provider).
|
||||
Use `--check` for automation (exit `1` when missing/expired, `2` when expiring).
|
||||
|
||||
## Scanning (OpenRouter free models)
|
||||
|
||||
|
||||
@@ -49,10 +49,13 @@ If you already signed in with the external CLIs *on the gateway host*, Clawdbot
|
||||
- Codex CLI: reads `~/.codex/auth.json` → profile `openai-codex:codex-cli`
|
||||
|
||||
Sync happens when Clawdbot loads the auth store (so it stays up-to-date when the CLIs refresh tokens).
|
||||
On macOS, the first read may trigger a Keychain prompt; run `clawdbot models status`
|
||||
in a terminal once if the Gateway runs headless and can’t access the entry.
|
||||
|
||||
How to verify:
|
||||
|
||||
```bash
|
||||
clawdbot models status
|
||||
clawdbot providers list
|
||||
```
|
||||
|
||||
|
||||
@@ -97,6 +97,14 @@
|
||||
"source": "/bun",
|
||||
"destination": "/install/bun"
|
||||
},
|
||||
{
|
||||
"source": "/auth-monitoring",
|
||||
"destination": "/automation/auth-monitoring"
|
||||
},
|
||||
{
|
||||
"source": "/scripts",
|
||||
"destination": "/scripts"
|
||||
},
|
||||
{
|
||||
"source": "/camera",
|
||||
"destination": "/nodes/camera"
|
||||
@@ -617,6 +625,7 @@
|
||||
{
|
||||
"group": "Automation & Hooks",
|
||||
"pages": [
|
||||
"automation/auth-monitoring",
|
||||
"automation/webhook",
|
||||
"automation/gmail-pubsub",
|
||||
"automation/cron-jobs",
|
||||
@@ -690,6 +699,7 @@
|
||||
{
|
||||
"group": "Reference & Templates",
|
||||
"pages": [
|
||||
"scripts",
|
||||
"reference/rpc",
|
||||
"reference/device-models",
|
||||
"reference/test",
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
26
docs/scripts.md
Normal file
26
docs/scripts.md
Normal file
@@ -0,0 +1,26 @@
|
||||
---
|
||||
summary: "Repository scripts: purpose, scope, and safety notes"
|
||||
read_when:
|
||||
- Running scripts from the repo
|
||||
- Adding or changing scripts under ./scripts
|
||||
---
|
||||
# Scripts
|
||||
|
||||
The `scripts/` directory contains helper scripts for local workflows and ops tasks.
|
||||
Use these when a task is clearly tied to a script; otherwise prefer the CLI.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Scripts are **optional** unless referenced in docs or release checklists.
|
||||
- Prefer CLI surfaces when they exist (example: auth monitoring uses `clawdbot models status --check`).
|
||||
- Assume scripts are host‑specific; read them before running on a new machine.
|
||||
|
||||
## Auth monitoring scripts
|
||||
|
||||
Auth monitoring scripts are documented here:
|
||||
[/automation/auth-monitoring](/automation/auth-monitoring)
|
||||
|
||||
## When adding scripts
|
||||
|
||||
- Keep scripts focused and documented.
|
||||
- Add a short entry in the relevant doc (or create one if missing).
|
||||
@@ -346,7 +346,7 @@ It means the system attempted to use the auth profile ID `anthropic:default`, bu
|
||||
- **Make sure you’re editing the correct agent**
|
||||
- Multi‑agent setups mean there can be multiple `auth-profiles.json` files.
|
||||
- **Sanity‑check model/auth status**
|
||||
- Use `/model status` to see configured models and whether providers are authenticated.
|
||||
- Use `clawdbot models status` to see configured models and whether providers are authenticated.
|
||||
|
||||
### Why did it also try Google Gemini and fail?
|
||||
|
||||
|
||||
Reference in New Issue
Block a user