@hailwright/buyer — Hailwright for OpenClaw

Ask OpenClaw to look up Hailwright, set it up, and hire a voice wright for a restaurant reservation. The public alpha runs free scripted demos. Actual phone calls are an invited test pilot restricted to the offered restaurant. General restaurant bookings and real-dollar settlement are not enabled.

Conversational setup (0.3.8)

Requires OpenClaw 2026.9.8 or newer. Ask your agent:

Look up Hailwright and set it up to make a reservation at Le Reve in Brownsville, TX.

The agent can use OpenClaw's built-in plugins tool to search ClawHub and install @hailwright/buyer. Respect the owner's capability review. Supported conversations refresh tools after installation and continue the original job in the same chat. Keep the original restaurant and preferences through any host-required restart.

The normal pinned CLI install is:

openclaw plugins install clawhub:@hailwright/buyer@0.3.8 --accept-capabilities

The capability flag requires the owner's authorization. Alternatively, use the Apache-2.0 archive in the public setup guide. The private GitHub repositories are not needed to install this buyer. Machine-readable setup information: openclaw.json. Agent instructions: openclaw.md.

Start a reservation with hailwright_setup, for example:

{"intent":"real-call","restaurant_name":"Le Reve","restaurant_city":"Brownsville","restaurant_state":"TX"}

Include only details the human supplied in known_fields. Omit unspecified optional locations. Setup checks the actual restaurant before account creation or funding. Le Reve is not currently offered; that request stops with an honest availability blocker. Setup never silently changes the restaurant or substitutes a demo.

For an offered, admitted request, setup proves the buyer identity, creates/reuses the buyer-owned spending account, reuses shared name/contact facts, asks the missing reservation questions together, and obtains free test funds when details are complete. Resume setup with the same request and merged answers. It checks the actual balance and recovers uncertain funding without another drip. No login, operator credential, network selection or gas setup is required for the current consumer lanes.

For an explicitly requested sample, use intent:"demo" with a party size, an offset-bearing time window and a sample booking name. No spending account or funding is required. Follow the returned workflow into the free quote, scripted execution, evidence and private history. No restaurant is called, no actual reservation is made and no money moves.

Call and payment controls

The invited pilot uses Base Sepolia test USDC, which has no dollar value. Its quote holds 2.25 test settlement units: price 2.00 (wright net 1.98; settlement fee 0.02), plus keeper reserve 0.25. Setup prepares an account and test balance; it never quotes, funds escrow, starts a call or releases payment.

The native buyer approves the exact escrow funding/call request once. After execution, a separate native acknowledgement is required for release. A non-interactive CLI cannot approve a spend. Unknown evidence withholds; without a release ACK, the clock leads to refund. The judge is advisory. Evidence is disclosed-fallible data, not a booking guarantee.

The pinned verifier derives the order hash and receiver locally. The relay receives only fixed buyer signatures, never the spending-account key. Recover a lost reply through status; a restart is not permission to repeat a call or payment. The owner test completed a real consented call and test settlement; it does not establish unattended paid-public readiness.

No real-money funding connector is configured. Production must use a buyer-authorized funding source; an initial provider payment/identity confirmation may be required. Never request card numbers, bank passwords or private keys in chat.

Consumer installs expose nine tools. Operator followups and setup instructions are kept in a separate reference. Malformed or mixed-lane inputs fail before transport/approval. Explicit offsets preserve the requested local clock. Zod 4.4.3 is exactly pinned; signed inputs are not coerced.

Explicit operator configuration

The rest of this reference describes deliberately configured operator installations. Public consumers use conversational setup above and need none of these credentials.

Set these before starting the gateway (env is preferred; the same keys exist in the plugin config — see openclaw.plugin.json):

The plugin installs and enables with no config; missing secrets fail closed at first use, not at install time.

Tools

The bundled hailwright-buyer skill teaches the agent the requirement interview: a wright declares the minimum information it needs in its manifest; hailwright_requirements reads that declaration, pre-fills what the buyer profile already knows (booking name, callback number), and hands back the wright's own plain-language questions for what is missing — collected conversationally before any spend, since the wright cannot ask follow-up questions mid-job. The order path enforces it: a missing required field refuses the order (fail-closed), never a silent default.

The spending account

Hailwright orders are paid from a spending account the plugin manages for you. There is nothing to install or sign up for: the first hailwright_account call creates it and gives you an address; you add funds by transferring them to that address from another app or account you already use. The agent will offer to set this up the first time an order needs funds.

• Setup flow. Ask your agent to set up a Hailwright spending account (or let it offer). It calls hailwright_account and reports the account address, the current balance (when HAILWRIGHT_RPC_URL + HAILWRIGHT_SETTLEMENT_ASSET are configured), and the disclosures below. The call is idempotent — running it again just reports.
• Transfer in. Send funds to the reported address from any app that can transfer the settlement asset. The balance shows up on the next hailwright_account call.
• The ceiling. No single fund authorization, and no total of outstanding authorizations, may exceed HAILWRIGHT_HOT_ALLOWANCE_CEILING_USD (default $25). Violations are refused in code before any approval prompt, alongside a per-hour rate limit and a cooldown between authorizations. These plugin-side brakes bound accidents and injected requests; the hard bounds live on-chain in the escrow itself.
• Where the key lives — the honest disclosure. The account's signing key is a plain file in the plugin state directory (spending-account.json, owner-only permissions, separate from the plugin's order-signing identity). Whoever can read that file controls the funds: treat the machine as the account. There is no recovery copy and no backup phrase — if the file is lost, the remaining balance is unrecoverable. That is exactly why the ceiling exists: keep the balance near what you actually plan to spend, and never store more than you are willing to lose.
• What automation can and cannot sign (the firewall). The plugin's automated path can produce only two kinds of signature with this account: a fund authorization (money into the escrow for an order you approved) and a withhold (a dispute that stops a release — it can only ever send funds back to you). A release signature — the one that pays the supplier — can only be produced on the human-present acknowledgement path, behind the same approval gate as every order, and the signing module exposes no general-purpose signing function that could be repurposed. Automation can stop money or return money on its own; it can never send money to a supplier on its own.

Adding funds

hailwright_fund covers both funding paths, and neither moves real money through Hailwright:

• Try Hailwright at no cost (test network). hailwright_fund with testnet: true asks Hailwright's test dispenser to drip test-network settlement funds to the account and confirms the balance on-chain — zero human steps. This is enabled only when HW_DISPENSER_URL is set and only on a test network (a non-test HAILWRIGHT_CHAIN_ID is refused fail-closed). The recommended first run is hailwright_account → hailwright_fund testnet → place a test order.
• Real funds. hailwright_fund (default) returns the account address plus one-step instructions for the human to transfer funds in from an app they already use. That single approval is the only human step; the funds move from the human's account to the escrowed payment or the supplier, never through Hailwright.

The wallet command (developer/terminal)

For trying the flow from a shell (the same three steps as one command each), the package ships a wallet bin over the same key store and dispenser client:

wallet init                 # create the local spending account (both keys, chmod 600, outside any git repo)
wallet status               # address · network · balance · key files + permissions
HW_DISPENSER_URL=… wallet fund --testnet   # drip test funds and confirm on-chain
wallet fund                 # print one-step guided real-money funding

wallet init refuses to overwrite an existing account without --force, and keys default to $HOME/.hailwright/buyer (override with --dir or HAILWRIGHT_WALLET_DIR) so a checkout never holds a private key. Output is JSON by default; add --human for a short readable form.

Money-path controls

• Human approval gate. hailwright_order and hailwright_ack are governed by a trusted tool policy (hailwright-spend-gate): approval prompt with the amount and supplier, allow-once/deny only, timeout denies, and an unreadable amount escalates rather than bypasses. There is no allow-always persistence.
• Both money calls are signed. The plugin holds its own Ed25519 key (persisted in plugin state, file mode 0600) and signs the complete request body of every order and every release acknowledgement — domain-separated (hailwright-order-v1|), with a signed intent field (an order signature can never authorize a release), a single-use nonce, and a 5-minute expiry.
• Per-session budget ceiling on escrowed spend, on top of per-order approval.
• Authenticated callbacks. Inbound settlement callbacks are verified with a constant-time HMAC-SHA256 check against your per-buyer secret before they can wake a session.
• Server is the schema authority. The plugin never constructs the order envelope; it sends your intent with a versioned API header and lets the server compile the order. Order state lives on the server, not in the transcript.

What it does not do

• Outcome records are disclosed-fallible data — a record of the work, not a guarantee.
• No live mid-call interaction with a wright; the callback/poll machinery handles between-turn asynchrony only.
• The allowance ledger persists across gateway restarts. Per-session budgets remain tied to the active session; escrow bounds remain authoritative on-chain.
• Discovery uses the public synthetic catalog in the preset, the live venue when configured, or the legacy pinned-manifest fallback.
• Like any OpenClaw plugin, it runs in-process with the gateway's own privileges.

Development

npm install
npm run typecheck   # tsc --noEmit (strict)
npm test            # unit tests (tool clients, spend gate, callback HMAC, identity, scheduler)
npm run build       # emit dist/ (optional; OpenClaw loads the TypeScript entry directly)