fix(onboarding): 3 fresh-install stalls — gateway.mode message, default agent, scope-rejection masking (draft)#74
Merged
Conversation
Two fresh-install onboarding stalls hit during a live local-model bring-up:
1. `gateway install` already auto-sets `gateway.mode=local` when it is unset
(it writes the config), but then printed "No gateway.mode found. Set
gateway.mode=local for managed gateway install." — an imperative that reads
like the operator still has to act. Operators then redundantly ran
`openclaw config set gateway.mode local` + restart. Message now states what
the code actually did (defaulted to local) and that no action is needed.
2. `openclaw agent -m "…"` with no --to/--agent/--session-* errored "No target
session selected" even on a fresh box where exactly one agent ("main")
exists. It now defaults to the sole configured agent (emitting a stderr
hint), and only errors when 0 or 2+ choices exist — where it now lists the
configured agents instead of just pointing at `agents list`.
Tests: install.test.ts message assertion updated; new agent-via-gateway case
locks the default-to-sole-agent behavior. 77/77 in the two affected suites,
tsc --noEmit clean, oxlint clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
…e rejection Third fresh-install onboarding stall from the same bring-up: when the CLI device holds operator.read but a turn needs operator.write, the gateway closes with "pairing required: device is asking for more scopes" — a transport-closed error. The fallback path treated ALL transport errors as embedded-fallback worthy, so it silently ran an embedded agent (which then picked a keyless openai/gpt-5.5 and died with a confusing auth error), masking the real authz problem. Now a pairing/scope close is detected (isGatewayPairingScopeError) and the CLI throws a clear, actionable error pointing at `openclaw devices approve --latest` instead of falling back. Does NOT auto-grant scopes (authz stays operator-gated). New regression test asserts the scope rejection throws the approve hint and does NOT invoke the embedded agent. agent-via-gateway suite 57/57; install 20/20. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
LightDriverCS
force-pushed
the
aurelius/onboarding-hardening
branch
from
June 17, 2026 22:01
f351b28 to
41d2767
Compare
LightDriverCS
changed the title
LightDriverCS
marked this pull request as ready for review
June 17, 2026 23:06
Agent-Aurelius
approved these changes
Jun 21, 2026
Agent-Aurelius
left a comment
Agent-Aurelius
left a comment
There was a problem hiding this comment.
Anvil auto-approval — verdict READY, non-code-owned. Approved under the dedicated Anvil reviewer identity.
Dependency GuardThis PR changes dependency-related files. Maintainers should confirm these changes are intentional. Changed files:
Maintainer follow-up:
|
Dependency graph changes notedThis PR includes dependency graph changes. The dependency guard is informational because the PR author is a repository admin or a member of
Security review is still recommended before merge when the dependency graph change is intentional. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Scope
Three fresh-install onboarding stalls observed during a live local-model bring-up (customer Mac mini, openclaw 2026.6.2). Each is small and self-contained.
The three fixes
gateway installmessage lied about its own behavior. Install already auto-setsgateway.mode=localwhen unset, then printed"No gateway.mode found. Set gateway.mode=local …"— an imperative that made operators redundantly runconfig set+ restart. New message states what the code did and that no action is needed.openclaw agenterrored with no target even when one agent exists.openclaw agent -m "…"(no--to/--agent/--session-*) threw "No target session selected" on a fresh box with exactly one agent (main). It now defaults to the sole configured agent (stderr hint), erroring only on 0/2+ (and listing the configured agents then).operator.readbut a turn needsoperator.write, the gateway closes with "pairing required: … more scopes". That transport-closed error was treated as embedded-fallback-worthy, so the CLI silently ran an embedded agent that picked a keylessopenai/gpt-5.5and died with a confusing auth error. Now a pairing/scope close throws a clear, actionable error pointing atopenclaw devices approve --latestand does not fall back. Does not auto-grant scopes — authz stays operator-gated.Touched surfaces
src/cli/daemon-cli/install.ts(+ test) — messagesrc/commands/agent-via-gateway.ts(+ test) — default-to-sole-agent;isGatewayPairingScopeError+ interceptUser-visible behavior
Clearer install output;
openclaw agent -m "…"works on a single-agent install; a scope-rejected turn tells you exactly how to fix it instead of failing on a phantom openai model. Multi-agent / explicit-target / normal-fallback behavior unchanged.Firebase / deploy impact
None — CLI-only.
Local gates
vitest runaffected suites — 78/78 (incl. 2 new regression tests: default-agent, scope-rejection-no-fallback)tsc --noEmit— clean on touched filesoxlint— clean (incl. preserve-caught-error: thrown scope error carries{ cause })Known follow-up (NOT in this PR — genuine design decision, deferred)
openai/gpt-5.5when only an Anthropic key is present. Auto-picking a per-provider default model non-interactively risks writing a wrong/deprecated model id — the provider plugin exposes a model list, not an authoritative single default (the wizard resolves this via an interactive picker). Correct fix = reuse the wizard's model selection at key-placement, or add an authoritative per-provider recommended-model source. With fix fix(memory-wiki): standardize page schema + repair pipeline #3 above, this now surfaces as a clear error rather than the old silent cascade.🤖 Generated with Claude Code