0b94cb8fd5
- Add .editorconfig, .prettierrc, .prettierignore, .gitignore - Add Makefile with fmt, fmt-check, secret-scan, test (skip) targets - Add package.json with prettier - Add tools/secret-scan.sh - Add .secret-scan-allowlist for documentation token format references - Sanitize documentation to use generic placeholders - Auto-format with prettier - make check passes clean
109 lines
4.1 KiB
Markdown
109 lines
4.1 KiB
Markdown
# How Token Refresh Works
|
|
|
|
## Anthropic OAuth Token Lifecycle
|
|
|
|
Claude Max subscriptions use OAuth tokens for API authentication.
|
|
|
|
- **Access token** (`<access-token-value>`): Used for API requests, expires in ~8 hours
|
|
- **Refresh token** (`<refresh-token-value>`): Used to get new access tokens, long-lived
|
|
- **Token endpoint**: `POST https://console.anthropic.com/v1/oauth/token`
|
|
- **Client ID**: `9d1c250a-e61b-44d9-88ed-5944d1962f5e` (Claude Code public OAuth client)
|
|
|
|
## How Claude Code CLI Refreshes Tokens
|
|
|
|
Claude Code CLI has built-in token refresh. Before each API request:
|
|
|
|
1. Checks `[API:auth] OAuth token check` — reads `.credentials.json`
|
|
2. If access token is expired or near expiry:
|
|
- Sends `grant_type: "refresh_token"` to Anthropic's token endpoint
|
|
- Gets back new `access_token`, `refresh_token`, `expires_in`
|
|
- Writes updated credentials back to `.credentials.json`
|
|
3. Uses the (possibly refreshed) access token for the API request
|
|
|
|
The relevant function in Claude Code's minified source (`cli.js`):
|
|
|
|
```javascript
|
|
// Simplified from minified source
|
|
async function refreshToken(refreshToken, scopes) {
|
|
const params = {
|
|
grant_type: 'refresh_token',
|
|
refresh_token: refreshToken,
|
|
client_id: CLIENT_ID,
|
|
scope: scopes.join(' '),
|
|
};
|
|
const response = await axios.post(TOKEN_URL, params, {
|
|
headers: { 'Content-Type': 'application/json' },
|
|
});
|
|
return {
|
|
accessToken: response.data.access_token,
|
|
refreshToken: response.data.refresh_token || refreshToken,
|
|
expiresAt: Date.now() + response.data.expires_in * 1000,
|
|
scopes: response.data.scope.split(' '),
|
|
};
|
|
}
|
|
```
|
|
|
|
## Why We Need a Sync Service
|
|
|
|
The problem is that Claude Code CLI and OpenClaw are **separate processes in separate containers**:
|
|
|
|
- Claude Code CLI runs in `claude-proxy` container, writes to its own `.credentials.json`
|
|
- OpenClaw gateway runs in `openclaw-openclaw-gateway-1`, reads from `oauth.json` and env vars
|
|
|
|
They don't share the same credential files. So when Claude CLI refreshes the token, OpenClaw doesn't know about it.
|
|
|
|
## The Sync Approach (inotifywait)
|
|
|
|
We use `inotifywait` from `inotify-tools` to watch for file changes in real-time:
|
|
|
|
```bash
|
|
inotifywait -q -e close_write,moved_to "$WATCH_DIR"
|
|
```
|
|
|
|
- **`close_write`**: Fires when a file is written and closed (normal writes)
|
|
- **`moved_to`**: Fires when a file is moved into the directory (atomic writes: write to temp, then `mv`)
|
|
- We watch the **directory** not the file, because atomic renames create a new inode
|
|
|
|
When the file changes:
|
|
|
|
1. Read `accessToken`, `refreshToken`, `expiresAt` from Claude CLI format
|
|
2. Map fields: `accessToken` -> `access`, `refreshToken` -> `refresh`, `expiresAt` -> `expires`
|
|
3. Write to `oauth.json` (for gateway's `mergeOAuthFileIntoStore()`)
|
|
4. Update `ANTHROPIC_OAUTH_TOKEN` in `.env`
|
|
5. Recreate gateway container (`docker compose down/up`) to reload env vars
|
|
|
|
## The Fallback Approach (Timer)
|
|
|
|
If `inotifywait` is unavailable, a systemd timer runs every 6 hours:
|
|
|
|
1. Reads current refresh token from `.credentials.json`
|
|
2. Calls Anthropic's token endpoint directly
|
|
3. Writes new tokens to all credential locations
|
|
4. Recreates gateway container
|
|
|
|
This is less responsive (up to 6-hour delay) but works without inotify.
|
|
|
|
## Field Mapping
|
|
|
|
| Claude CLI (`.credentials.json`) | OpenClaw (`oauth.json`) |
|
|
| -------------------------------- | ----------------------- |
|
|
| `claudeAiOauth.accessToken` | `anthropic.access` |
|
|
| `claudeAiOauth.refreshToken` | `anthropic.refresh` |
|
|
| `claudeAiOauth.expiresAt` | `anthropic.expires` |
|
|
| `claudeAiOauth.scopes` | `anthropic.scopes` |
|
|
|
|
## Timeline
|
|
|
|
```
|
|
T=0h Token issued (access + refresh)
|
|
T=7.5h Claude CLI detects token nearing expiry
|
|
T=7.5h CLI calls refresh endpoint, gets new tokens
|
|
T=7.5h CLI writes new .credentials.json
|
|
T=7.5h inotifywait detects change (< 1 second)
|
|
T=7.5h sync-oauth-token.sh syncs to oauth.json + .env
|
|
T=7.5h Gateway recreated with fresh token
|
|
T=8h Old token would have expired (but we already refreshed)
|
|
```
|
|
|
|
The entire sync happens within seconds of the CLI refresh, well before the old token expires.
|