ROOH/openclaw_oauth_sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add LLM install guide for ClaudeHack setup

Browse Source
This commit is contained in:
RED SOUL
2026-04-05 06:27:52 +00:00
parent 81b4bbe960
commit aa4ed22139
1 changed files with 577 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

577
LLM-INSTALL-CLAUDEHACK.md Normal file
View File

@@ -0,0 +1,577 @@
# LLM-INSTALL-CLAUDEHACK.md
Use this guide when an AI agent (OpenClaw, Claude Code, Codex, etc.) is asked to install the OAuth token sync system from this repo onto a fresh or existing OpenClaw host, and to expose a separate optional `claudehack` model provider.
## Goal
Install the OAuth token sync system from:
`https://git.eeqj.de/ROOH/openclaw_oauth_sync`
onto the target OpenClaw machine, without using the repo's interactive installer, and with these additional requirements:
- install the token sync manually by reading this repo's `setup.sh`, `scripts/`, `templates/`, and `docs/`
- **skip webhook security entirely** (Step 11 in `setup.sh`)
- add a **new optional provider** named `claudehack`
- do **not** replace or modify existing providers beyond what is required to add `claudehack`
- do **not** set `claudehack` as the system primary or fallback default
- keep all existing OpenClaw behavior intact unless explicitly required below
---
## Hard Rules
1. **Do NOT run `setup.sh` interactively.**
- Read it to understand the system.
- Perform the installation manually.
2. **Do NOT modify webhook security.**
- Skip webhook security completely.
- Skip Step 11 in `setup.sh`.
3. **Do NOT remove or overwrite existing providers, auth profiles, defaults, or models unless explicitly required below.**
- This install is additive.
4. **Do NOT make `claudehack` the default model or fallback model.**
- It must remain an optional selectable provider.
5. **Do NOT guess paths.**
- Detect actual paths on the machine first.
6. **Do NOT assume all per-agent files already exist.**
- Create missing `models.json` or `auth-profiles.json` files where required.
---
## Prerequisites
Run:
```bash
apt-get update
apt-get install -y inotify-tools python3 curl
```
Verify Docker and Docker Compose v2 are available:
```bash
docker compose version
```
If Node.js is not installed on the host, install it:
```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs
```
Then install Claude CLI on the host:
```bash
npm install -g @anthropic-ai/claude-code
```
---
## Step 1 — Identify OpenClaw Paths
Find the actual OpenClaw paths on the machine.
Defaults are usually:
- `OPENCLAW_CONFIG_DIR=/root/.openclaw`
- `COMPOSE_DIR=/root/openclaw`
These should contain:
- `/root/.openclaw/openclaw.json`
- `/root/openclaw/docker-compose.yml`
- `/root/openclaw/.env`
Find the gateway container name:
```bash
docker ps --filter name=openclaw --format '{{.Names}}' | grep gateway
```
Set and verify:
- `OPENCLAW_CONFIG_DIR`
- `COMPOSE_DIR`
- `GATEWAY_CONTAINER`
Do not continue until these are confirmed.
---
## Step 2 — Install and Authenticate Claude CLI
Claude CLI must be authenticated on the **host**, because this install relies on the Claude CLI OAuth credentials file and its token refresh behavior.
Run:
```bash
claude
```
This opens the OAuth login flow. Complete the authentication in the browser.
Verify CLI access works:
```bash
claude -p "say hello" --no-session-persistence
```
Locate the credentials file:
```bash
ls -la ~/.claude/.credentials.json
```
On a standard root-based install, this file is usually:
```bash
/root/.claude/.credentials.json
```
Set:
- `CLAUDE_CREDS_FILE=/root/.claude/.credentials.json`
or the actual discovered path
Do not continue unless the file exists and contains valid OAuth credentials.
---
## Step 3 — Install the Sync Script
Use the repo's `scripts/sync-oauth-token.sh` as the base.
Substitute these placeholders:
- `@@CLAUDE_CREDS_FILE@@` → credentials file path from Step 2
- `@@OPENCLAW_OAUTH_FILE@@` → `/root/.openclaw/credentials/oauth.json`
- `@@OPENCLAW_ENV_FILE@@` → `/root/openclaw/.env`
- `@@COMPOSE_DIR@@` → `/root/openclaw`
Install the rendered script to:
```bash
/root/sync-oauth-token.sh
```
Then:
```bash
chmod +x /root/sync-oauth-token.sh
```
### Required custom addition
After the `.env` update section in the sync script, and **before** the gateway recreate section, add this logic:
```bash
FRESH_TOKEN=$(python3 -c "import json; d=json.load(open('$CLAUDE_CREDS_FILE')); print(d['claudeAiOauth']['accessToken'])")
if [ -n "$FRESH_TOKEN" ]; then
python3 /root/update-claudehack-profiles.py "$FRESH_TOKEN" 2>&1 | sed "s/^/$LOG_PREFIX /"
fi
```
### Create the helper profile updater
Create:
```bash
/root/update-claudehack-profiles.py
```
Make it executable:
```bash
chmod +x /root/update-claudehack-profiles.py
```
This script must:
- take the access token as its first argument
- iterate over every:
```bash
/root/.openclaw/agents/*/agent/auth-profiles.json
```
- create missing files if needed
- update the `"access"` field inside the `"claudehack:default"` profile
- preserve other profile data
- use the auth profile structure described in `setup.sh` Step 6
---
## Step 4 — Install the Trigger Script
Use the repo's `scripts/trigger-claude-refresh.sh` as the base.
Substitute:
- `@@CREDS_FILE@@` → the credentials file path from Step 2
- `@@REAUTH_FLAG@@` → `/root/openclaw/REAUTH_NEEDED`
- `@@CLI_MODE@@` → `host`
- `@@CLI_CONTAINER@@` → empty / unused
- `@@CLI_BASE_URL_OVERRIDE@@` → `false`
Why `false`:
- Claude CLI runs directly on the host
- it is not running inside the proxy container
- no container-local base URL override is needed
Install to:
```bash
/root/trigger-claude-refresh.sh
```
Then:
```bash
chmod +x /root/trigger-claude-refresh.sh
```
---
## Step 5 — Install Systemd Units
Use the repo's `templates/` directory as the base for these units:
- `sync-oauth-token.service`
- `trigger-claude-refresh.service`
- `trigger-claude-refresh.timer`
Substitute:
- `@@SYNC_SCRIPT_PATH@@` → `/root/sync-oauth-token.sh`
- `@@TRIGGER_SCRIPT_PATH@@` → `/root/trigger-claude-refresh.sh`
Install them to:
```bash
/etc/systemd/system/
```
Then run:
```bash
systemctl daemon-reload
systemctl enable --now sync-oauth-token.service
systemctl enable --now trigger-claude-refresh.timer
```
---
## Step 6 — Configure the `claudehack` Provider
This is a **new provider** separate from OpenClaw’s built-in `anthropic` provider.
Do **not** modify existing provider identities beyond adding the new provider and related model entries.
Three separate configuration locations must be updated.
### 6.1 Global `openclaw.json` → `models.providers`
Add a new provider entry named:
```json
"claudehack"
```
Provider requirements:
- `baseUrl`: `"https://api.anthropic.com"`
- `api`: `"anthropic-messages"`
Add two models:
1. `claude-opus-4-6`
- name: `"ClaudeHack Opus 4.6"`
- contextWindow: `200000`
- maxTokens: `32000`
- input: `["text", "image"]`
- costs: all zero
2. `claude-sonnet-4-6`
- name: `"ClaudeHack Sonnet 4.6"`
- contextWindow: `200000`
- maxTokens: `32000`
- input: `["text", "image"]`
- costs: all zero
### 6.2 Global `openclaw.json` → `agents.defaults.models`
Add these model registrations:
- `claudehack/claude-opus-4-6`
- alias: `"ClaudeHack Opus 4.6"`
- `claudehack/claude-sonnet-4-6`
- alias: `"ClaudeHack Sonnet 4.6"`
These are additive registrations only.
### 6.3 Per-agent `models.json`
For every agent directory:
```bash
/root/.openclaw/agents/*/agent/models.json
```
Add the same `claudehack` provider block to the file’s `providers` object.
If the file does not exist, create it.
Do not delete existing providers.
---
## Step 7 — Configure Auth Profiles
For **every**:
```bash
/root/.openclaw/agents/*/agent/auth-profiles.json
```
add a new profile entry.
If the file does not exist, create it.
Read the fresh token from:
```json
claudeAiOauth.accessToken
```
inside the Claude CLI credentials file.
### Required structure
Under `profiles`, add:
```json
"claudehack:default": {
"type": "oauth",
"provider": "claudehack",
"access": "<FRESH_TOKEN>"
}
```
Under `lastGood`, add:
```json
"claudehack": "claudehack:default"
```
Under `usageStats`, add:
```json
"claudehack:default": {
"errorCount": 0
}
```
Preserve all existing profile entries.
---
## Step 8 — Initial Sync and Verify
Restart the sync service to trigger the initial sync:
```bash
systemctl restart sync-oauth-token.service
```
Check logs:
```bash
journalctl -u sync-oauth-token.service --since "1 min ago" --no-pager
```
Expected successful behavior should include log output indicating:
- updated `oauth.json`
- updated `.env`
- updated `N` claudehack auth profiles
- gateway recreated
### Verify service state
```bash
systemctl is-active sync-oauth-token.service
```
Expected:
```bash
active
```
Check timer registration:
```bash
systemctl list-timers --all | grep trigger-claude-refresh
```
Expected:
- `trigger-claude-refresh.timer` is installed
- next run time is visible
Check gateway container health:
```bash
docker ps
```
Confirm the OpenClaw gateway is up and healthy.
Check gateway logs for config reload / startup success and `claudehack` availability:
```bash
docker logs "$GATEWAY_CONTAINER" --tail 200
```
---
## Critical Gotchas
These are mandatory. If any of these are wrong, the install may silently fail.
### 1. Auth profile field must be `access`, not `key`
Correct:
```json
"access": "<TOKEN>"
```
Wrong:
```json
"key": "<TOKEN>"
```
Using `key` causes OpenClaw to silently skip the profile.
---
### 2. Auth profile type must be `oauth`, not `token`
Correct:
```json
"type": "oauth"
```
Wrong:
```json
"type": "token"
```
Why:
- `oauth` tells the gateway to attach Claude Code identity headers
- without those headers, Anthropic rejects the request with errors like:
> "Third-party apps now draw from your extra usage"
---
### 3. The sync script must use `docker compose down` then `up`, not `restart`
Do **not** use:
```bash
docker compose restart
```
Use a full recreate flow so updated environment values are picked up.
Reason:
- `restart` can reuse cached environment variables
- the updated `ANTHROPIC_OAUTH_TOKEN` from `.env` may not be applied
---
### 4. `oauth.json` field mapping is different from Claude CLI credentials
Claude CLI credentials file uses:
- `accessToken`
- `refreshToken`
- `expiresAt`
OpenClaw `oauth.json` expects:
- `access`
- `refresh`
- `expires`
The sync script must translate these correctly.
---
### 5. All three model registration points are required
You must update all three:
1. global `models.providers`
2. global `agents.defaults.models`
3. per-agent `models.json`
If any of these are missing:
- models may not appear in the UI
- model selection may fail
- requests may error with `"Unknown model"`
---
### 6. Do not set `claudehack` as primary or fallback defaults
This install is additive only.
The system’s existing primary/fallback models must remain unchanged unless explicitly requested by the human operator.
---
## Definition of Done
The install is complete only when **all** of the following are true:
1. Claude CLI is installed and authenticated on the host
2. `~/.claude/.credentials.json` exists and contains valid OAuth data
3. `/root/sync-oauth-token.sh` exists, is executable, and includes the `update-claudehack-profiles.py` call
4. `/root/update-claudehack-profiles.py` exists and is executable
5. `/root/trigger-claude-refresh.sh` exists and is executable
6. all required systemd units are installed and enabled
7. `claudehack` exists in global `openclaw.json`
8. `claudehack` model aliases exist in global `agents.defaults.models`
9. every agent has `claudehack` provider entries in `models.json`
10. every agent has `claudehack:default` in `auth-profiles.json`
11. sync service runs successfully
12. timer is active
13. gateway is healthy
14. `claudehack/claude-opus-4-6` and `claudehack/claude-sonnet-4-6` are visible as optional models
15. existing defaults and providers were preserved
16. webhook security was not installed or modified
---
## Final Notes for the Installing Agent
- Be conservative.
- Preserve existing config.
- Make additive changes only.
- Do not silently skip missing files; create them correctly.
- Validate every file written.
- Validate service state after installation.
- Validate the gateway actually sees the new models.
- Skip webhook security entirely.