fix(agent): route explicit channel targets per recipient

vincentkoc · vincentkoc · commit 765765a972cc · 2026-04-28T07:58:13.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Agents/CLI: derive `openclaw agent --agent ... --channel ... --to ...` sessions from the explicit channel recipient instead of the agent main session, while preserving explicit `--session-id` and `--session-key` precedence. Fixes #41483; refs #41557, #60614, and #60621. Thanks @pingfanfan.
 - Control UI/WebChat: keep large attachment payloads out of Lit state and optimistic chat messages, using object URL previews plus send-time payload serialization so PDF/image uploads no longer trigger `RangeError: Maximum call stack size exceeded`. Fixes #73360; refs #54378 and #63432. Thanks @hejunhui-73, @Ansub, and @christianhernandez3-afk.
 - Agents/models: keep per-agent primary models strict when `fallbacks` is omitted, so probe-only custom providers are not tried as hidden fallback candidates unless the agent explicitly opts in. Fixes #73332. Thanks @haumanto.
 - Gateway/models: add `models.pricing.enabled` so offline or restricted-network installs can skip startup OpenRouter and LiteLLM pricing-catalog fetches while keeping explicit model costs working. Fixes #53639. Thanks @callebtc, @palewire, and @rjdjohnston.
diff --git a/docs/cli/agent.md b/docs/cli/agent.md
@@ -29,7 +29,7 @@ Related:
 - `--model <id>`: model override for this run (`provider/model` or model id)
 - `--thinking <level>`: agent thinking level (`off`, `minimal`, `low`, `medium`, `high`, plus provider-supported custom levels such as `xhigh`, `adaptive`, or `max`)
 - `--verbose <on|off>`: persist verbose level for the session
-- `--channel <channel>`: delivery channel; omit to use the main session channel
+- `--channel <channel>`: delivery channel; with `--agent` and `--to`, also scopes the derived session key to that channel recipient
 - `--reply-to <target>`: delivery target override
 - `--reply-channel <channel>`: delivery channel override
 - `--reply-account <id>`: delivery account override
@@ -56,7 +56,7 @@ openclaw agent --agent ops --message "Run locally" --local
 - `--local` still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
 - `--local` and embedded fallback runs are treated as one-shot runs. Bundled MCP loopback resources and warm Claude stdio sessions opened for that local process are retired after the reply, so scripted invocations do not keep local child processes alive.
 - Gateway-backed runs leave Gateway-owned MCP loopback resources under the running Gateway process; older clients may still send the historical cleanup flag, but the Gateway accepts it as a compatibility no-op.
-- `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not session routing.
+- `--agent ... --channel ... --to ...` uses an agent-scoped channel-recipient session key. `--reply-channel` and `--reply-account` affect reply delivery, not session routing.
 - `--json` keeps stdout reserved for the JSON response. Gateway, plugin, and embedded-fallback diagnostics are routed to stderr so scripts can parse stdout directly.
 - Embedded fallback JSON includes `meta.transport: "embedded"` and `meta.fallbackFrom: "gateway"` so scripts can distinguish fallback runs from Gateway runs.
 - When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext.
diff --git a/src/agents/agent-command.ts b/src/agents/agent-command.ts
@@ -332,6 +332,7 @@ async function prepareAgentCommandExecution(
   const sessionResolution = resolveSession({
     cfg,
     to: opts.to,
+    channel: opts.channel,
     sessionId: opts.sessionId,
     sessionKey: opts.sessionKey,
     agentId: agentIdOverride,
diff --git a/src/agents/command/session.ts b/src/agents/command/session.ts
@@ -22,6 +22,7 @@ import { loadSessionStore } from "../../config/sessions/store-load.js";
 import type { SessionEntry } from "../../config/sessions/types.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import {
+  buildAgentPeerSessionKey,
   buildAgentMainSessionKey,
   DEFAULT_AGENT_ID,
   normalizeAgentId,
@@ -196,6 +197,7 @@ export function resolveStoredSessionKeyForSessionId(opts: {
 export function resolveSessionKeyForRequest(opts: {
   cfg: OpenClawConfig;
   to?: string;
+  channel?: string;
   sessionId?: string;
   sessionKey?: string;
   agentId?: string;
@@ -206,9 +208,16 @@ export function resolveSessionKeyForRequest(opts: {
   const defaultAgentId = normalizeAgentId(resolveDefaultAgentId(opts.cfg));
   const requestedAgentId = opts.agentId?.trim() ? normalizeAgentId(opts.agentId) : undefined;
   const requestedSessionId = opts.sessionId?.trim() || undefined;
+  const requestedSessionKey = opts.sessionKey?.trim();
+  const explicitChannel = opts.channel?.trim();
+  const explicitTo = opts.to?.trim();
+  const shouldPreferExplicitChannelSession =
+    Boolean(requestedAgentId && explicitChannel && explicitTo) &&
+    !requestedSessionId &&
+    !requestedSessionKey;
   const explicitSessionKey =
-    opts.sessionKey?.trim() ||
-    (!requestedSessionId
+    requestedSessionKey ||
+    (!requestedSessionId && !shouldPreferExplicitChannelSession
       ? resolveExplicitAgentSessionKey({
           cfg: opts.cfg,
           agentId: requestedAgentId,
@@ -223,8 +232,21 @@ export function resolveSessionKeyForRequest(opts: {
   const sessionStore = loadSessionStore(storePath);
 
   const ctx: MsgContext | undefined = opts.to?.trim() ? { From: opts.to } : undefined;
+  const explicitChannelSessionKey =
+    requestedAgentId && explicitChannel && explicitTo && !requestedSessionId
+      ? buildAgentPeerSessionKey({
+          agentId: storeAgentId,
+          mainKey,
+          channel: explicitChannel,
+          peerKind: "direct",
+          peerId: explicitTo,
+          dmScope: "per-channel-peer",
+        })
+      : undefined;
   let sessionKey: string | undefined =
-    explicitSessionKey ?? (ctx ? resolveSessionKey(scope, ctx, mainKey, storeAgentId) : undefined);
+    explicitSessionKey ??
+    explicitChannelSessionKey ??
+    (ctx ? resolveSessionKey(scope, ctx, mainKey, storeAgentId) : undefined);
 
   if (ctx && !requestedAgentId && !requestedSessionId && !explicitSessionKey) {
     const legacyMainSession = resolveLegacyMainStoreSessionForDefaultAgent({
@@ -284,6 +306,7 @@ export function resolveSessionKeyForRequest(opts: {
 export function resolveSession(opts: {
   cfg: OpenClawConfig;
   to?: string;
+  channel?: string;
   sessionId?: string;
   sessionKey?: string;
   agentId?: string;
@@ -292,6 +315,7 @@ export function resolveSession(opts: {
   const { sessionKey, sessionStore, storePath } = resolveSessionKeyForRequest({
     cfg: opts.cfg,
     to: opts.to,
+    channel: opts.channel,
     sessionId: opts.sessionId,
     sessionKey: opts.sessionKey,
     agentId: opts.agentId,
diff --git a/src/commands/agent-via-gateway.test.ts b/src/commands/agent-via-gateway.test.ts
@@ -33,6 +33,7 @@ function mockConfig(storePath: string, overrides?: Partial<OpenClawConfig>) {
         timeoutSeconds: 600,
         ...overrides?.agents?.defaults,
       },
+      list: overrides?.agents?.list,
     },
     session: {
       store: storePath,
@@ -138,6 +139,39 @@ describe("agentCliCommand", () => {
     });
   });
 
+  it("passes an agent-scoped recipient session key for explicit channel targets", async () => {
+    await withTempStore(
+      async () => {
+        mockGatewaySuccessReply();
+
+        await agentCliCommand(
+          {
+            message: "hi",
+            agent: "ops",
+            channel: "whatsapp",
+            to: "+15551234567",
+          },
+          runtime,
+        );
+
+        expect(callGateway).toHaveBeenCalledTimes(1);
+        expect(callGateway.mock.calls[0]?.[0]).toMatchObject({
+          params: {
+            agentId: "ops",
+            channel: "whatsapp",
+            to: "+15551234567",
+            sessionKey: "agent:ops:whatsapp:direct:+15551234567",
+          },
+        });
+      },
+      {
+        agents: {
+          list: [{ id: "ops" }],
+        },
+      } satisfies Partial<OpenClawConfig>,
+    );
+  });
+
   it("routes diagnostics to stderr before JSON gateway execution", async () => {
     await withTempStore(async () => {
       const response = {
diff --git a/src/commands/agent-via-gateway.ts b/src/commands/agent-via-gateway.ts
@@ -123,14 +123,15 @@ export async function agentViaGatewayCommand(opts: AgentCliOpts, runtime: Runtim
       ? NO_GATEWAY_TIMEOUT_MS // no timeout (timer-safe max)
       : Math.max(10_000, (timeoutSeconds + 30) * 1000);
 
+  const channel = normalizeMessageChannel(opts.channel);
   const sessionKey = resolveSessionKeyForRequest({
     cfg,
     agentId,
     to: opts.to,
+    channel,
     sessionId: opts.sessionId,
   }).sessionKey;
 
-  const channel = normalizeMessageChannel(opts.channel);
   const idempotencyKey = normalizeOptionalString(opts.runId) || randomIdempotencyKey();
 
   const response: GatewayAgentResponse = await withProgress(
diff --git a/src/commands/agent/session.test.ts b/src/commands/agent/session.test.ts
@@ -28,9 +28,9 @@ vi.mock("../../config/sessions/paths.js", () => ({
 }));
 
 vi.mock("../../agents/agent-scope.js", async () => {
-  const { normalizeAgentId } = await vi.importActual<
-    typeof import("../../routing/session-key.js")
-  >("../../routing/session-key.js");
+  const { normalizeAgentId } = await vi.importActual<typeof import("../../routing/session-key.js")>(
+    "../../routing/session-key.js",
+  );
   return {
     listAgentIds: mocks.listAgentIds,
     resolveDefaultAgentId: (cfg: OpenClawConfig) => {
@@ -102,6 +102,59 @@ describe("resolveSessionKeyForRequest", () => {
     expect(result.storePath).toBe(MYBOT_STORE_PATH);
   });
 
+  it("derives an agent-scoped recipient key for explicit --agent --channel --to sessions", async () => {
+    setupMainAndMybotStorePaths();
+    mockStoresByPath({
+      [MYBOT_STORE_PATH]: {},
+    });
+
+    const result = resolveSessionKeyForRequest({
+      cfg: baseCfg,
+      agentId: "mybot",
+      channel: "whatsapp",
+      to: "+15551234567",
+    });
+
+    expect(result.sessionKey).toBe("agent:mybot:whatsapp:direct:+15551234567");
+    expect(result.storePath).toBe(MYBOT_STORE_PATH);
+  });
+
+  it("keeps global scope for non-channel --agent --to session derivation", async () => {
+    setupMainAndMybotStorePaths();
+    mockStoresByPath({
+      [MYBOT_STORE_PATH]: {},
+    });
+
+    const result = resolveSessionKeyForRequest({
+      cfg: { session: { scope: "global" } } satisfies OpenClawConfig,
+      agentId: "mybot",
+      to: "+15551234567",
+    });
+
+    expect(result.sessionKey).toBe("global");
+    expect(result.storePath).toBe(MYBOT_STORE_PATH);
+  });
+
+  it("keeps --session-id lookup ahead of explicit channel recipient derivation", async () => {
+    setupMainAndMybotStorePaths();
+    mockStoresByPath({
+      [MYBOT_STORE_PATH]: {
+        "agent:mybot:main": { sessionId: "target-session-id", updatedAt: 0 },
+      },
+    });
+
+    const result = resolveSessionKeyForRequest({
+      cfg: baseCfg,
+      agentId: "mybot",
+      channel: "whatsapp",
+      to: "+15551234567",
+      sessionId: "target-session-id",
+    });
+
+    expect(result.sessionKey).toBe("agent:mybot:main");
+    expect(result.storePath).toBe(MYBOT_STORE_PATH);
+  });
+
   it("migrates legacy main-store main-key sessions for plain --to default-agent requests", async () => {
     setupMainAndMybotStorePaths();
     const mainStore = {
