bot/docs/start/setup.md at dependabot/github_actions/actions/setup-python-7

Files

T

hanzo-dev 0fa6a33a93 Eradicate OpenClaw — resolve merge conflicts and finish the rebrand

Three coordinated things:

1. Resolve the committed upstream/main merge conflicts. 94 files were
   sitting with raw <<<<<<< HEAD ... >>>>>>> upstream/main blocks. Every
   conflict had HanzoBot/Bot on HEAD and OpenClaw on upstream. Resolved
   by keeping HEAD everywhere — 540 conflict blocks.

2. Rewrite remaining OpenClaw text refs.
     OPENCLAW   → HANZO_BOT
     OpenClaw   → HanzoBot          (PascalCase type identifiers)
     openclaw   → bot               (codebase convention — botToken,
                                    botUsername etc.; avoids invalid
                                    hyphenated JS identifiers)
     openclaw[_]/openclaw[A-Z] → bot[_]/bot[A-Z]   (compound)
     ai.openclaw.x → ai.hanzo.bot.x  (JVM package path)

3. Delete or rename openclaw-named file paths (116 of them). Dead
   duplicates with a Bot-named canonical from the partial migration:
   deleted. Otherwise renamed.
     ai/openclaw/**           → deleted (ai/hanzo/bot/** canonical)
     Sources/OpenClaw*/       → deleted (Sources/Bot* canonical)
     Tests/OpenClawIPCTests/  → deleted (Tests/BotIPCTests canonical)
     OpenClawKit/             → deleted (BotKit canonical)
     openclaw-tools.*.ts      → deleted (bot-tools.*.ts canonical)
     openclaw-root.ts etc.    → deleted (bot-root.ts canonical)
     types.openclaw.ts        → deleted (types.bot.ts canonical)
     extensions/*/openclaw.plugin.json → renamed hanzo-bot.plugin.json
     docs/start/openclaw.md   → renamed hanzo-bot.md (+ zh-CN)
     docs/assets/openclaw-*.png, whatsapp-openclaw*.jpg → deleted
     scripts/.../openclaw-*   → deleted (bot/hanzo-bot parallels)
     openclaw.mjs             → deleted (hanzo-bot.mjs is package.bin)

Then patched 65 broken JS/TS import strings where hanzo-bot had ended
up inside an import path ('./types.hanzo-bot.js' → './types.bot.js'
etc., since the on-disk filename uses the brand-neutral bot- prefix).

Pre-existing lint debt cleaned up to get oxlint --type-aware to 0/0:
removed the dead i18n test that referenced a path no longer existing;
defined the missing DIDConfig and WalletConfig types in types.base.ts
(they were imported but never declared); dropped unused imports;
collapsed redundant type assertion and a tautological meta.bot lookup
that the openclaw→bot rename made redundant.

The a2ui.bundle.js generated artifact is kept at its pre-rebrand
contents — it gets regenerated by 'pnpm canvas:a2ui:bundle' from
sources I cannot rebuild in this commit; the source side is clean.

Verified: 0 occurrences of openclaw (case-insensitive) in tree source
content, 0 file or directory paths with openclaw in the name; oxlint
--type-aware src test reports 0/0.

2026-05-11 17:56:29 -07:00

4.9 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Advanced setup and development workflows for HanzoBot

Setting up a new machine

You want “latest + greatest” without breaking your personal setup

Setup

If you are setting up for the first time, start with [Getting Started](/start/getting-started). For wizard details, see [Onboarding Wizard](/start/wizard).

Last updated: 2026-01-01

TL;DR

Tailoring lives outside the repo: ~/.hanzo-bot/workspace (workspace) + ~/.hanzo-bot/hanzo-bot.json (config).
Stable workflow: install the macOS app; let it run the bundled Gateway.
Bleeding edge workflow: run the Gateway yourself via pnpm gateway:watch, then let the macOS app attach in Local mode.

Prereqs (from source)

Node >=22
pnpm
Docker (optional; only for containerized setup/e2e — see Docker)

Tailoring strategy (so updates don’t hurt)

If you want “100% tailored to me” and easy updates, keep your customization in:

Config: ~/.hanzo-bot/hanzo-bot.json (JSON/JSON5-ish)
Workspace: ~/.hanzo-bot/workspace (skills, prompts, memories; make it a private git repo)

Bootstrap once:

hanzo-bot setup

From inside this repo, use the local CLI entry:

hanzo-bot setup

If you don’t have a global install yet, run it via pnpm hanzo-bot setup.

Run the Gateway from this repo

After pnpm build, you can run the packaged CLI directly:

node hanzo-bot.mjs gateway --port 18789 --verbose

Stable workflow (macOS app first)

Install + launch HanzoBot.app (menu bar).
Complete the onboarding/permissions checklist (TCC prompts).
Ensure Gateway is Local and running (the app manages it).
Link surfaces (example: WhatsApp):

hanzo-bot channels login

Sanity check:

hanzo-bot health

If onboarding is not available in your build:

Run hanzo-bot setup, then hanzo-bot channels login, then start the Gateway manually (hanzo-bot gateway).

Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.

0) (Optional) Run the macOS app from source too

If you also want the macOS app on the bleeding edge:

./scripts/restart-mac.sh

1) Start the dev Gateway

pnpm install
pnpm gateway:watch

gateway:watch runs the gateway in watch mode and reloads on TypeScript changes.

2) Point the macOS app at your running Gateway

In HanzoBot.app:

Connection Mode: Local The app will attach to the running gateway on the configured port.

3) Verify

In-app Gateway status should read “Using existing gateway …”
Or via CLI:

hanzo-bot health

Common footguns

Wrong port: Gateway WS defaults to ws://127.0.0.1:18789; keep app + CLI on the same port.
Where state lives:
- Credentials: ~/.hanzo-bot/credentials/
- Sessions: ~/.hanzo-bot/agents/<agentId>/sessions/
- Logs: /tmp/hanzo-bot/

Credential storage map

Use this when debugging auth or deciding what to back up:

WhatsApp: ~/.hanzo-bot/credentials/whatsapp/<accountId>/creds.json
Telegram bot token: config/env or channels.telegram.tokenFile
Discord bot token: config/env or SecretRef (env/file/exec providers)
Slack tokens: config/env (channels.slack.*)
Pairing allowlists:
- ~/.hanzo-bot/credentials/<channel>-allowFrom.json (default account)
- ~/.hanzo-bot/credentials/<channel>-<accountId>-allowFrom.json (non-default accounts)
Model auth profiles: ~/.hanzo-bot/agents/<agentId>/agent/auth-profiles.json
File-backed secrets payload (optional): ~/.hanzo-bot/secrets.json
Legacy OAuth import: ~/.hanzo-bot/credentials/oauth.json More detail: Security.

Updating (without wrecking your setup)

Keep ~/.hanzo-bot/workspace and ~/.hanzo-bot/ as “your stuff”; don’t put personal prompts/config into the hanzo-bot repo.
Updating source: git pull + pnpm install (when lockfile changed) + keep using pnpm gateway:watch.

Linux (systemd user service)

Linux installs use a systemd user service. By default, systemd stops user services on logout/idle, which kills the Gateway. Onboarding attempts to enable lingering for you (may prompt for sudo). If it’s still off, run:

sudo loginctl enable-linger $USER

For always-on or multi-user servers, consider a system service instead of a user service (no lingering needed). See Gateway runbook for the systemd notes.

Gateway runbook (flags, supervision, ports)
Gateway configuration (config schema + examples)
Discord and Telegram (reply tags + replyToMode settings)
HanzoBot assistant setup
macOS app (gateway lifecycle)

4.9 KiB Raw Permalink Blame History Unescape Escape