Greptile Summary

This PR fixes a security gap in the OpenClaw gateway where unknown agent IDs supplied via x-openclaw-agent-id, x-openclaw-agent, or model-selector strings (openclaw:<id> / agent:<id>) were silently routed to the main agent rather than rejected. The fix adds InvalidGatewayAgentIdError, validates explicit selections against listAgentIds(loadConfig()) in both HTTP handlers, and maps the error to a consistent 400 JSON response.

Key changes:

• http-utils.ts — new InvalidGatewayAgentIdError class; internal ExplicitAgentSelection type preserves raw input for error messages; assertKnownExplicitAgentSelection enforces the allowlist; no-header / no-model fallback to main is preserved.
• openai-http.ts / openresponses-http.ts — both handlers now wrap resolveGatewayRequestContext in a try/catch that converts InvalidGatewayAgentIdError to a 400 invalid_request_error.
• Tests cover four new scenarios across three test files.

One logic concern:
assertKnownExplicitAgentSelection is called with the optional knownAgentIds parameter, but when that parameter is undefined, the optional-chain expression knownAgentIds?.includes(...) evaluates to undefined and !undefined === true causes the function to always throw for any explicit agent selection. Both current callers always supply a non-undefined list, so nothing breaks today, but any future gateway handler or test that omits knownAgentIds while handling agent-scoped requests will get unexpected InvalidGatewayAgentIdError exceptions. Treating undefined as "skip validation" (i.e. if (knownAgentIds !== undefined && !knownAgentIds.includes(...))) would make the optional contract safe.

Confidence Score: 4/5

• Safe to merge with the optional-parameter footgun acknowledged — all current callers pass a valid knownAgentIds list.
• The security fix is correct and well-tested. The only concern is an API design issue in assertKnownExplicitAgentSelection: omitting the optional knownAgentIds parameter (rather than "no validation") causes it to throw on any explicit agent selection, which contradicts the ? optional contract. This does not affect any current production path but is a subtle footgun for future contributors.
• src/gateway/http-utils.ts — specifically the assertKnownExplicitAgentSelection helper and its behavior when knownAgentIds is undefined.

This is a comment left during a code review.
Path: src/gateway/http-utils.ts
Line: 80-88

Comment:
**`knownAgentIds: undefined` silently rejects all explicit agent selections**

When `knownAgentIds` is `undefined`, the optional-chaining expression `knownAgentIds?.includes(selection.agentId)` evaluates to `undefined`, so `!undefined` is `true` and the function **always throws `InvalidGatewayAgentIdError`** — even for a perfectly valid agent ID.

This contradicts the implied contract of the `?` optional parameter in `resolveAgentIdForRequest` and `resolveGatewayRequestContext`: a caller who omits `knownAgentIds` expecting "no validation" will instead get an unexpected error thrown for any request that carries an explicit `x-openclaw-agent-id` header or an `openclaw:<id>` / `agent:<id>` model selector.

The two current production callers always pass `listAgentIds(loadConfig())`, so nothing breaks today. However, any future gateway handler (or unit test) that omits `knownAgentIds` while handling agent-scoped requests will silently break.

Suggested fix — treat `undefined` as "skip validation":

```ts
function assertKnownExplicitAgentSelection(
  selection: ExplicitAgentSelection,
  knownAgentIds: readonly string[] | undefined,
): string {
  if (knownAgentIds !== undefined && !knownAgentIds.includes(selection.agentId)) {
    throw new InvalidGatewayAgentIdError(selection.rawAgentId);
  }
  return selection.agentId;
}
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: 3eec497}

Reviewed the diff — solid security fix. The silent fallback to main for unknown agent IDs is a real gap for anyone exposing the HTTP API. Clean implementation, good test coverage across all four paths (header-known, header-unknown, model-known, model-unknown), and the CLI hint in the error message is a nice UX touch.

Agreeing with xkonjin's note on loadConfig() per-request — fine for single-user setups, but worth considering a short-TTL memoization if this path gets hot in multi-tenant deployments. Not a blocker.

Also +1 on the knownAgentIds: undefined behavior question — rejecting all explicit selections when the list is undefined is the safe default, but a brief code comment documenting that intent would help future contributors.

Thanks for the context here. I swept through the related work, and this is now duplicate or superseded.

Keep open. The PR addresses a real source-reproducible gateway bug, but the branch is now conflicting and stale, lacks after-fix real behavior proof, and would regress current OpenAI-compatible gateway routing contracts if merged as submitted.

Canonical path: Close this stale PR. The latest review rated it F, the branch still lacks merge-ready proof, and there has been no human follow-up after the durable review.

So I’m closing this here because the remaining work is already tracked in the canonical issue.

ClawSweeper PR egg

🎁 Pass real behavior proof to wake the egg and unlock a hatchable treat.

ClawSweeper applied the proposed close for this PR.

• Action: closed this PR.
• Close reason: duplicate or superseded.
• Evidence: durable ClawSweeper review.