8cd38b03ce
## What Problem This Solves
Connects supported installed OpenCode, Qwen Code, Pi, and Kilo Code agents to Models settings, setup, the shared model picker, and chat. Each CLI owns its sign-in; this does not discover every arbitrary ACP-compatible executable.
## User Impact
- Enabling an installed agent finishes at the configuration acknowledgement, without waiting for model discovery.
- Native model choices survive reload. Disabling an agent stops new discovery and turns without interrupting admitted work or deleting history.
- When optional chat restrictions cannot be enforced, an administrator can explicitly choose **Continue for this chat** to use the native app's permissions. Required sandboxing and other mandatory boundaries remain enforced; agent and global defaults do not change.
- Continue retries the original refused message and attachments once. A newer draft is preserved rather than sent under an earlier confirmation. Native assistant output streams before the final response.
- Explicit permission and sandbox preferences survive same-chat resets and expiry. Native consent remains incarnation-bound and is retired on reset, fork, runtime change, or stronger settings.
- Empty native discovery does not remove unrelated API models or trigger false model-fact changes, including repeated empty reads.
## Why This Change Was Made
OpenClaw owns model selection, consent, transcripts, session lifecycle, and run authority. ACPX owns transport, model inspection, session-scoped client permissions, and final prompt admission. This consumes upstream ACPX [#622](https://github.com/openclaw/acpx/pull/622), [#623](https://github.com/openclaw/acpx/pull/623), and [#624](https://github.com/openclaw/acpx/pull/624), rather than maintaining private enforcement wrappers in OpenClaw.
Both dependencies now use published **acpx 0.17.1**. The temporary Git-source pin and source-build approval are removed. Exact, dated dependency cooldown exclusions remain; installer integrity checks and script-disabled managed installation are unchanged.
The final reconciliation keeps catalog requests with the existing catalog schema owner, removes an unused type facade, and preserves native observation identity at the merge producer. Native policy calculation lives in the existing execution-policy module instead of importing the full agent runner during preflight. Runtime availability, implicit fallback, and explicit native pins stay with the execution selector; chat preflight checks only the known host-only runtime's permission restrictions. Tests exercise real catalog invalidation rather than retired UI wording or private metadata.
## Evidence
- **Published-driver upgrade:** the actual npm `openclaw@2026.9.4` updater installed the standard candidate package. Staging, migration rehearsal/continuation, canary, swap, and Doctor succeeded. The existing session retained its ID, model, runtime, workspace, label, and permissions. Restart was explicit after `update --no-restart`; automatic OS-service restart is not claimed.
- **Managed plugin and native continuity:** the unchanged candidate plugin archive installed through the repository's canonical local prepublish npm registry fixture with normal official-package provenance. Its ACPX dependency matched public npm 0.17.1, and its SDK resolved the installed candidate core—not the source checkout. A native conversation continued across a real Gateway process restart. Reset cleared consent; a stale lifecycle grant was rejected without peer effects; fresh explicit consent restored execution. The peer was a deterministic ACP subprocess, not paid-provider inference. The candidate OpenClaw plugin itself is not publicly released.
- **Telegram Test Server:** six real-user sends and two callback selections produced native-runtime confirmation edits. Four persisted snapshots verified native provider/model/runtime selection, `/reset` retention, restart retention, and unchanged agent defaults. Zero inference requests. The unchanged QA runner used Bun after a host Node/Undici error; the product Gateway used Node and the built candidate. Leases, credentials, processes, and listeners were cleaned up.
- **Real provider:** OpenCode through ACPX 0.17.1 returned the requested exact smoke response using `opencode/big-pickle`, an isolated HOME, and no API-key environment variables.
- **Real UI/Gateway:** a synthetic ACP subprocess refused the first message under Read Only, automatically retried it after confirmation, and streamed assistant chunks while its final response was still held. The recording contains one session creation and one automatic `chat.send`. [Inspected before/after screenshots](https://github.com/openclaw/openclaw/pull/150224#issuecomment-5748103787) are embedded in the PR discussion and originating chat; [earlier consent/retry captures](https://github.com/openclaw/openclaw/pull/150224#issuecomment-5743925304) remain available.
- **Regression proof:** repeated empty native discovery failed before the producer fix: captured API rows disappeared, and configured API rows emitted false invalidations. Both cases pass after repair. A successful empty provider refresh still removes its own obsolete rows; native cancellation, final-prompt authority, and API/native route separation remain covered.
- **Lightweight preflight:** the existing lazy-handler regression reproduced a speech-runtime import during basic `chat.send` validation. Moving the shared policy implementation fixed it without changing policy decisions: all nine moved function bodies and denial-prompt initializers have identical tokens. The registered consent-refusal test, 25 native-process cases, 18 model-ownership cases, 168 harness-selection cases, and seven relocated pure policy cases passed. The seven policy cases were moved, not added; the oversized selection module no longer needs its old size exception.
- **Single availability owner:** hosted creation/recovery regressions exposed a duplicate availability check in chat preflight. Removing it restores inherited and recovered native selections without inventing fixture runtimes or changing stored pins. Four title/initial-send selection paths, tombstone recovery, and refusal before message persistence passed unchanged. Temporary core-runtime fixture pins were removed; execution still rejects unavailable explicit native ownership rather than silently switching to an API provider.
- **Focused checks:** more than 700 cases passed across the repair rounds, including registered native-process execution, Gateway creation/recovery/admission/compaction/queued Stop, protocol exports, plugin boundaries, catalog ownership, Telegram callbacks, and 12 browser scenarios. The policy-cutover tree passed a full build and core production/UI/core-test typechecks; the subsequent availability-owner correction passed focused execution, production types, and lint. Protocol generation/Swift/Kotlin checks, assertion safety, and runtime import-cycle checks passed. Startup JS measured 364,119 bytes gzip against the 364,774-byte limit. The complete protocol schema's serialized bytes stayed identical through its module relocation. Size exceptions were pruned, not relaxed.
Upgrade, Telegram, and UI recordings bind the compiled `99ecb40e5d` artifact. Later ACP changes affect empty catalog observations, schema placement, metadata-only policy loading, and test fixtures. Consent decisions and denial prompts are unchanged; native execution and pre-admission refusal were rechecked after the policy move. The final main merge also carries upstream update-service planning changes; retained upgrade proof still exercises the unchanged published 2026.9.4 driver with explicit no-restart, not a new automatic-service-restart claim. Historical observations are not relabeled as reruns of a later commit. Final exact-head review and hosted checks remain separate gates.
### Disclosed limits
- Direct local `npm-pack` installation imported successfully but correctly lacked official-plugin storage trust for native execution. The normal npm installation through the canonical prepublish registry fixture closed that execution gap without trust overrides.
- An optional custom `--bundle-plugin acpx` distribution failed Darwin staging in `fsevents@2.3.3` (`binding.gyp` missing). No flags or packaging code were weakened; the standard candidate installation remained intact. That custom-distribution route is not claimed green.
- Matching-backup restoration and a post-upgrade external MCP tool call were not exercised.
## Compatibility and intended permission contract
The maintainer-requested behavior is explicit administrator-only, per-chat delegation to the native app when optional restrictions cannot be enforced—not silent global relaxation or a second OpenClaw enforcement system. Mandatory boundaries, live run authority, and consent retirement remain required. The accompanying SDK additions use the existing harness, transcript, and turn-stream owners; existing silent transcript-write defaults remain unchanged.
The candidate plugin declares `compat.pluginApi: >=2026.9.5`; supported installation uses that SDK floor rather than relying on the older general install hint. The package proof upgraded the host before installing the candidate plugin.
Existing API-key setup and explicit ACP commands remain available. No database schema migration is introduced. No package release, operator Gateway redeployment, or OpenClaw merge is included in this preparation.
## Contributor context
Sandbox recovery and upstream-first integration requested by @obviyus. [Discussion, implementation and verification](https://team.openclaw.ai/chat/roboclaw/dashboard/c522995c-e4fe-471a-848e-0d8fc44edd5c).
Co-authored-by: Ayaan Zaidi <hi@obviy.us>
11 KiB
| summary | read_when | title | ||||
|---|---|---|---|---|---|---|
| CLI reference for `openclaw setup` (system-agent chat with onboarding fallback) |
|
Setup CLI |
openclaw setup
openclaw setup is the system-agent entry point. On a configured system, bare
openclaw setup opens an interactive OpenClaw chat. On a fresh system, it
falls through to guided onboarding. Use -m/--message for one request or
--baseline to initialize config/workspace folders without the wizard.
Routing order:
- Any onboarding option (
--wizard,--baseline, workspace, reset, non-interactive, flow, mode, Gateway, daemon, skip, import, remote, or auth options) runs onboarding exactly asopenclaw onboarddoes. -m/--messageor--yesruns the system agent.- With no routing option, a configured interactive system opens OpenClaw. A
fresh system runs onboarding. On a configured system,
--jsonprints the system overview even without a TTY; an onboarding option keeps onboarding's JSON summary.
In guided mode, --workspace <dir> is the workspace proposed to OpenClaw;
it is persisted only after you approve that proposal. Baseline, classic, and
noninteractive setup persist the supplied workspace through their normal flow
on a fresh install. When an existing agent roster would be remapped, the
classic wizard requires explicit confirmation; noninteractive setup keeps the
current fleet workspace and prints a warning.
Guided inference detection runs on the Gateway host on macOS or Linux. The CLI and macOS app call the same Gateway-owned detector, which checks configured models, supported CLI logins, API-key environment variables, and already installed Ollama or LM Studio models. Local models are never downloaded by this discovery pass. Both CLI onboarding and the macOS app wait for you to choose a connection before testing it. A failed or cancelled attempt never selects another provider automatically. Setup saves the credential, then sends one tool-free confirmation turn using the candidate settings in memory. It saves the provider and model configuration only after that turn succeeds. A failed connection keeps the credential and leaves the configuration unchanged. Choose the saved sign-in to retry without signing in again. Custom endpoint settings stay available for retry while the Gateway runs; after a restart, enter the endpoint settings again.
Initial Claude Code and Codex detection checks executable versions without running auth-status commands or starting an app server. Readable Codex credentials are reported as stored evidence; the active login remains unverified during detection. Stored credentials do not receive verified-subscription priority over environment API keys.
In the Control UI, Model Setup can also select models from installed native agents through the shared model picker. Use saves that model and its runtime without running the setup test; authentication and tools stay with the native agent. Provider Test & use still requires a verified tool-free reply. Gemini CLI and Antigravity are not offered as detected setup routes.
setup accepts the same onboarding flags as openclaw onboard, including
auth (--auth-choice, --token, provider key flags), Gateway
(--gateway-port, --gateway-bind, --gateway-auth, --install-daemon),
Tailscale (--tailscale), reset (--reset, --reset-scope), flow
(--flow quickstart|advanced|manual|import), and skip flags
(--skip-channels, --skip-skills, --skip-bootstrap, --skip-search,
--skip-health, --skip-ui, --skip-hooks). Pass --tui to use the same
terminal hatch as openclaw onboard --tui. See Onboard and
CLI automation for the full flag reference and
non-interactive examples. openclaw onboard --modern remains a compatibility
entry for the same inference-gated OpenClaw assistant.
Local onboarding generates a Gateway secret in token mode by default, without
asking you to choose token or password. Existing password-mode configs are
preserved. Use --gateway-auth password or --gateway-password <value> to
choose a password explicitly; Tailscale Funnel still requires password mode.
Use setup --team for the same small-team onboarding as onboard --team.
--agent-name <name> names the first agent or, with --team, the coordinator.
Options
| Flag | Description |
|---|---|
-m, --message <text> |
Run one OpenClaw request. |
--yes |
Approve persistent config writes for one --message request. |
--workspace <dir> |
Workspace proposal; existing fleets require classic confirmation and are preserved noninteractively. |
--baseline |
Create baseline config/workspace/session folders without onboarding. |
--wizard |
Force interactive onboarding. |
--classic |
Run the classic multi-step onboarding wizard; not valid with --non-interactive. |
--agent-name <name> |
Name for the first agent (default: main). |
--tui |
Use the terminal hatch instead of the browser handoff. |
--non-interactive |
Run onboarding without prompts. |
--accept-risk |
Acknowledge full-system agent access risk; required with --non-interactive. |
--mode <mode> |
Onboarding mode: local or remote. |
--flow <flow> |
Onboard flow: quickstart, advanced, manual, or import. |
--reset |
Reset config + credentials + sessions before onboarding (workspace only with --reset-scope full). |
--reset-scope <scope> |
Reset scope: config, config+creds+sessions, or full. |
--import-from <provider> |
Migration provider to run during onboarding. |
--import-source <path> |
Source agent home for --import-from. |
--import-secrets |
Import supported secrets during onboarding migration. |
--remote-url <url> |
Remote Gateway WebSocket URL. |
--remote-token <token> |
Remote Gateway token (optional). |
--remote-password <password> |
Remote Gateway password (optional). |
--json |
Configured system: OpenClaw overview. Onboarding route: onboarding summary. |
--classic and --non-interactive are mutually exclusive: classic opens the
prompted wizard, while noninteractive setup uses the automation path.
In interactive onboarding, --remote-url, --remote-token, and
--remote-password prefill the remote Gateway step and take precedence over
stored remote values for that run. Pass either a token or a password, not both.
Changing the URL does not reuse stored credentials unless you also provide a new
token or password. The interactive step asks for one Gateway secret and
stores it as gateway.remote.token; either field is accepted by the Gateway.
The credential remains masked and uses the wizard's selected
plaintext or SecretRef storage mode. --gateway-token, --gateway-token-ref-env,
and --gateway-password configure a local Gateway and are not valid in remote
mode. For remote token SecretRefs, set OPENCLAW_GATEWAY_TOKEN and use
--remote-token with --secret-input-mode ref.
Baseline mode
openclaw setup --baseline preserves the older baseline-only behavior: it
creates the config, workspace, and session directories, then exits without
running onboarding. It accepts --workspace and harmless output controls, but
rejects explicit onboarding, Gateway, auth, reset, or daemon options instead of
silently ignoring them. If an existing config is invalid, baseline setup preserves
it and asks you to run openclaw doctor --fix to apply supported repairs before retrying.
Examples
openclaw setup
openclaw setup -m "status"
openclaw setup -m "restart gateway" --yes
openclaw setup --json
openclaw setup --wizard
openclaw setup --baseline
openclaw setup --workspace ~/.openclaw/workspace
openclaw setup --import-from hermes --import-source ~/.hermes
openclaw setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
openclaw setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-password <password>
Notes
- Inside the interactive OpenClaw chat,
configure skills,configure web search, andconfigure gatewayrun hosted setup flows.open search wizardandopen gateway wizardhand credential entry to masked terminal wizards. Gateway setup is local-only and config-only; restart afterward withrestart gatewayin chat oropenclaw gateway restartin the terminal. Seeopenclaw setupoperations. import memorycopies detected local memory into the existing default agent workspace without importing config, credentials, or skills. Finish onboarding first; the chat reports partial and failed copies instead of assuming success.- After baseline setup, run
openclaw onboardfor the full guided journey,openclaw configurefor targeted changes, oropenclaw channels addto add channel accounts. - If Hermes state is detected, interactive onboarding can offer migration automatically. Import onboarding requires a fresh setup; use Migrate for dry-run plans, backups, and overwrite mode outside onboarding.