- If `~/.coderclaw/coderclaw.json` exists, choose Keep, Modify, or Reset.
- Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
- If config is invalid or contains legacy keys, the wizard stops and asks you to run `coderclaw doctor` before continuing.
- Reset uses `trash` and offers scopes:
- Config only
- Config + credentials + sessions
- Full reset (also removes workspace)
- Full option matrix is in [Auth and model options](#auth-and-model-options).
- Default `~/.coderclaw/workspace` (configurable).
- Seeds workspace files needed for first-run bootstrap ritual.
- Workspace layout: [Agent workspace](/concepts/agent-workspace).
- Prompts for port, bind, auth mode, and tailscale exposure.
- Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
- Disable auth only if you fully trust every local process.
- Non-loopback binds still require auth.
- [WhatsApp](/channels/whatsapp): optional QR login
- [Telegram](/channels/telegram): bot token
- [Discord](/channels/discord): bot token
- [Google Chat](/channels/googlechat): service account JSON + webhook audience
- [Mattermost](/channels/mattermost) plugin: bot token + base URL
- [Signal](/channels/signal): optional `signal-cli` install + account config
- [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook
- [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access
- DM security: default is pairing. First DM sends a code; approve via
`coderclaw pairing approve ` or use allowlists.
- 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.
- 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.
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).
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`)
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.
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/<accountId>/.
Sessions are stored under ~/.coderclaw/agents/<agentId>/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/<version>/
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
