@termix-it/cryptoclaw 1.0.0

package/docs/gateway/authentication.md

@@ -0,0 +1,145 @@
+---
+summary: "Model authentication: OAuth, API keys, and setup-token"
+read_when:
+  - Debugging model auth or OAuth expiry
+  - Documenting authentication or credential storage
+title: "Authentication"
+---
+
+# Authentication
+
+OpenClaw supports OAuth and API keys for model providers. For Anthropic
+accounts, we recommend using an **API key**. For Claude subscription access,
+use the long‑lived token created by `claude setup-token`.
+
+See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
+layout.
+
+## Recommended Anthropic setup (API key)
+
+If you’re using Anthropic directly, use an API key.
+
+1. Create an API key in the Anthropic Console.
+2. Put it on the **gateway host** (the machine running `openclaw gateway`).
+
+```bash
+export ANTHROPIC_API_KEY="..."
+openclaw models status
+```
+
+3. If the Gateway runs under systemd/launchd, prefer putting the key in
+   `~/.openclaw/.env` so the daemon can read it:
+
+```bash
+cat >> ~/.openclaw/.env <<'EOF'
+ANTHROPIC_API_KEY=...
+EOF
+```
+
+Then restart the daemon (or restart your Gateway process) and re-check:
+
+```bash
+openclaw models status
+openclaw doctor
+```
+
+If you’d rather not manage env vars yourself, the onboarding wizard can store
+API keys for daemon use: `openclaw onboard`.
+
+See [Help](/help) for details on env inheritance (`env.shellEnv`,
+`~/.openclaw/.env`, systemd/launchd).
+
+## Anthropic: setup-token (subscription auth)
+
+For Anthropic, the recommended path is an **API key**. If you’re using a Claude
+subscription, the setup-token flow is also supported. Run it on the **gateway host**:
+
+```bash
+claude setup-token
+```
+
+Then paste it into OpenClaw:
+
+```bash
+openclaw models auth setup-token --provider anthropic
+```
+
+If the token was created on another machine, paste it manually:
+
+```bash
+openclaw models auth paste-token --provider anthropic
+```
+
+If you see an Anthropic error like:
+
+```
+This credential is only authorized for use with Claude Code and cannot be used for other API requests.
+```
+
+…use an Anthropic API key instead.
+
+Manual token entry (any provider; writes `auth-profiles.json` + updates config):
+
+```bash
+openclaw models auth paste-token --provider anthropic
+openclaw models auth paste-token --provider openrouter
+```
+
+Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
+
+```bash
+openclaw models status --check
+```
+
+Optional ops scripts (systemd/Termux) are documented here:
+[/automation/auth-monitoring](/automation/auth-monitoring)
+
+> `claude setup-token` requires an interactive TTY.
+
+## Checking model auth status
+
+```bash
+openclaw models status
+openclaw doctor
+```
+
+## Controlling which credential is used
+
+### Per-session (chat command)
+
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
+
+Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
+
+### Per-agent (CLI override)
+
+Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
+
+```bash
+openclaw models auth order get --provider anthropic
+openclaw models auth order set --provider anthropic anthropic:default
+openclaw models auth order clear --provider anthropic
+```
+
+Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
+
+## Troubleshooting
+
+### “No credentials found”
+
+If the Anthropic token profile is missing, run `claude setup-token` on the
+**gateway host**, then re-check:
+
+```bash
+openclaw models status
+```
+
+### Token expiring/expired
+
+Run `openclaw models status` to confirm which profile is expiring. If the profile
+is missing, rerun `claude setup-token` and paste the token again.
+
+## Requirements
+
+- Claude Max or Pro subscription (for `claude setup-token`)
+- Claude Code CLI installed (`claude` command available)

package/docs/gateway/background-process.md

@@ -0,0 +1,93 @@
+---
+summary: "Background exec execution and process management"
+read_when:
+  - Adding or modifying background exec behavior
+  - Debugging long-running exec tasks
+title: "Background Exec and Process Tool"
+---
+
+# Background Exec + Process Tool
+
+OpenClaw runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+
+## exec tool
+
+Key parameters:
+
+- `command` (required)
+- `yieldMs` (default 10000): auto‑background after this delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill the process after this timeout
+- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- Need a real TTY? Set `pty: true`.
+- `workdir`, `env`
+
+Behavior:
+
+- Foreground runs return output directly.
+- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
+- Output is kept in memory until the session is polled or cleared.
+- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
+
+## Child process bridging
+
+When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.
+
+Environment overrides:
+
+- `PI_BASH_YIELD_MS`: default yield (ms)
+- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
+- `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
+- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
+
+Config (preferred):
+
+- `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.timeoutSec` (default 1800)
+- `tools.exec.cleanupMs` (default 1800000)
+- `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
+
+## process tool
+
+Actions:
+
+- `list`: running + finished sessions
+- `poll`: drain new output for a session (also reports exit status)
+- `log`: read the aggregated output (supports `offset` + `limit`)
+- `write`: send stdin (`data`, optional `eof`)
+- `kill`: terminate a background session
+- `clear`: remove a finished session from memory
+- `remove`: kill if running, otherwise clear if finished
+
+Notes:
+
+- Only backgrounded sessions are listed/persisted in memory.
+- Sessions are lost on process restart (no disk persistence).
+- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
+- `process` is scoped per agent; it only sees sessions started by that agent.
+- `process list` includes a derived `name` (command verb + target) for quick scans.
+- `process log` uses line-based `offset`/`limit` (omit `offset` to grab the last N lines).
+
+## Examples
+
+Run a long task and poll later:
+
+```json
+{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
+```
+
+```json
+{ "tool": "process", "action": "poll", "sessionId": "<id>" }
+```
+
+Start immediately in background:
+
+```json
+{ "tool": "exec", "command": "npm run build", "background": true }
+```
+
+Send stdin:
+
+```json
+{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
+```

package/docs/gateway/bonjour.md

@@ -0,0 +1,167 @@
+---
+summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
+read_when:
+  - Debugging Bonjour discovery issues on macOS/iOS
+  - Changing mDNS service types, TXT records, or discovery UX
+title: "Bonjour Discovery"
+---
+
+# Bonjour / mDNS discovery
+
+OpenClaw uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover
+an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or
+Tailnet-based connectivity.
+
+## Wide‑area Bonjour (Unicast DNS‑SD) over Tailscale
+
+If the node and gateway are on different networks, multicast mDNS won’t cross the
+boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD**
+("Wide‑Area Bonjour") over Tailscale.
+
+High‑level steps:
+
+1. Run a DNS server on the gateway host (reachable over Tailnet).
+2. Publish DNS‑SD records for `_openclaw-gw._tcp` under a dedicated zone
+   (example: `openclaw.internal.`).
+3. Configure Tailscale **split DNS** so your chosen domain resolves via that
+   DNS server for clients (including iOS).
+
+OpenClaw supports any discovery domain; `openclaw.internal.` is just an example.
+iOS/Android nodes browse both `local.` and your configured wide‑area domain.
+
+### Gateway config (recommended)
+
+```json5
+{
+  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
+  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
+}
+```
+
+### One‑time DNS server setup (gateway host)
+
+```bash
+openclaw dns setup --apply
+```
+
+This installs CoreDNS and configures it to:
+
+- listen on port 53 only on the gateway’s Tailscale interfaces
+- serve your chosen domain (example: `openclaw.internal.`) from `~/.openclaw/dns/<domain>.db`
+
+Validate from a tailnet‑connected machine:
+
+```bash
+dns-sd -B _openclaw-gw._tcp openclaw.internal.
+dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
+```
+
+### Tailscale DNS settings
+
+In the Tailscale admin console:
+
+- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
+- Add split DNS so your discovery domain uses that nameserver.
+
+Once clients accept tailnet DNS, iOS nodes can browse
+`_openclaw-gw._tcp` in your discovery domain without multicast.
+
+### Gateway listener security (recommended)
+
+The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tailnet
+access, bind explicitly and keep auth enabled.
+
+For tailnet‑only setups:
+
+- Set `gateway.bind: "tailnet"` in `~/.openclaw/openclaw.json`.
+- Restart the Gateway (or restart the macOS menubar app).
+
+## What advertises
+
+Only the Gateway advertises `_openclaw-gw._tcp`.
+
+## Service types
+
+- `_openclaw-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
+
+## TXT keys (non‑secret hints)
+
+The Gateway advertises small non‑secret hints to make UI flows convenient:
+
+- `role=gateway`
+- `displayName=<friendly name>`
+- `lanHost=<hostname>.local`
+- `gatewayPort=<port>` (Gateway WS + HTTP)
+- `gatewayTls=1` (only when TLS is enabled)
+- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
+- `canvasPort=<port>` (only when the canvas host is enabled; default `18793`)
+- `sshPort=<port>` (defaults to 22 when not overridden)
+- `transport=gateway`
+- `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint)
+- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
+
+## Debugging on macOS
+
+Useful built‑in tools:
+
+- Browse instances:
+  ```bash
+  dns-sd -B _openclaw-gw._tcp local.
+  ```
+- Resolve one instance (replace `<instance>`):
+  ```bash
+  dns-sd -L "<instance>" _openclaw-gw._tcp local.
+  ```
+
+If browsing works but resolving fails, you’re usually hitting a LAN policy or
+mDNS resolver issue.
+
+## Debugging in Gateway logs
+
+The Gateway writes a rolling log file (printed on startup as
+`gateway log file: ...`). Look for `bonjour:` lines, especially:
+
+- `bonjour: advertise failed ...`
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service ...`
+
+## Debugging on iOS node
+
+The iOS node uses `NWBrowser` to discover `_openclaw-gw._tcp`.
+
+To capture logs:
+
+- Settings → Gateway → Advanced → **Discovery Debug Logs**
+- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**
+
+The log includes browser state transitions and result‑set changes.
+
+## Common failure modes
+
+- **Bonjour doesn’t cross networks**: use Tailnet or SSH.
+- **Multicast blocked**: some Wi‑Fi networks disable mDNS.
+- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
+- **Browse works but resolve fails**: keep machine names simple (avoid emojis or
+  punctuation), then restart the Gateway. The service instance name derives from
+  the host name, so overly complex names can confuse some resolvers.
+
+## Escaped instance names (`\032`)
+
+Bonjour/DNS‑SD often escapes bytes in service instance names as decimal `\DDD`
+sequences (e.g. spaces become `\032`).
+
+- This is normal at the protocol level.
+- UIs should decode for display (iOS uses `BonjourEscapes.decode`).
+
+## Disabling / configuration
+
+- `OPENCLAW_DISABLE_BONJOUR=1` disables advertising (legacy: `OPENCLAW_DISABLE_BONJOUR`).
+- `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
+- `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (legacy: `OPENCLAW_SSH_PORT`).
+- `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT (legacy: `OPENCLAW_TAILNET_DNS`).
+- `OPENCLAW_CLI_PATH` overrides the advertised CLI path (legacy: `OPENCLAW_CLI_PATH`).
+
+## Related docs
+
+- Discovery policy and transport selection: [Discovery](/gateway/discovery)
+- Node pairing + approvals: [Gateway pairing](/gateway/pairing)

package/docs/gateway/bridge-protocol.md

@@ -0,0 +1,89 @@
+---
+summary: "Bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
+read_when:
+  - Building or debugging node clients (iOS/Android/macOS node mode)
+  - Investigating pairing or bridge auth failures
+  - Auditing the node surface exposed by the gateway
+title: "Bridge Protocol"
+---
+
+# Bridge protocol (legacy node transport)
+
+The Bridge protocol is a **legacy** node transport (TCP JSONL). New node clients
+should use the unified Gateway WebSocket protocol instead.
+
+If you are building an operator or node client, use the
+[Gateway protocol](/gateway/protocol).
+
+**Note:** Current OpenClaw builds no longer ship the TCP bridge listener; this document is kept for historical reference.
+Legacy `bridge.*` config keys are no longer part of the config schema.
+
+## Why we have both
+
+- **Security boundary**: the bridge exposes a small allowlist instead of the
+  full gateway API surface.
+- **Pairing + node identity**: node admission is owned by the gateway and tied
+  to a per-node token.
+- **Discovery UX**: nodes can discover gateways via Bonjour on LAN, or connect
+  directly over a tailnet.
+- **Loopback WS**: the full WS control plane stays local unless tunneled via SSH.
+
+## Transport
+
+- TCP, one JSON object per line (JSONL).
+- Optional TLS (when `bridge.tls.enabled` is true).
+- Legacy default listener port was `18790` (current builds do not start a TCP bridge).
+
+When TLS is enabled, discovery TXT records include `bridgeTls=1` plus
+`bridgeTlsSha256` so nodes can pin the certificate.
+
+## Handshake + pairing
+
+1. Client sends `hello` with node metadata + token (if already paired).
+2. If not paired, gateway replies `error` (`NOT_PAIRED`/`UNAUTHORIZED`).
+3. Client sends `pair-request`.
+4. Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
+
+`hello-ok` returns `serverName` and may include `canvasHostUrl`.
+
+## Frames
+
+Client → Gateway:
+
+- `req` / `res`: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
+- `event`: node signals (voice transcript, agent request, chat subscribe, exec lifecycle)
+
+Gateway → Client:
+
+- `invoke` / `invoke-res`: node commands (`canvas.*`, `camera.*`, `screen.record`,
+  `location.get`, `sms.send`)
+- `event`: chat updates for subscribed sessions
+- `ping` / `pong`: keepalive
+
+Legacy allowlist enforcement lived in `src/gateway/server-bridge.ts` (removed).
+
+## Exec lifecycle events
+
+Nodes can emit `exec.finished` or `exec.denied` events to surface system.run activity.
+These are mapped to system events in the gateway. (Legacy nodes may still emit `exec.started`.)
+
+Payload fields (all optional unless noted):
+
+- `sessionKey` (required): agent session to receive the system event.
+- `runId`: unique exec id for grouping.
+- `command`: raw or formatted command string.
+- `exitCode`, `timedOut`, `success`, `output`: completion details (finished only).
+- `reason`: denial reason (denied only).
+
+## Tailnet usage
+
+- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
+  `~/.openclaw/openclaw.json`.
+- Clients connect via MagicDNS name or tailnet IP.
+- Bonjour does **not** cross networks; use manual host/port or wide-area DNS‑SD
+  when needed.
+
+## Versioning
+
+Bridge is currently **implicit v1** (no min/max negotiation). Backward‑compat
+is expected; add a bridge protocol version field before any breaking changes.