@askalf/dario 5.4.16 → 5.4.19

package/docs/integrations/hands-walkthrough.md

@@ -0,0 +1,295 @@
+# dario + hands — battletested setup
+
+End-to-end walkthrough for running [hands](https://github.com/askalf/hands) — a local computer-use agent that drives your OS through its native shell — through dario so the model spend bills against your Claude Pro / Max subscription instead of per-token overage on the computer-use beta. Covers install → mode selection → first run → verification → the gotchas that bite first-time users.
+
+This is the **first-party** walkthrough. hands is one of dario's sister projects under [askalf](https://github.com/askalf), so unlike the OpenHands / OpenClaw guides where dario is *integrating* with someone else's tool, this is the canonical end-to-end stack we run ourselves. Most of the integration work has already been done on both ends: dario v3.33.0 auto-detects hands via system-prompt identity match and preserves the computer-use beta tools (`computer`, `bash`, `str_replace_based_edit_tool`) without you needing any flag.
+
+## Why hands + dario
+
+Hosted "AI controls your computer" products charge $20–50/mo on top of any LLM costs. The math is unfavorable on at least four axes:
+
+| Axis | Hosted product | hands + dario |
+|---|---|---|
+| **Per-task cost** | Bundled into the $20–50/mo tier | **$0** — bills against the Claude Max plan you already pay for |
+| **Where your screenshots go** | Vendor's servers | Your machine. The only outbound is to your chosen LLM endpoint |
+| **What drives your OS** | A screenshot loop simulating clicks | Your actual shell — PowerShell on Windows, `open` + AppleScript on macOS, `xdotool` / `ydotool` on Linux. Faster, cheaper, more reliable |
+| **Audit trail** | Vendor's logs (good luck exporting) | `~/.hands/audit.jsonl` — every tool call, locally, line-delimited JSON. `--dry-run` to plan without acting |
+
+The walkthrough below puts that stack together in 5 minutes.
+
+## Two modes — pick the right one
+
+hands ships with two authentication paths. Same agent loop, same tools — the difference is **where** the model runs and **what it costs.**
+
+| Mode | What it uses | Per-task cost via dario | Audit log | Best for |
+|---|---|---|---|---|
+| **Claude Login** *(default)* | The `claude` CLI as a child process | $0 (the CLI already uses your subscription) | None — `claude` runs the tools internally | Daily use, lowest setup |
+| **SDK mode** | Anthropic SDK directly | **$0** when routed through dario | ✅ `~/.hands/audit.jsonl` | Programmatic access, dry-run planning, security review |
+
+If you already pay for Claude Max and want zero friction, **Claude Login mode** is fine — dario isn't strictly required because the `claude` binary handles subscription billing on its own. dario becomes useful when you want SDK mode's audit log, `--dry-run` planning, or to run hands programmatically from your own scripts — those don't work on Claude Login.
+
+This walkthrough covers both. SDK + dario gets the spotlight because that's where dario actually adds value.
+
+## Prerequisites
+
+| Thing | Version | Why |
+|---|---|---|
+| **Node.js** | 20+ | hands and dario both target Node 20 minimum |
+| **hands** | latest from npm — `npm i -g @askalf/hands` | The agent itself |
+| **dario** | v3.33.0+ (latest preferred — `npm i -g @askalf/dario@latest`) | v3.33.0 added the system-prompt identity match that auto-preserves hands' computer-use tools |
+| **A Claude OAuth login** | run `dario login` once | A Pro / Max subscription on a Claude account |
+| **`claude` CLI** | latest | Required for Claude Login mode; `hands init` will install for you if missing |
+| **Bun** (recommended) | 1.1+ | dario auto-relaunches under Bun for TLS-fingerprint fidelity. Skip if you're fine with a runtime banner; install via [bun.sh](https://bun.sh) for the full subscription wire shape. |
+
+Verify dario before starting:
+
+```bash
+dario doctor          # all green = ready
+dario status          # OAuth healthy, expires in N hours
+```
+
+## Install + init
+
+One npm install, one interactive command:
+
+```bash
+npm install -g @askalf/hands
+hands init
+```
+
+`hands init` walks every choice a new user has to make — auth mode, optional voice (whisper.cpp), `claude` CLI install if missing, dario routing tip. It's safe to re-run; pick a different mode any time.
+
+## Mode 1 — Claude Login (default, simplest)
+
+This is the path `hands init` recommends. Pick "Claude Login" when prompted. Done.
+
+```bash
+hands run "open notepad and type hello world"
+```
+
+What happens under the hood:
+
+1. hands spawns the `claude` CLI as a child process
+2. `claude` uses your Claude Code subscription (the same OAuth login you have for CC)
+3. The agent loop runs inside `claude`, dispatching computer-use tools via hands' shell wrappers
+4. You see the result in your terminal
+
+dario isn't on the path here because `claude` handles subscription billing directly. That's by design — Claude Login mode is the "I want it to just work" path.
+
+If you're using Claude Login mode, **you can stop reading this walkthrough now** — you're done. The rest of this guide covers SDK mode.
+
+## Mode 2 — SDK + dario (audit-logged, programmatic, dry-run)
+
+Pick this mode when you want one of:
+
+- **`--dry-run`** — see exactly what the agent would do before letting it act
+- **`~/.hands/audit.jsonl`** — every tool call timestamped, with args, durations, outcomes. Useful for security review or post-incident forensics.
+- **Programmatic agent runs** from your own Node scripts (importing hands as a library)
+- **A specific Claude account** different from the one your `claude` CLI is logged into (via `dario accounts add`)
+
+Setup is two env vars and one running dario instance:
+
+```bash
+# In whatever shell starts hands:
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario          # or your DARIO_API_KEY if set
+```
+
+Add those to your shell profile (`~/.bashrc`, `~/.zshrc`, fish config, PowerShell `$PROFILE`) so they're set for every session.
+
+Then in one terminal:
+
+```bash
+dario proxy --verbose
+```
+
+In another:
+
+```bash
+hands auth        # pick "API Key" — when prompted for the key, paste: dario
+hands run "open notepad and type hello world"
+```
+
+That's it. The Anthropic SDK reads the env vars by default, so no hands-side config is needed beyond `hands auth` once.
+
+### What dario does for hands automatically
+
+You don't need any flag. Dario v3.33.0+ recognizes hands via a system-prompt identity match and:
+
+- **Preserves** the Anthropic computer-use beta tools (`computer`, `bash`, `str_replace_based_edit_tool`) instead of remapping them to CC's canonical set. The computer-use beta tools have schema fields CC's tools don't carry; trying to translate them would corrupt the calls.
+- **Strips** orchestration tags from the prompt to keep the wire shape on the subscription path.
+- **Forwards** the `anthropic-beta: computer-use-*` header so the upstream model knows to enable the beta.
+- Everything else (template replay, OAuth swap, sticky session) runs identically to a Claude Code request.
+
+You'll see this in `dario proxy --verbose` as a log line like:
+
+```
+[dario] #1 POST /v1/messages (model: claude-sonnet-4-6, client: hands, preserve_tools: true, beta: computer-use-2025-01-24) → 200 (1842 ms)
+```
+
+## Voice (optional)
+
+If you opted into voice during `hands init`, you'll have whisper.cpp installed locally. Then:
+
+```bash
+hands run "open chrome and go to amazon.com" --voice
+```
+
+Press Enter to start recording, Enter again to stop. Whisper transcribes locally (no audio leaves your machine), and the transcribed task feeds into the agent loop the same as a typed prompt.
+
+## Verifying subscription billing
+
+Two checks, one at the dario layer and one at Anthropic's:
+
+### Check 1: dario doctor --usage
+
+```bash
+dario doctor --usage
+```
+
+You should see your 5-hour bucket showing non-zero usage with `claim=five_hour (subscription)`:
+
+```
+[ OK ]  Usage 5h (all)          14.2% used  •  status=allowed  •  claim=five_hour (subscription)
+```
+
+If `claim=five_hour (subscription)` shows up, you're billing against the Claude Max plan, not API. Done.
+
+If `claim=api` shows up, something flipped you to per-token billing — usually because you started hands in Claude Login mode (where `claude` doesn't go through dario at all) but then ran SDK mode without setting the env vars. `hands doctor` reports the effective base URL hands sees; cross-check it.
+
+### Check 2: hands' audit log
+
+```bash
+tail -f ~/.hands/audit.jsonl
+```
+
+Every tool call is one JSON-ND record. If you ran `hands run "open notepad"` and the audit log is silent, you're on Claude Login mode (which bypasses hands' tool dispatcher). Switch with `hands auth` to API Key mode if you want the audit trail.
+
+### Check 3: Anthropic dashboard
+
+Log into [console.anthropic.com](https://console.anthropic.com) → Usage. **Your API spend should be flat** (no new charges since you started hands). If it's climbing, the env vars didn't take effect — restart your shell and re-export.
+
+## Battletested patterns
+
+After running hands+dario in production for months, here are the patterns we lean on:
+
+### Plan first, act second
+
+Always run a `--dry-run` before letting hands actually touch anything irreversible:
+
+```bash
+hands run --dry-run "delete every file in ~/Downloads older than 30 days"
+```
+
+`--dry-run` forces SDK mode (which is the only mode where hands sees individual tool calls before they execute), prints the planned action sequence, and exits without doing anything. If the plan looks right, run it without `--dry-run`.
+
+### Pin the model for cost-sensitive runs
+
+Long autonomous loops on Sonnet are usually right. For exploratory single-shot tasks where you just want a quick answer, Haiku is dramatically cheaper *in API mode* — but on subscription via dario, the bucket is the same. Pin Sonnet for everything unless you have a specific reason; the model-choice tradeoff is real on direct API but neutralized through dario.
+
+### Multi-account pool for parallel runs
+
+If you run two or more hands sessions in parallel — say, one task on the desktop and another headless on a server — you'll exhaust a single Claude account's 5-hour bucket. Add a second account to dario's pool and pool mode load-balances:
+
+```bash
+dario login                  # log in to a second Claude account
+dario accounts add work
+```
+
+See [`docs/multi-account-pool.md`](./multi-account-pool.md). Session stickiness ensures multi-turn hands conversations stay on one account.
+
+### Audit-log review before deploying agents into shared environments
+
+Before letting hands SDK-mode loose on a shared machine (CI agent, family computer, etc.), run a representative task with `--dry-run` and read `~/.hands/audit.jsonl` end-to-end. The audit log is exactly the visibility you'd want before signing off on agentic access to a shared OS — and it's local, not vendor-side.
+
+## Common gotchas
+
+### `claude` CLI not found, hands won't start in Claude Login mode
+
+```bash
+hands init    # offers to install claude CLI for you, then re-runs hands setup
+```
+
+Or install Claude Code yourself per [Anthropic's docs](https://docs.anthropic.com/en/docs/claude-code).
+
+### `Connection refused` to localhost:3456 in SDK mode
+
+dario isn't running:
+
+```bash
+curl -s http://localhost:3456/health
+# expected: {"status":"ok",...}
+```
+
+If that fails, start dario (`dario proxy --verbose`) before invoking hands.
+
+### Claim flips to api in SDK mode
+
+Three causes, in order of likelihood:
+
+1. **You're not actually on dario.** Run `hands doctor` — if `Effective base URL` doesn't show `localhost:3456`, the env vars didn't take effect. Restart your shell.
+2. **Your dario template is stale.** Run `dario doctor` and check the template-age line. If it's >48 hours old, the captured CC system prompt may not match what Anthropic's classifier currently expects. `dario doctor --bun-bootstrap` to force a fresh capture.
+3. **You're running hands SDK mode against a different account than the one paying for Max.** Run `dario status` and confirm the OAuth account is the subscription account.
+
+### "computer use" beta header dropped
+
+If dario isn't preserving the `anthropic-beta: computer-use-*` header, you're probably on a dario version older than v3.33.0. Upgrade — the system-prompt identity match and beta-preserve behavior both landed in that release.
+
+```bash
+npm install -g @askalf/dario@latest
+```
+
+### Voice mode says "whisper.cpp not found"
+
+```bash
+hands init     # offers to download whisper.cpp for you
+```
+
+Or install it yourself: clone [ggerganov/whisper.cpp](https://github.com/ggerganov/whisper.cpp), `make`, and put the binary on your `PATH`.
+
+### Hands hangs on a screenshot in SDK mode
+
+Computer-use beta requests with multiple screenshots can be slow on first response. Bump retry config in your shell:
+
+```bash
+export ANTHROPIC_REQUEST_TIMEOUT_MS=120000
+```
+
+dario's outbound timeout is 5 min by default, so this is purely about hands' own client-side timeout.
+
+## What this guide doesn't cover
+
+- **hands as a library** (importing into your own Node scripts). The dario integration works the same way — env vars route the underlying SDK to `localhost:3456`. See hands' README for the programmatic API surface.
+- **Custom agents extending hands' core.** Subclassing the agent loop is supported but out of scope here. The dario integration is at the LLM layer; agent code doesn't need to change.
+
+## Quick reference card
+
+```bash
+# One-time setup
+npm install -g @askalf/dario @askalf/hands
+dario login
+hands init
+
+# Per-session — Claude Login mode (default, no dario needed)
+hands run "your task here"
+
+# Per-session — SDK + dario mode (audit-logged, programmatic, --dry-run)
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario
+dario proxy --verbose &
+hands run "your task here"
+
+# Verify subscription billing
+dario doctor --usage              # claim=five_hour (subscription) ✓
+hands doctor                      # effective base URL shows localhost:3456
+tail -f ~/.hands/audit.jsonl      # tool calls flowing in real time (SDK mode only)
+```
+
+## Related guides
+
+- [`openhands-walkthrough.md`](./openhands-walkthrough.md) — sister walkthrough for the OpenHands software-engineer agent
+- [`openclaw-walkthrough.md`](./openclaw-walkthrough.md) — sister walkthrough for OpenClaw
+- [`agent-compat.md`](./agent-compat.md) — short setup snippets for every other agent dario supports
+- [`multi-account-pool.md`](./multi-account-pool.md) — adding 2+ Claude accounts to extend rate limits for parallel hands runs
+- [`commands.md`](./commands.md) — full dario CLI reference
+- [hands repo](https://github.com/askalf/hands) — full hands documentation, security model, and architecture deep-dive

package/docs/integrations/openclaw-walkthrough.md

@@ -0,0 +1,248 @@
+# dario + OpenClaw — battletested setup
+
+End-to-end walkthrough for running OpenClaw through dario so it routes against your Claude Pro / Max subscription instead of paying per-token API rates. Covers install → config → first run → verification → the gotchas that bite first-time users — including the `openclaw.inbound_meta.v1` classifier filter that dario's default mode silently protects against.
+
+This is opinionated. There are several ways to wire OpenClaw to dario; this is the one we run in production and trust to not surprise us. Where we omit options it's because they're worse, not because they don't exist.
+
+## What you'll have at the end
+
+- OpenClaw running locally, talking to dario at `localhost:3456`
+- All Claude API calls routed through your Pro / Max subscription via the Claude Code wire shape
+- OpenClaw's tool schema (`exec`, `process`, `web_search`, `web_fetch`, `browser`, `message`) auto-translated to CC's canonical set on the outbound path and rebuilt back on the inbound path — **no flag required**
+- Your `openclaw.inbound_meta.v1` namespace stripped at the proxy boundary so Anthropic's billing classifier doesn't flip you to extra-usage
+- `dario doctor --usage` showing the OpenClaw traffic in your 5-hour bucket with `claim=five_hour (subscription)`
+
+Total install + config: 5–10 minutes if dario is already installed.
+
+## Prerequisites
+
+| Thing | Version | Why |
+|---|---|---|
+| **OpenClaw** | 2026.2.17+ recommended | Older versions read auth differently — see auth-profiles gotcha below |
+| **dario** | v3.31.2+ (latest preferred — `npm i -g @askalf/dario@latest`) | Auth-mismatch reject log, structural-fallback tool detection, classifier-fingerprint protection |
+| **A Claude OAuth login** | run `dario login` once | The whole point — a Pro / Max subscription on a Claude account |
+| **Bun** (recommended) | 1.1+ | dario auto-relaunches under Bun for TLS-fingerprint fidelity. Skip if you're fine with a runtime banner; install via [bun.sh](https://bun.sh) for the full subscription wire shape. |
+
+Verify dario before starting OpenClaw — saves you from chasing OpenClaw errors that are actually dario auth issues:
+
+```bash
+dario doctor          # all green = ready
+dario status          # OAuth healthy, expires in N hours
+```
+
+If `dario status` shows expired or missing OAuth, run `dario login` and retry. Don't continue past this step until both are clean.
+
+## Install OpenClaw
+
+Follow the install instructions in [OpenClaw's own README](https://github.com/openclaw/openclaw) — installation steps move with their releases and we'd rather link the canonical source than copy-paste a snapshot that goes stale.
+
+Verify after install:
+
+```bash
+openclaw --version
+```
+
+The rest of this guide assumes a working `openclaw` CLI on your `PATH`.
+
+## Configure OpenClaw → dario
+
+OpenClaw reads its Anthropic configuration from three places, in priority order (2026.2.17+):
+
+1. `~/.openclaw/agents/main/agent/auth-profiles.json` — wins if the `anthropic:default` entry exists
+2. `openclaw.json` — `apiKey` field
+3. `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` env vars — fallback
+
+**This priority order is the single most common source of "why doesn't dario see my requests" tickets** ([dario#97](https://github.com/askalf/dario/issues/97)). Read the next section carefully.
+
+### Step 1 — Set the env vars
+
+Put this in your shell profile (`~/.bashrc`, `~/.zshrc`, fish `config.fish`, or PowerShell `$PROFILE`):
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario
+```
+
+Two things to know:
+
+- `ANTHROPIC_BASE_URL=http://localhost:3456` — points OpenClaw at dario instead of `api.anthropic.com`. dario speaks the Anthropic protocol on this port.
+- `ANTHROPIC_API_KEY=dario` — this string is a literal placeholder. dario doesn't validate it (the real auth lives in dario's stored OAuth token). If you're running dario with `DARIO_API_KEY` set (LAN/multi-host mode), use that value here instead.
+
+### Step 2 — Clear or overwrite the auth-profiles.json entry
+
+If you've ever set up OpenClaw with a real Anthropic API key, the env vars above won't take effect — `auth-profiles.json` wins. Pick one of two fixes:
+
+**Option A: delete the Anthropic entry from auth-profiles.json (preferred — confirmed working by [@tetsuco in dario#97](https://github.com/askalf/dario/issues/97))**
+
+Open `~/.openclaw/agents/main/agent/auth-profiles.json` in any editor, remove the `"anthropic:default"` entry (or the whole file if Anthropic is the only profile in there), save. OpenClaw falls back to the env vars on next run.
+
+**Option B: overwrite the auth-profiles.json entry with `dario`**
+
+```bash
+openclaw models auth paste-token --provider anthropic
+# When prompted, paste the literal string: dario
+```
+
+This replaces whatever was in the file with `dario`. Keep a backup if you use the original key elsewhere.
+
+> **Loopback escape hatch.** If you're running dario at `--host=127.0.0.1` (the default), you don't need `DARIO_API_KEY` set at all and the auth-profiles content matters less — dario only enforces auth on non-loopback binds. So if you can stay on loopback, do; the auth-profiles dance is only needed for LAN reach setups (Tailscale, multi-host).
+
+### Step 3 — Verify the config takes effect
+
+```bash
+echo "$ANTHROPIC_BASE_URL"
+# expected: http://localhost:3456
+```
+
+If that's empty, restart your shell or `source` your profile.
+
+### Battletested model choices
+
+OpenClaw exposes its model selection through its own config. We default to:
+
+| Model | When to use | Notes |
+|---|---|---|
+| `claude-sonnet-4-6` | **Default for everything.** | Best quality/speed for agent loops. What we run 95% of the time. |
+| `claude-opus-5` | Hard reasoning tasks, refactors, novel architecture | ~3× slower per turn, ~3× more tokens. Subscription absorbs the cost; your wall-clock pays. Worth it for one-shot heavy lifts, overkill for routine. |
+| `claude-haiku-4-5` | Fast scripts, quick lookups, smoke tests | Cheap on tokens, weak on multi-step reasoning. Don't run a long autonomous OpenClaw session on Haiku. |
+
+Set the model in OpenClaw's config (the field name varies by OpenClaw version — check `openclaw config --help`). Use the canonical Anthropic model ID (no provider prefix) — OpenClaw is already on the Anthropic protocol.
+
+## First run
+
+Start dario in one terminal:
+
+```bash
+dario proxy --verbose
+```
+
+Leave it running. You'll watch real-time request logs here.
+
+In a second terminal, run an OpenClaw task:
+
+```bash
+openclaw "Add a function to utils.py that takes a list of strings and returns them sorted by length, longest first. Include a docstring and a basic test."
+```
+
+(Exact invocation may differ by OpenClaw version — check `openclaw --help`. The above is the conceptual shape; substitute the right flags for your install.)
+
+Watch the dario terminal — you should see one log line per request, looking like:
+
+```
+[dario] #1 POST /v1/messages (model: claude-sonnet-4-6) → 200 (1843 ms)
+[dario] #2 POST /v1/messages (model: claude-sonnet-4-6) → 200 (2104 ms)
+...
+```
+
+If you see `→ 200` lines and OpenClaw is making progress, you're good. dario's `client: 'unknown-non-cc'` structural fallback is silently auto-translating OpenClaw's `exec` / `process` / `web_search` / `web_fetch` / `browser` / `message` tools to CC's canonical set on the outbound path and rebuilding the OpenClaw shape on the inbound path — no flag, no config.
+
+## Verifying subscription billing (the important part)
+
+This is what separates "OpenClaw talking to dario" from "OpenClaw actually using your Claude subscription." Two checks:
+
+### Check 1: dario doctor --usage
+
+```bash
+dario doctor --usage
+```
+
+You should see your 5-hour bucket showing non-zero usage with `claim=five_hour (subscription)`:
+
+```
+[ OK ]  Usage 5h (all)          12.3% used  •  status=allowed  •  claim=five_hour (subscription)
+```
+
+If `claim=five_hour (subscription)` shows up, you're billing against subscription, not API. Done.
+
+If `claim=api` shows up, something flipped you to per-token billing. The most common cause for OpenClaw users is the next section.
+
+### Check 2: Anthropic dashboard
+
+Log into [console.anthropic.com](https://console.anthropic.com) → Usage. **Your API spend should be flat** (no new charges since you started OpenClaw). If it's climbing, something is bypassing dario.
+
+## How dario protects you from the classifier filter
+
+Anthropic's billing classifier fingerprints the string `openclaw.inbound_meta.v1` and routes any request containing it to extra-usage billing — not subscription. This was reproduced in [dario discussion #178](https://github.com/askalf/dario/discussions/178) following Theo Browne's original finding.
+
+The filter triggers on the `openclaw.inbound_meta.v1` namespace appearing in the request body — which is easy to hit accidentally. If you've ever made a commit message or branch name containing that string in any of your repos, Claude Code's environment block (which CC adds to its prompt) will surface those names back to the model in the system prompt, and the classifier flips your request.
+
+**dario's default template-replay mode protects you from this automatically.** Every outbound request gets rebuilt from dario's captured-fresh CC system prompt — your local git context (commit messages, branch names, modified-file lists) is discarded at the proxy boundary. The `openclaw.inbound_meta.v1` string never leaves your machine.
+
+You don't need to do anything to get this protection — it's the default. The protection is validated by `scripts/research/test-dario-protects-openclaw.mjs` against real Anthropic upstream traffic.
+
+> **If you want to verify it on your own machine:** create a temp git repo with `{"schema": "openclaw.inbound_meta.v1"}` as a commit message, run OpenClaw against dario from inside that repo, and check `dario doctor --usage` — you should still see `claim=five_hour`. Without dario, the same setup would 400 or flip to api-billing.
+
+## Common gotchas
+
+### `401 Unauthorized` from dario, even though `ANTHROPIC_API_KEY=dario` is set
+
+This is the auth-profiles.json priority issue ([dario#97](https://github.com/askalf/dario/issues/97)). OpenClaw is reading a stale Anthropic key from `~/.openclaw/agents/main/agent/auth-profiles.json` instead of your env var. Run `dario proxy -v` to confirm — you'll see `Authorization present but value mismatch (header: x-api-key)` in the reject log. Fix with one of the three options in Step 2 above.
+
+### `Connection refused` to localhost:3456
+
+dario isn't running, or it's bound to a different port:
+
+```bash
+curl -s http://localhost:3456/health
+# expected: {"status":"ok",...}
+```
+
+If that fails, start dario (`dario proxy --verbose`). If it's running on a custom port, match it: `ANTHROPIC_BASE_URL=http://localhost:<port>`.
+
+### `claim=api` showing up in dario doctor --usage
+
+Something is sneaking the `openclaw.inbound_meta.v1` string past dario's template replay. The most common cause is running with `dario proxy --passthrough` (thin proxy, no template injection) — passthrough mode does an OAuth swap only and does NOT scrub the system prompt, so any classifier triggers in your local env survive. Drop the `--passthrough` flag and the default template-replay mode will protect you.
+
+If you actually need passthrough mode for some other reason, you'll need to clean your local git state — rename branches with `openclaw` in their names, rewrite commit messages with that string, and remove any files in your working tree that contain the classifier-fingerprint namespace.
+
+### Long sessions failing with rate limits
+
+If you run multiple parallel OpenClaw sessions on a single Claude account, you'll hit the 5-hour rate limit fast. Two fixes:
+
+1. **Add a second account to dario's pool** (`dario accounts add work` after running `dario login` on a second account). Pool mode routes each request to whichever account has the most headroom and uses session stickiness so multi-turn chats stay on one account. See [`docs/multi-account-pool.md`](./multi-account-pool.md).
+2. **Stagger the runs** — finish one before starting the next. Cheaper, no extra subscription needed.
+
+### Tools come back empty / wrong shape
+
+Symptom: OpenClaw's tool calls round-trip with stripped fields, or your runtime complains about a required field being absent only when routed through dario.
+
+If you see this, run dario with `--preserve-tools`:
+
+```bash
+dario proxy --preserve-tools
+```
+
+This skips the CC tool remap entirely and forwards OpenClaw's tool definitions through to the model unchanged. You lose the CC wire shape (and may lose subscription billing), but you keep all custom tool fields. Reserve for cases where the auto-detection can't reconstruct your schema cleanly.
+
+## What this guide doesn't cover
+
+- **OpenClaw's own internal config flags.** OpenClaw has a rich CLI with options for sandbox, project root, agent loop tuning, etc. We don't shadow them here; check `openclaw --help`. The dario integration is at the LLM layer; agent code doesn't need to change.
+- **OpenClaw derivatives** (forks like `openclaw-billing-proxy`, `nanoclaw`, etc.). These typically work the same way — point them at `localhost:3456` and dario's structural-fallback tool detection (the 3+ tools, ≥80% not in TOOL_MAP rule) catches them automatically. If a specific fork doesn't work, open an issue with the request body shape and we'll add explicit detection.
+
+## Quick reference card
+
+```bash
+# One-time setup
+# (install OpenClaw per its README)
+npm install -g @askalf/dario
+dario login
+
+# Per-session
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario
+# (clear ~/.openclaw/agents/main/agent/auth-profiles.json first if you have a stale Anthropic key)
+dario proxy --verbose &
+openclaw "your task here"
+
+# Verify subscription billing
+dario doctor --usage   # claim=five_hour (subscription) ✓
+```
+
+## Related guides
+
+- [`openhands-walkthrough.md`](./openhands-walkthrough.md) — sister walkthrough for OpenHands
+- [`agent-compat.md`](./agent-compat.md) — short setup snippets for every other agent dario supports
+- [`multi-account-pool.md`](./multi-account-pool.md) — adding 2+ Claude accounts to extend rate limits
+- [`commands.md`](./commands.md) — full dario CLI reference
+- [`faq.md`](./faq.md) — common dario questions, including the OpenClaw auth-profiles 401 entry
+- [`research/system-prompt-classifier-study.md`](./research/system-prompt-classifier-study.md) — empirical work on what the billing classifier reads (and doesn't)