feat: pass channel context to exec

lanzhi-lee · lanzhi-lee · commit be5b8434cd24 · 2026-06-22T16:59:16.000+08:00
diff --git a/docs/tools/exec.md b/docs/tools/exec.md
@@ -92,6 +92,8 @@ Notes:
 - Host execution (`gateway`/`node`) rejects `env.PATH` and loader overrides (`LD_*`/`DYLD_*`) to
   prevent binary hijacking or injected code.
 - OpenClaw sets `OPENCLAW_SHELL=exec` in the spawned command environment (including PTY and sandbox execution) so shell/profile rules can detect exec-tool context.
+- For channel-origin runs, OpenClaw also exposes channel-owned sender/chat metadata as JSON in
+  `OPENCLAW_CHANNEL_CONTEXT` when the channel provided that context.
 - `openclaw channels login` is blocked from `exec` because it is an interactive channel-auth flow; run it in a terminal on the gateway host, or use the channel-native login tool from chat when one exists.
 - Important: sandboxing is **off by default**. If sandboxing is off, implicit `host=auto`
   resolves to `gateway`. Explicit `host=sandbox` still fails closed instead of silently
diff --git a/src/agents/agent-tools.ts b/src/agents/agent-tools.ts
@@ -24,6 +24,7 @@ import {
 } from "../infra/exec-approvals.js";
 import { resolveMergedSafeBinProfileFixtures } from "../infra/exec-safe-bin-runtime-policy.js";
 import { logWarn } from "../logger.js";
+import type { PluginHookChannelContext } from "../plugins/hook-types.js";
 import { getPluginToolMeta } from "../plugins/tools.js";
 import { createLazyImportLoader } from "../shared/lazy-promise.js";
 import type { SkillSnapshot } from "../skills/types.js";
@@ -503,6 +504,8 @@ export function createOpenClawCodingTools(options?: {
   currentMessagingTarget?: string;
   /** Normalized conversation id exposed to tool hooks. Defaults to currentChannelId. */
   hookChannelId?: string;
+  /** Channel-owned sender/chat metadata exposed to subprocess environments. */
+  channelContext?: PluginHookChannelContext;
   /** Current thread timestamp for auto-threading (Slack). */
   currentThreadTs?: string;
   /** Current inbound message id for action fallbacks (e.g. Telegram react). */
@@ -870,6 +873,7 @@ export function createOpenClawCodingTools(options?: {
         messageProvider: options?.messageProvider,
         currentChannelId: options?.currentChannelId,
         currentThreadTs: options?.currentThreadTs,
+        channelContext: options?.channelContext,
         accountId: options?.agentAccountId,
         approvalReviewerDeviceId: options?.approvalReviewerDeviceId,
         backgroundMs: options?.exec?.backgroundMs ?? execConfig.backgroundMs,
diff --git a/src/agents/bash-tools.exec-types.ts b/src/agents/bash-tools.exec-types.ts
@@ -15,6 +15,7 @@ import type {
 } from "../infra/exec-approvals.js";
 import type { ExecAutoReviewer } from "../infra/exec-auto-review.js";
 import type { SafeBinProfileFixture } from "../infra/exec-safe-bin-policy.js";
+import type { PluginHookChannelContext } from "../plugins/hook-types.js";
 import type { BashSandboxConfig } from "./bash-tools.shared.js";
 import type { EmbeddedFullAccessBlockedReason } from "./embedded-agent-runner/types.js";
 import type { ExecReviewerConfig } from "./exec-auto-reviewer.js";
@@ -71,6 +72,8 @@ export type ExecToolDefaults = {
   messageProvider?: string;
   currentChannelId?: string;
   currentThreadTs?: string;
+  /** Channel-owned sender/chat metadata exposed to subprocesses as OPENCLAW_CHANNEL_CONTEXT. */
+  channelContext?: PluginHookChannelContext;
   accountId?: string;
   approvalReviewerDeviceId?: string;
   notifyOnExit?: boolean;
diff --git a/src/agents/bash-tools.exec.resolve-env-hook.test.ts b/src/agents/bash-tools.exec.resolve-env-hook.test.ts
@@ -7,6 +7,14 @@ import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { OPENCLAW_CLI_ENV_VALUE } from "../infra/openclaw-exec-env.js";
 import type { ExtensionContext } from "./sessions/index.js";
 
+declare module "../plugins/hook-types.js" {
+  interface PluginHookChannelSenderContext {
+    unionId?: string;
+  }
+}
+
+const CHANNEL_CONTEXT_ENV_KEY = "OPENCLAW_CHANNEL_CONTEXT";
+
 const mocks = vi.hoisted(() => ({
   hookRunner: undefined as
     | {
@@ -130,6 +138,31 @@ describe("exec resolve_exec_env hook wiring", () => {
     mocks.spawnInputs.length = 0;
   });
 
+  it("adds channel context env to gateway exec subprocesses", async () => {
+    const tool = createExecTool({
+      host: "auto",
+      security: "full",
+      ask: "off",
+      channelContext: {
+        sender: { id: "ou_1", unionId: "on_1" },
+        chat: { id: "oc_1" },
+      },
+    });
+
+    await tool.execute("call-channel-env", {
+      command: "echo ok",
+      yieldMs: 120_000,
+    });
+
+    expect(JSON.parse(mocks.gatewayParams[0]?.env[CHANNEL_CONTEXT_ENV_KEY] ?? "{}")).toEqual({
+      chat: { id: "oc_1" },
+      sender: { id: "ou_1", unionId: "on_1" },
+    });
+    expect(mocks.spawnInputs[0]?.env?.[CHANNEL_CONTEXT_ENV_KEY]).toBe(
+      mocks.gatewayParams[0]?.env[CHANNEL_CONTEXT_ENV_KEY],
+    );
+  });
+
   it("merges filtered plugin env into gateway execution and approval-visible requested env", async () => {
     installResolveExecEnvHook({
       EXISTING: "plugin",
@@ -147,6 +180,10 @@ describe("exec resolve_exec_env hook wiring", () => {
       sessionKey: "agent:main:telegram:chat-1",
       messageProvider: "telegram",
       currentChannelId: "chat-1",
+      channelContext: {
+        sender: { id: "ou_1", unionId: "on_1" },
+        chat: { id: "oc_1" },
+      },
     });
     await tool.execute("call-1", {
       command: "echo ok",
@@ -171,10 +208,16 @@ describe("exec resolve_exec_env hook wiring", () => {
         },
       },
     );
-    expect(mocks.gatewayParams[0]?.requestedEnv).toEqual({
+    expect(mocks.gatewayParams[0]?.requestedEnv).toMatchObject({
       EXISTING: "plugin",
       PLUGIN_SAFE: "yes",
     });
+    expect(
+      JSON.parse(mocks.gatewayParams[0]?.requestedEnv?.[CHANNEL_CONTEXT_ENV_KEY] ?? "{}"),
+    ).toEqual({
+      chat: { id: "oc_1" },
+      sender: { id: "ou_1", unionId: "on_1" },
+    });
     expect(mocks.gatewayParams[0]?.env).toMatchObject({
       EXISTING: "plugin",
       PLUGIN_SAFE: "yes",
@@ -199,20 +242,34 @@ describe("exec resolve_exec_env hook wiring", () => {
       security: "full",
       ask: "off",
       sessionKey: "agent:main:main",
+      channelContext: {
+        sender: { id: "ou_node" },
+        chat: { id: "oc_node" },
+      },
     });
     await tool.execute("call-node", {
       command: "echo ok",
       env: { REQUEST_SAFE: "request" },
     });
 
-    expect(mocks.nodeHostParams[0]?.requestedEnv).toEqual({
+    expect(mocks.nodeHostParams[0]?.requestedEnv).toMatchObject({
       NODE_HOST_SAFE: "yes",
       REQUEST_SAFE: "request",
     });
     expect(mocks.nodeHostParams[0]?.env).toMatchObject({
       NODE_HOST_SAFE: "yes",
       REQUEST_SAFE: "request",
     });
+    expect(
+      JSON.parse(mocks.nodeHostParams[0]?.requestedEnv?.[CHANNEL_CONTEXT_ENV_KEY] ?? "{}"),
+    ).toEqual({
+      chat: { id: "oc_node" },
+      sender: { id: "ou_node" },
+    });
+    expect(JSON.parse(mocks.nodeHostParams[0]?.env?.[CHANNEL_CONTEXT_ENV_KEY] ?? "{}")).toEqual({
+      chat: { id: "oc_node" },
+      sender: { id: "ou_node" },
+    });
     expect(mocks.nodeHostParams[0]?.env).not.toHaveProperty("LD_PRELOAD");
   });
 
diff --git a/src/agents/bash-tools.exec.ts b/src/agents/bash-tools.exec.ts
@@ -49,6 +49,7 @@ import {
 } from "../routing/session-key.js";
 import { createLazyImportLoader } from "../shared/lazy-promise.js";
 import { normalizeDeliveryContext } from "../utils/delivery-context.js";
+import { safeJsonStringify } from "../utils/safe-json.js";
 import { splitShellArgs } from "../utils/shell-argv.js";
 import type { HookContext } from "./agent-tools.before-tool-call.js";
 import { stripMalformedXmlArgValueSuffixFromKeys } from "./agent-tools.params.js";
@@ -106,6 +107,16 @@ type ExecToolArgs = Record<string, unknown> & {
   ask?: string;
   node?: string;
 };
+
+const CHANNEL_CONTEXT_ENV_KEY = "OPENCLAW_CHANNEL_CONTEXT";
+
+function buildChannelContextEnv(channelContext: unknown): Record<string, string> | undefined {
+  if (!channelContext) {
+    return undefined;
+  }
+  const serialized = safeJsonStringify(channelContext);
+  return serialized ? { [CHANNEL_CONTEXT_ENV_KEY]: serialized } : undefined;
+}
 type ResolvedExecEnvPreparedState = {
   host?: ExecHost;
   pluginEnv?: Record<string, string>;
@@ -1572,9 +1583,13 @@ export function createExecTool(
 
       const inheritedBaseEnv = coerceEnv(process.env);
       const resolvedExecEnvState = getResolvedExecEnvPreparedState(params);
-      const requestedEnv = resolvedExecEnvState?.pluginEnv
-        ? { ...params.env, ...resolvedExecEnvState.pluginEnv }
-        : params.env;
+      const channelContextEnv = buildChannelContextEnv(defaults?.channelContext);
+      const requestedEnv: Record<string, string> | undefined =
+        params.env !== undefined ||
+        resolvedExecEnvState?.pluginEnv !== undefined ||
+        channelContextEnv !== undefined
+          ? { ...params.env, ...resolvedExecEnvState?.pluginEnv, ...channelContextEnv }
+          : undefined;
       const hostEnvResult =
         host === "sandbox"
           ? null
@@ -1627,6 +1642,7 @@ export function createExecTool(
               containerWorkdir: containerWorkdir ?? sandbox.containerWorkdir,
             })
           : (hostEnvResult?.env ?? inheritedBaseEnv);
+      Object.assign(env, channelContextEnv);
 
       if (!sandbox && host === "gateway" && !requestedEnv?.PATH) {
         const shellPath = getShellPathFromLoginShell({
diff --git a/src/agents/embedded-agent-runner/run/attempt.ts b/src/agents/embedded-agent-runner/run/attempt.ts
@@ -1268,6 +1268,7 @@ export async function runEmbeddedAttempt(
             memberRoleIds: params.memberRoleIds,
             spawnedBy: params.spawnedBy,
             senderId: params.senderId,
+            channelContext: params.channelContext,
             senderName: params.senderName,
             senderUsername: params.senderUsername,
             senderE164: params.senderE164,
