This page is the full reference for coderclaw onboard.
For the short guide, see Onboarding Wizard (CLI).
Local mode (default) walks you through:
Remote mode configures this machine to connect to a gateway elsewhere. It does not install or modify anything on the remote host.
` or use allowlists.
</Step>
- macOS: LaunchAgent
- Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
- Linux and Windows via WSL2: systemd user unit
- Wizard attempts `loginctl enable-linger ` so gateway stays up after logout.
- May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
- Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
</Step>
- Starts gateway (if needed) and runs `coderclaw health`.
- `coderclaw status --deep` adds gateway health probes to status output.
- Reads available skills and checks requirements.
- Lets you choose node manager: npm or pnpm (bun not recommended).
- Installs optional dependencies (some use Homebrew on macOS).
- Summary and next steps, including iOS, Android, and macOS app options.
</Steps>
If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
## Remote mode details
Remote mode configures this machine to connect to a gateway elsewhere.
Remote mode does not install or modify anything on the remote host.
What you set:
- Remote gateway URL (`ws://...`)
- Token if remote gateway auth is required (recommended)
- If gateway is loopback-only, use SSH tunneling or a tailnet.
- Discovery hints:
- macOS: Bonjour (`dns-sd`)
- Linux: Avahi (`avahi-browse`)
## Auth and model options
Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
- macOS: checks Keychain item "Claude Code-credentials"
- Linux and Windows: reuses `~/.claude/.credentials.json` if present
On macOS, choose "Always Allow" so launchd starts do not block.
Run `claude setup-token` on any machine, then paste the token.
You can name it; blank uses default.
If `~/.codex/auth.json` exists, the wizard can reuse it.
Browser flow; paste `code#state`.
Sets `agents.defaults.model` to `openai-codex/gpt-5.3-codex` when model is unset or `openai/*`.
Uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to
`~/.coderclaw/.env` so launchd can read it.
Sets `agents.defaults.model` to `openai/gpt-5.1-codex` when model is unset, `openai/*`, or `openai-codex/*`.
Prompts for `XAI_API_KEY` and configures xAI as a model provider.
Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`).
Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
Stores the key for you.
Prompts for `AI_GATEWAY_API_KEY`.
More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
Config is auto-written.
More detail: [MiniMax](/providers/minimax).
Prompts for `SYNTHETIC_API_KEY`.
More detail: [Synthetic](/providers/synthetic).
Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
Works with OpenAI-compatible and Anthropic-compatible endpoints.
Non-interactive flags:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
- `--custom-provider-id` (optional)
- `--custom-compatibility <openai|anthropic>` (optional; default `openai`)
Leaves auth unconfigured.
Model behavior:
- Pick default model from detected options, or enter provider and model manually.
- Wizard runs a model check and warns if the configured model is unknown or missing auth.
Credential and profile paths:
- OAuth credentials: `~/.coderclaw/credentials/oauth.json`
- Auth profiles (API keys + OAuth): `~/.coderclaw/agents//agent/auth-profiles.json`
Headless and server tip: complete OAuth on a machine with a browser, then copy
`~/.coderclaw/credentials/oauth.json` (or `$CODERCLAW_STATE_DIR/credentials/oauth.json`)
to the gateway host.
## Outputs and internals
Typical fields in `~/.coderclaw/coderclaw.json`:
- `agents.defaults.workspace`
- `agents.defaults.model` / `models.providers` (if Minimax chosen)
- `gateway.*` (mode, bind, auth, tailscale)
- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
- `skills.install.nodeManager`
- `wizard.lastRunAt`
- `wizard.lastRunVersion`
- `wizard.lastRunCommit`
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
`coderclaw agents add` writes `agents.list[]` and optional `bindings`.
WhatsApp credentials go under `~/.coderclaw/credentials/whatsapp//`.
Sessions are stored under `~/.coderclaw/agents//sessions/`.
Some channels are delivered as plugins. When selected during onboarding, the wizard
prompts to install the plugin (npm or local path) before channel configuration.
Gateway wizard RPC:
- `wizard.start`
- `wizard.next`
- `wizard.cancel`
- `wizard.status`
Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
Signal setup behavior:
- Downloads the appropriate release asset
- Stores it under `~/.coderclaw/tools/signal-cli//`
- Writes `channels.signal.cliPath` in config
- JVM builds require Java 21
- Native builds are used when available
- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
## Related docs
- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
- Command reference: [`coderclaw onboard`](/cli/onboard)