fix(agent): support explicit CLI session keys

[Kaspre]

Problem

openclaw agent can target an agent, --to, or --session-id, but it has no direct way to target a known session key. Operators and scripts that already have an exact stored key need to reverse-map through session ids or choose a less precise selector. PR #35241 tried to add this surface but appears abandoned; the CLI gap is still present.

Change and value

This adds --session-key <key> to openclaw agent and carries that selector through Gateway dispatch, local embedded runs, and embedded fallback. Agent-prefixed keys are accepted as exact keys; malformed agent: keys and --agent/key mismatches fail before dispatch.

Legacy bare-key behavior is kept predictable:

• With --agent, bare non-sentinel keys are scoped to that agent.
• Without --agent, bare non-sentinel keys are scoped to the configured default agent.
• Literal global and unknown remain unscoped when no --agent is provided, while store/fallback ownership uses the configured default agent.

Implementation

• Registers --session-key for openclaw agent and forwards it through CLI options.
• Normalizes and validates explicit keys before Gateway dispatch and local fallback.
• Reuses the same normalization in direct embedded agentCommand callers.
• Adds routing helper coverage for exact, bare, sentinel, default-agent, malformed, and mismatched keys.
• Updates the CLI and tool docs with the new option and scoping rules.

Verification

Local, after rebasing onto origin/main ba06376c79550e52bfb51008a0622bed4dc53637:

• timeout 180s node scripts/run-vitest.mjs run --config test/vitest/vitest.commands.config.ts src/commands/agent-via-gateway.test.ts src/commands/agent.test.ts - 52 tests passed
• timeout 180s node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/routing/session-key.test.ts - 70 tests passed
• timeout 180s node scripts/run-vitest.mjs run --config test/vitest/vitest.cli.config.ts src/cli/program/register.agent.test.ts - 15 tests passed
• timeout 120s node scripts/check-docs-mdx.mjs docs/cli/agent.md docs/tools/agent-send.md - passed
• timeout 120s /home/captain/openclaw-source/node_modules/.bin/oxfmt --check --threads=1 ... - passed on the 11 changed files
• git diff --check origin/main...HEAD - passed
• timeout 60s node --import tsx src/entry.ts agent --help - showed --session-key <key>
• timeout 60s node --import tsx src/entry.ts agent --message hi --session-key agent:main --json - rejected malformed agent: key before dispatch
• timeout 60s node --import tsx src/entry.ts agent --message hi --agent ops --session-key agent:main:incident-42 --json - rejected --agent/session-key mismatch before dispatch

Remote, exact pushed head 34c87c28a0736c1b782ad47a9df00ffcf0b395fd on GCP Crabbox Spot e2-standard-8, us-east1-b, Node v24.15.0, pnpm 11.0.8, base/merge-base ba06376c79550e52bfb51008a0622bed4dc53637:

• pnpm check:changed - passed
• node scripts/run-vitest.mjs run --config test/vitest/vitest.commands.config.ts src/commands/agent-via-gateway.test.ts src/commands/agent.test.ts - 52 tests passed
• node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/routing/session-key.test.ts - 70 tests passed
• node scripts/run-vitest.mjs run --config test/vitest/vitest.cli.config.ts src/cli/program/register.agent.test.ts - 15 tests passed
• node scripts/check-docs-mdx.mjs docs/cli/agent.md docs/tools/agent-send.md - passed

A broader pnpm test:changed attempt on GCP also passed 139 of 140 files before failing two unrelated src/gateway/server.preauth-hardening.test.ts handshake-timeout assertions. I reproduced the same two failures on a clean origin/main checkout, so I am treating that as inherited or environment-sensitive, not caused by this patch.

Real behavior proof

Behavior or issue addressed: openclaw agent now accepts an explicit --session-key selector, validates malformed or mismatched agent-prefixed keys before dispatch, and routes exact keys consistently through Gateway, embedded, and fallback paths.

Real environment tested: local PR-head worktree at 34c87c28a0736c1b782ad47a9df00ffcf0b395fd, rebased onto origin/main ba06376c79550e52bfb51008a0622bed4dc53637; remote GCP Crabbox Spot e2-standard-8 in us-east1-b, Node v24.15.0, pnpm 11.0.8, exact pushed head 34c87c28a0736c1b782ad47a9df00ffcf0b395fd.

Exact steps or command run after this patch: local focused Vitest/doc/format/CLI commands listed above; remote fresh-clone validation ran pnpm check:changed plus the focused command/routing/CLI tests and docs MDX check. The local CLI proof commands were:

timeout 60s node --import tsx src/entry.ts agent --help
timeout 60s node --import tsx src/entry.ts agent --message hi --session-key agent:main --json
timeout 60s node --import tsx src/entry.ts agent --message hi --agent ops --session-key agent:main:incident-42 --json

Evidence after fix: copied terminal output from the exact PR-head worktree shows the new option and the two pre-dispatch validation errors:

$ timeout 60s node --import tsx src/entry.ts agent --help
OpenClaw 2026.5.20 (34c87c2) - All your chats, one OpenClaw.

Usage: openclaw agent [options]

Run an agent turn via the Gateway (use --local for embedded)

Options:
  --agent <id>               Agent id (overrides routing bindings)
  --session-id <id>          Use an explicit session id
  --session-key <key>        Explicit session key (agent:<id>:<key>, or scoped
                             to --agent)
  -t, --to <number>          Recipient number in E.164 used to derive the
                             session key

Examples:
  openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"
    Target an exact session key.

$ timeout 60s node --import tsx src/entry.ts agent --message hi --session-key agent:main --json
Error: Invalid --session-key "agent:main". Agent-prefixed session keys must use agent:<agent-id>:<session-key>.

$ timeout 60s node --import tsx src/entry.ts agent --message hi --agent ops --session-key agent:main:incident-42 --json
Error: Agent id "ops" does not match session key agent "main".

Observed result after fix: the CLI exposes --session-key, accepts the documented exact-key syntax, and rejects malformed or mismatched agent-prefixed keys before dispatch. Existing --to, --session-id, --agent, delivery, model override, and fallback behavior remains covered by the focused command/routing/CLI test set and the remote pnpm check:changed run on the pushed head.

What was not tested: I did not dispatch a live provider-backed agent turn or send a real channel delivery message; the changed behavior here is the selector surface and pre-dispatch routing/validation path, so validation used CLI output plus dispatch/local/fallback tests to avoid sending a real model/channel request from CI.

[clawsweeper]

Codex review: passed.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
The PR adds openclaw agent --session-key, normalizes explicit session keys through Gateway and embedded agent execution, and updates docs, tests, and changelog.

Reproducibility: yes. Current main's openclaw agent registration and gateway CLI option type lack --session-key, while the Gateway agent protocol already accepts sessionKey; this is source-reproducible without executing the CLI.

PR rating
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Summary: Good PR with strong proof for a CLI routing change; patch quality looks mergeable, with maintainer-owned session-contract risk remaining.

Rank-up moves:

• Maintainers should explicitly accept or adjust the bare-key/default-agent and global/unknown scoping contract before merge.

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Real behavior proof
Sufficient (live_output): The PR body includes after-fix terminal output for the new flag and validation errors, plus exact-head remote Crabbox validation for changed checks and focused tests.

Risk before merge

• The PR intentionally changes how bare explicit keys and literal global/unknown are interpreted across CLI, Gateway fallback, and embedded execution; if maintainers want different scoping, existing direct embedded callers or new scripts could attach state to a different agent store/session than intended.

Maintainer options:

1. Accept the documented session-key contract (recommended)
   Merge or let automerge continue if maintainers agree that bare keys scope to the requested/default agent while unscoped global and unknown stay literal without --agent.
2. Request a semantics-only patch
   Pause only if maintainers want different precedence for bare keys, sentinel keys, or combined --session-id plus --session-key before this becomes the CLI contract.

Next step before merge
No repair lane is needed because there is no concrete blocking finding; exact-head automerge/checks plus maintainer acceptance of the session contract should gate merge.

Security
Cleared: No concrete security or supply-chain regression found; the diff adds a validated operator CLI selector and does not change dependencies, CI, permissions, secret handling, or external code execution.

Review details

Best possible solution:

Land the shared normalization/validation implementation after maintainers accept the documented session-key scoping contract, or request a narrow semantics-only adjustment before merge.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main's openclaw agent registration and gateway CLI option type lack --session-key, while the Gateway agent protocol already accepts sessionKey; this is source-reproducible without executing the CLI.

Is this the best way to solve the issue?

Yes, if maintainers accept the semantics. Reusing the existing Gateway field and centralizing legacy-key normalization in routing helpers is the narrow maintainable path; the only open question is the documented scoping policy.

Label justifications:

• P2: This is a normal-priority CLI/session-routing improvement with focused operator scripting value and limited blast radius.
• merge-risk: 🚨 session-state: The diff changes how explicit CLI session keys are normalized and routed through Gateway, embedded, and fallback execution paths.
• rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🦞 diamond lobster, patch quality is 🐚 platinum hermit, and Good PR with strong proof for a CLI routing change; patch quality looks mergeable, with maintainer-owned session-contract risk remaining.
• status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): The PR body includes after-fix terminal output for the new flag and validation errors, plus exact-head remote Crabbox validation for changed checks and focused tests.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal output for the new flag and validation errors, plus exact-head remote Crabbox validation for changed checks and focused tests.

What I checked:

• Current main CLI gap: Current main registers openclaw agent options for --to, --session-id, and --agent, but not --session-key. (src/cli/program/register.agent.ts:69, b8e9ab9385c0)
• Current main dispatch gap: Current main's CLI gateway option type and target guard do not accept sessionKey, so operators cannot select an exact stored key through this command path. (src/commands/agent-via-gateway.ts:45, b8e9ab9385c0)
• Existing Gateway contract: The Gateway agent protocol already accepts an optional sessionKey, so the PR is plumbing an existing backend contract into the CLI rather than inventing a new Gateway field. (src/gateway/protocol/schema/agent.ts:163, b8e9ab9385c0)
• PR normalization and validation: The PR validates malformed agent: keys, rejects --agent/key mismatches, scopes legacy bare keys, and forwards the resolved key into Gateway params. (src/commands/agent-via-gateway.ts:124, 2c76dd339f5f)
• Embedded path alignment: The PR applies the same explicit-key normalization and validation in direct embedded agentCommand execution before resolving the session. (src/agents/agent-command.ts:323, 2c76dd339f5f)
• Shared routing helper: The PR adds isUnscopedSessionKeySentinel and scopeLegacySessionKeyToAgent, keeping the new key-shape policy centralized in routing helpers. (src/routing/session-key.ts:134, 2c76dd339f5f)

Likely related people:

• martingarramon: git blame attributes the current CLI registration, Gateway dispatch, session resolution, and routing-helper baseline lines to commit 7f4462e, which is the main provenance available for these paths in this checkout. (role: recent area contributor; confidence: medium; commits: 7f4462e5c06d; files: src/cli/program/register.agent.ts, src/commands/agent-via-gateway.ts, src/agents/command/session.ts)
• steipete: git log shows cabb553 as a recent commit touching the central agent/session-related path set with session entry workflow helper work. (role: recent adjacent session API contributor; confidence: medium; commits: cabb55380f84; files: src/agents/command/session.ts, src/routing/session-key.ts)
• joshavant: git log shows b8e9ab9 as a recent current-main commit touching the inspected agent path set, making this a plausible routing candidate for nearby agent/session behavior. (role: recent adjacent agent contributor; confidence: medium; commits: b8e9ab9385c0; files: src/agents/agent-command.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against b8e9ab9385c0.

[clawsweeper]

ClawSweeper PR egg

✨ Hatched: 🥚 common Gilded Clawlet

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

• Merged PRs are hatchable.
• Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
• Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: sniffs out flaky tests.
Image traits: location flaky test forest; accessory proof snapshot camera; palette cobalt, lime, and pearl; mood sleepy but ready; pose standing beside its cracked shell; shell starlit enamel shell; lighting bright celebratory glints; background delicate sparkle particles.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Gilded Clawlet in ClawSweeper.

What is this egg doing here?

• Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
• The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
• Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
• The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
• Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

[Kaspre]

@clawsweeper re-run

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26263654572
• Updated: 2026-05-22T01:53:33.969Z

[Takhoffman]

@clawsweeper automerge

[clawsweeper]

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=2c76dd339f5f83a07877134dc553c0338a31691d)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-05-22T03:08:26Z
Merge commit: eb7f3b7b50c5

What merged:

• The PR adds openclaw agent --session-key, normalizes explicit session keys through Gateway and embedded agent execution, and updates docs, tests, and changelog.
• Reproducibility: yes. Current main's openclaw agent registration and gateway CLI option type lack --sessi ... Gateway agent protocol already accepts sessionKey`; this is source-reproducible without executing the CLI.

Automerge notes:

• PR branch already contained follow-up commit before automerge: fix(agent): support explicit CLI session keys

The automerge loop is complete.

Automerge progress:

• 2026-05-22 02:33:47 UTC review queued 34c87c28a073 (queued)

• 2026-05-22 02:36:24 UTC repair queued 34c87c28a073 (autonomous) Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963

• 2026-05-22 02:39:16 UTC repair started (running) in 1s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 automerge-openclaw-openclaw-85121

• 2026-05-22 02:39:32 UTC validation plan (passed) in 16s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 pnpm check:changed; pnpm lint; pnpm check:test-types

• 2026-05-22 02:39:50 UTC Codex write preflight (passed) in 34s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 danger-full-access

• 2026-05-22 02:47:28 UTC Codex edit 1 c9029ddec497 (complete) in 8m 13s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 exit 0

• 2026-05-22 02:50:53 UTC validation and review 1 2c76dd339f5f (complete) in 11m 38s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 already-current

• 2026-05-22 02:51:00 UTC repair completed 2c76dd339f5f (branch updated) in 11m 44s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 initial automerge rebase is delegated to Codex repair

• 2026-05-22 02:50:59 UTC review queued 2c76dd339f5f (after repair)

• 2026-05-22 02:59:12 UTC automerge wait 2c76dd339f5f (ready) in 19m 56s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 checks and exact-head review are ready

• 2026-05-22 03:08:08 UTC review passed 2c76dd339f5f (structured ClawSweeper verdict: pass (sha=2c76dd339f5f83a07877134dc553c0338a316...)

• 2026-05-22 02:59:14 UTC repair finished 2c76dd339f5f (pushed) in 19m 58s Run: https://github.com/openclaw/clawsweeper/actions/runs/26265158963 repair_contributor_branch

• 2026-05-22 03:00:51 UTC review queued 2c76dd339f5f (queued)

• 2026-05-22 03:08:29 UTC merged 2c76dd339f5f (merged by ClawSweeper automerge)