hanzoai/bot
2
0
Fork 0
mirror of https://github.com/hanzoai/bot.git synced 2026-10-30 17:24:26 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
fix/ci-test-failures
bot/docs/start/wizard.md
T
zooqueenandHanzo Dev f38eb8d141 feat(secrets): expand onboarding secret-ref flows and custom-provider parity 
Cherry-pick upstream 16a9fdc89 with conflict resolution:
- Add isSecretRef type guard to types.secrets.ts
- Add ApiKeyStorageOptions to onboard-auth.credentials.ts
- Add provider field to SecretRef constructions in apply-helpers
- Fix max_tokens for verification probes (5/16 → 1024)
- Fix timeout test to match 30s verify timeout
- Fix writeOAuthCredentials to return profileId
- Fix branding (OpenClaw → Bot) in apply-helpers and docs
- Add withEnvAsync import to provider-auth tests

Co-authored-by: Hanzo Dev <[email protected]>
2026-03-01 11:18:41 -08:00

4.3 KiB
Raw Permalink Blame History

summary, read_when, title, sidebarTitle
summary read_when title sidebarTitle
CLI onboarding wizard: guided setup for gateway, workspace, channels, and skills
Running or configuring the onboarding wizard
Setting up a new machine
Onboarding Wizard (CLI) Onboarding: CLI

Onboarding Wizard (CLI)

The onboarding wizard is the recommended way to set up Hanzo Bot on macOS, Linux, or Windows (via WSL2; strongly recommended). It configures a local Gateway or a remote Gateway connection, plus channels, skills, and workspace defaults in one guided flow.

hanzo-bot onboard
Fastest first chat: open the Control UI (no channel setup needed). Run `hanzo-bot dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).

To reconfigure later:

hanzo-bot configure
hanzo-bot agents add <name>
`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`. Recommended: set up a Brave Search API key so the agent can use `web_search` (`web_fetch` works without a key). Easiest path: `hanzo-bot configure --section web` which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web).

QuickStart vs Advanced

The wizard starts with QuickStart (defaults) vs Advanced (full control).

- Local gateway (loopback) - Workspace default (or existing workspace) - Gateway port **18789** - Gateway auth **Token** (auto‑generated, even on loopback) - Tailscale exposure **Off** - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number) - Exposes every step (mode, workspace, gateway, channels, daemon, skills).

What the wizard configures

Local mode (default) walks you through these steps:

  1. Model/Auth — Anthropic API key (recommended), OpenAI, or Custom Provider (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model. For non-interactive runs, --secret-input-mode ref stores env-backed refs in auth profiles instead of plaintext API key values. In non-interactive ref mode, the provider env var must be set; passing inline key flags without that env var fails fast. In interactive runs, choosing secret reference mode lets you point at either an environment variable or an encrypted sops file pointer, with a fast preflight validation before saving.
  2. Workspace — Location for agent files (default ~/.hanzo/bot/workspace). Seeds bootstrap files.
  3. Gateway — Port, bind address, auth mode, Tailscale exposure.
  4. Channels — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.
  5. Daemon — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
  6. Health check — Starts the Gateway and verifies it's running.
  7. Skills — Installs recommended skills and optional dependencies.
Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`). If the config is invalid or contains legacy keys, the wizard asks you to run `hanzo-bot doctor` first.

Remote mode only configures the local client to connect to a Gateway elsewhere. It does not install or change anything on the remote host.

Add another agent

Use hanzo-bot agents add <name> to create a separate agent with its own workspace, sessions, and auth profiles. Running without --workspace launches the wizard.

What it sets:

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

Notes:

  • Default workspaces follow ~/.hanzo/bot/workspace-<agentId>.
  • Add bindings to route inbound messages (the wizard can do this).
  • Non-interactive flags: --model, --agent-dir, --bind, --non-interactive.

Full reference

For detailed step-by-step breakdowns, non-interactive scripting, Signal setup, RPC API, and a full list of config fields the wizard writes, see the Wizard Reference.

Related docs

Reference in New Issue View Git Blame Copy Permalink