fix(gateway): block internal HTTP session overrides

openclaw-clownfish[bot] · RichardCao · web-flow · commit 8694fe7e81f2 · 2026-06-16T09:30:27.000+08:00
Reject HTTP session-key overrides that target reserved internal session namespaces while preserving normal explicit session keys.

Co-authored-by: RichardCao &lt;4612401+RichardCao@users.noreply.github.com&gt;
diff --git a/docs/gateway/openai-http-api.md b/docs/gateway/openai-http-api.md
@@ -99,7 +99,7 @@ Optional request headers:
 
 - `x-openclaw-model: <provider/model-or-bare-id>` overrides the backend model for the selected agent. Shared-secret bearer callers can use this header. Identity-bearing callers, such as trusted-proxy or private no-auth ingress requests with `x-openclaw-scopes`, need `operator.admin`; write-only callers get `403 missing scope: operator.admin`.
 - `x-openclaw-agent-id: <agentId>` remains supported as a compatibility override.
-- `x-openclaw-session-key: <sessionKey>` fully controls session routing.
+- `x-openclaw-session-key: <sessionKey>` explicitly controls session routing. The value must not use reserved internal session namespaces such as `subagent:`, `cron:`, or `acp:`; those requests are rejected with `400 invalid_request_error`.
 - `x-openclaw-message-channel: <channel>` sets the synthetic ingress channel context for channel-aware prompts and policies.
 
 Compatibility aliases still accepted:
@@ -145,7 +145,7 @@ By default the endpoint is **stateless per request** (a new session key is gener
 
 If the request includes an OpenAI `user` string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.
 
-For custom apps, the safest default is to reuse the same `user` value per conversation thread. Avoid account-level identifiers unless you explicitly want multiple conversations or devices to share one OpenClaw session. Use `x-openclaw-session-key` when you need explicit routing control across multiple clients or threads.
+For custom apps, the safest default is to reuse the same `user` value per conversation thread. Avoid account-level identifiers unless you explicitly want multiple conversations or devices to share one OpenClaw session. Use `x-openclaw-session-key` only when you need explicit routing control across multiple clients or threads, and choose application-owned keys that do not start with reserved internal namespaces such as `subagent:`, `cron:`, or `acp:`.
 
 ## Why this surface matters
 
diff --git a/src/gateway/http-utils.request-context.test.ts b/src/gateway/http-utils.request-context.test.ts
@@ -5,6 +5,7 @@ import type { IncomingMessage } from "node:http";
 import { describe, expect, it } from "vitest";
 import {
   authorizeOpenAiCompatibleHttpModelOverride,
+  GatewaySessionKeyOverrideError,
   resolveOpenAiCompatibleHttpOperatorScopes,
   resolveOpenAiCompatibleHttpSenderIsOwner,
   resolveGatewayRequestContext,
@@ -56,6 +57,35 @@ describe("resolveGatewayRequestContext", () => {
     expect(result.sessionKey).toContain("openresponses-user:alice");
   });
 
+  it("preserves normal explicit session-key overrides", () => {
+    const result = resolveGatewayRequestContext({
+      req: createReq({ "x-openclaw-session-key": "customer-case-42" }),
+      model: "openclaw",
+      sessionPrefix: "openai",
+      defaultMessageChannel: "webchat",
+    });
+
+    expect(result.sessionKey).toBe("customer-case-42");
+  });
+
+  it.each([
+    "subagent:worker",
+    "cron:daily",
+    "acp:run-1",
+    "agent:main:subagent:worker",
+    "agent:main:cron:daily",
+    "agent:main:acp:run-1",
+  ])("rejects reserved internal session-key override %s", (sessionKey) => {
+    expect(() =>
+      resolveGatewayRequestContext({
+        req: createReq({ "x-openclaw-session-key": sessionKey }),
+        model: "openclaw",
+        sessionPrefix: "openai",
+        defaultMessageChannel: "webchat",
+      }),
+    ).toThrow(GatewaySessionKeyOverrideError);
+  });
+
   it("does not build session state for explicit unknown agent ids", () => {
     expect(() =>
       resolveGatewayRequestContext({
diff --git a/src/gateway/http-utils.ts b/src/gateway/http-utils.ts
@@ -13,6 +13,9 @@ import { getRuntimeConfig } from "../config/io.js";
 import { loadManifestMetadataSnapshot } from "../plugins/manifest-contract-eligibility.js";
 import {
   buildAgentMainSessionKey,
+  isAcpSessionKey,
+  isCronSessionKey,
+  isSubagentSessionKey,
   isValidAgentId,
   normalizeAgentId,
 } from "../routing/session-key.js";
@@ -49,10 +52,23 @@ export class UnknownGatewayAgentError extends Error {
   }
 }
 
+export class GatewaySessionKeyOverrideError extends Error {
+  constructor() {
+    super("`x-openclaw-session-key` cannot use reserved internal session namespaces.");
+    this.name = "GatewaySessionKeyOverrideError";
+  }
+}
+
 export function isUnknownGatewayAgentError(err: unknown): err is UnknownGatewayAgentError {
   return err instanceof UnknownGatewayAgentError;
 }
 
+export function isGatewaySessionKeyOverrideError(
+  err: unknown,
+): err is GatewaySessionKeyOverrideError {
+  return err instanceof GatewaySessionKeyOverrideError;
+}
+
 function assertKnownAgentId(agentId: string, cfg = getRuntimeConfig()): void {
   if (!listAgentIds(cfg).includes(agentId)) {
     throw new UnknownGatewayAgentError(agentId);
@@ -185,6 +201,9 @@ function resolveSessionKey(params: {
 }): string {
   const explicit = getHeader(params.req, "x-openclaw-session-key")?.trim();
   if (explicit) {
+    if (isReservedSessionKeyOverride(explicit)) {
+      throw new GatewaySessionKeyOverrideError();
+    }
     return explicit;
   }
 
@@ -193,6 +212,18 @@ function resolveSessionKey(params: {
   return buildAgentMainSessionKey({ agentId: params.agentId, mainKey });
 }
 
+function isReservedSessionKeyOverride(sessionKey: string): boolean {
+  const lowered = normalizeLowercaseStringOrEmpty(sessionKey);
+  return (
+    lowered.startsWith("subagent:") ||
+    lowered.startsWith("cron:") ||
+    lowered.startsWith("acp:") ||
+    isSubagentSessionKey(sessionKey) ||
+    isCronSessionKey(sessionKey) ||
+    isAcpSessionKey(sessionKey)
+  );
+}
+
 /** Resolves gateway agent/session/channel context for OpenAI-compatible handlers. */
 export function resolveGatewayRequestContext(params: {
   req: IncomingMessage;
diff --git a/src/gateway/openai-http.test.ts b/src/gateway/openai-http.test.ts
@@ -280,6 +280,22 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         await res.text();
       }
 
+      {
+        agentCommand.mockClear();
+        const res = await postChatCompletions(
+          port,
+          { model: "openclaw", messages: [{ role: "user", content: "hi" }] },
+          { "x-openclaw-session-key": "agent:main:subagent:spoofed" },
+        );
+        expect(res.status).toBe(400);
+        const json = (await res.json()) as { error?: { type?: string; message?: string } };
+        expect(json.error?.type).toBe("invalid_request_error");
+        expect(json.error?.message).toBe(
+          "`x-openclaw-session-key` cannot use reserved internal session namespaces.",
+        );
+        expect(agentCommand).toHaveBeenCalledTimes(0);
+      }
+
       {
         mockAgentOnce([{ text: "hello" }]);
         const res = await postChatCompletions(port, {
diff --git a/src/gateway/openai-http.ts b/src/gateway/openai-http.ts
@@ -53,6 +53,7 @@ import {
 import { handleGatewayPostJsonEndpoint } from "./http-endpoint-helpers.js";
 import {
   authorizeOpenAiCompatibleHttpModelOverride,
+  isGatewaySessionKeyOverrideError,
   isUnknownGatewayAgentError,
   resolveGatewayRequestContext,
   resolveOpenAiCompatModelOverride,
@@ -988,7 +989,7 @@ export async function handleOpenAiHttpRequest(
       useMessageChannelHeader: true,
     }));
   } catch (err) {
-    if (isUnknownGatewayAgentError(err)) {
+    if (isUnknownGatewayAgentError(err) || isGatewaySessionKeyOverrideError(err)) {
       sendJson(res, 400, {
         error: { message: err.message, type: "invalid_request_error" },
       });
diff --git a/src/gateway/openresponses-http.test.ts b/src/gateway/openresponses-http.test.ts
@@ -321,6 +321,37 @@ describe("OpenResponses HTTP API (e2e)", () => {
       );
       await ensureResponseConsumed(resHeader);
 
+      mockAgentOnce([{ text: "hello" }]);
+      const resSessionOverride = await postResponses(
+        port,
+        { model: "openclaw", input: "hi" },
+        {
+          "x-openclaw-agent-id": "beta",
+          "x-openclaw-session-key": "agent:beta:openresponses:custom",
+        },
+      );
+      expect(resSessionOverride.status).toBe(200);
+      expect((firstAgentOpts() as { sessionKey?: string }).sessionKey).toBe(
+        "agent:beta:openresponses:custom",
+      );
+      await ensureResponseConsumed(resSessionOverride);
+
+      agentCommand.mockClear();
+      const resReservedSessionOverride = await postResponses(
+        port,
+        { model: "openclaw", input: "hi" },
+        { "x-openclaw-session-key": "agent:main:subagent:spoofed" },
+      );
+      expect(resReservedSessionOverride.status).toBe(400);
+      const reservedSessionJson = (await resReservedSessionOverride.json()) as {
+        error?: { type?: string; message?: string };
+      };
+      expect(reservedSessionJson.error?.type).toBe("invalid_request_error");
+      expect(reservedSessionJson.error?.message).toBe(
+        "`x-openclaw-session-key` cannot use reserved internal session namespaces.",
+      );
+      expect(agentCommand).toHaveBeenCalledTimes(0);
+
       mockAgentOnce([{ text: "hello" }]);
       const resModel = await postResponses(port, { model: "openclaw/beta", input: "hi" });
       expect(resModel.status).toBe(200);
diff --git a/src/gateway/openresponses-http.ts b/src/gateway/openresponses-http.ts
@@ -48,6 +48,7 @@ import {
   authorizeOpenAiCompatibleHttpModelOverride,
   getBearerToken,
   getHeader,
+  isGatewaySessionKeyOverrideError,
   isUnknownGatewayAgentError,
   resolveAgentIdForRequest,
   resolveGatewayRequestContext,
@@ -667,7 +668,7 @@ export async function handleOpenResponsesHttpRequest(
       useMessageChannelHeader: true,
     });
   } catch (err) {
-    if (isUnknownGatewayAgentError(err)) {
+    if (isUnknownGatewayAgentError(err) || isGatewaySessionKeyOverrideError(err)) {
       sendJson(res, 400, {
         error: { message: err.message, type: "invalid_request_error" },
       });
