feat(tools): add per-sender tool policies (#66933)

JerranC · steipete · web-flow · commit 530b892f0684 · 2026-05-11T18:01:39.000+01:00
Co-authored-by: Peter Steinberger &lt;steipete@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Agents/tools: add per-sender tool policies with canonical channel-scoped sender keys, so operators can restrict dangerous tools by requester identity across global, agent, group, core, bundled, and plugin tool surfaces. (#66933) Thanks @JerranC.
 - CI: add a non-blocking `plugin-inspector-advisory` artifact to Plugin Prerelease so release runs capture bundled plugin compatibility triage without changing the blocking gate.
 - Runtime/Fly: detect Fly Machines as container environments from their runtime env vars, so gateway bind and Bonjour defaults match remote container launches. (#80209) Thanks @liorb-mountapps.
 - Providers/fal: route GPT Image 2 and Nano Banana 2 reference-image edit requests to `/edit` with `image_urls` array, enforce NB2 edit geometry using `aspect_ratio` and `resolution` params, lift Fal edit mode input-image caps to 10 for GPT Image 2 and 14 for Nano Banana 2, and allow aspect-ratio hints in edit mode. (#77295) Thanks @leoge007.
diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256
@@ -1,4 +1,4 @@
-c963f607273fcce55080dc6d8068d8e124a4aa111a8ecf04807ebef98dfa5fd5  config-baseline.json
-647f7a12deed46b4a962848a17ed5666d24fc526b777feab62cf331d84ce957d  config-baseline.core.json
+2800c9a6377fd02cb55bbf2577d63f2acc7193ed89be6fcffd32439893eaabc1  config-baseline.json
+ebbf966b41d99cd17282553f7882d1b826782599cbca6719b6f2c25b0e6b235d  config-baseline.core.json
 222d0338d6ed290870cac70cdf5e390bc1bb60c4462e46f847003bafe25c5a6e  config-baseline.channel.json
 18f71e9d4a62fe68fbd5bf18d5833a4e380fc705ad641769e1cf05794286344c  config-baseline.plugin.json
diff --git a/docs/channels/groups.md b/docs/channels/groups.md
@@ -362,7 +362,7 @@ Replying to a bot message counts as an implicit mention when the channel support
 Some channel configs support restricting which tools are available **inside a specific group/room/channel**.
 
 - `tools`: allow/deny tools for the whole group.
-- `toolsBySender`: per-sender overrides within the group. Use explicit key prefixes: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, and `"*"` wildcard. Legacy unprefixed keys are still accepted and matched as `id:` only.
+- `toolsBySender`: per-sender overrides within the group. Use explicit key prefixes: `channel:<channelId>:<senderId>`, `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, and `"*"` wildcard. Channel ids use canonical OpenClaw channel ids; aliases such as `teams` normalize to `msteams`. Legacy unprefixed keys are still accepted and matched as `id:` only.
 
 Resolution order (most specific wins):
 
diff --git a/docs/channels/msteams.md b/docs/channels/msteams.md
@@ -700,7 +700,7 @@ Key settings (see `/gateway/configuration` for shared channel patterns):
 - `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: per-channel tool policy overrides (`allow`/`deny`/`alsoAllow`).
 - `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: per-channel per-sender tool policy overrides (`"*"` wildcard supported).
 - `toolsBySender` keys should use explicit prefixes:
-  `id:`, `e164:`, `username:`, `name:` (legacy unprefixed keys still map to `id:` only).
+  `channel:`, `id:`, `e164:`, `username:`, `name:` (legacy unprefixed keys still map to `id:` only).
 - `channels.msteams.actions.memberInfo`: enable or disable the Graph-backed member info action (default: enabled when Graph credentials are available).
 - `channels.msteams.authType`: authentication type - `"secret"` (default) or `"federated"`.
 - `channels.msteams.certificatePath`: path to PEM certificate file (federated + certificate auth).
diff --git a/docs/channels/slack.md b/docs/channels/slack.md
@@ -915,7 +915,7 @@ Current Slack message actions include `send`, `upload-file`, `download-file`, `r
     - `skills`
     - `systemPrompt`
     - `tools`, `toolsBySender`
-    - `toolsBySender` key format: `id:`, `e164:`, `username:`, `name:`, or `"*"` wildcard
+    - `toolsBySender` key format: `channel:`, `id:`, `e164:`, `username:`, `name:`, or `"*"` wildcard
       (legacy unprefixed keys still map to `id:` only)
 
     `allowBots` is conservative for channels and private channels: bot-authored room messages are accepted only when the sending bot is explicitly listed in that room's `users` allowlist, or when at least one explicit Slack owner ID from `channels.slack.allowFrom` is currently a room member. Wildcards and display-name owner entries do not satisfy owner presence. Owner presence uses Slack `conversations.members`; make sure the app has the matching read scope for the room type (`channels:read` for public channels, `groups:read` for private channels). If the member lookup fails, OpenClaw drops the bot-authored room message.
diff --git a/docs/gateway/config-tools.md b/docs/gateway/config-tools.md
@@ -78,6 +78,26 @@ Further restrict tools for specific providers or models. Order: base profile →
 }
 ```
 
+### `tools.toolsBySender`
+
+Restricts tools for a specific requester identity. This is defense-in-depth on top of channel access control; sender values must come from the channel adapter, not message text.
+
+```json5
+{
+  tools: {
+    toolsBySender: {
+      "channel:discord:1234567890123": { alsoAllow: ["group:fs"] },
+      "id:guest-user-id": { deny: ["group:runtime", "group:fs"] },
+      "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] },
+    },
+  },
+}
+```
+
+Keys use explicit prefixes: `channel:<channelId>:<senderId>`, `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, or `"*"`. Channel ids are canonical OpenClaw ids; aliases such as `teams` normalize to `msteams`. Legacy unprefixed keys are accepted as `id:` only. Matching order is channel+id, id, e164, username, name, then wildcard.
+
+Per-agent `agents.list[].tools.toolsBySender` overrides the global sender match when it matches, even with an empty `{}` policy.
+
 ### `tools.elevated`
 
 Controls elevated exec access outside the sandbox:
diff --git a/src/agents/pi-embedded-runner/effective-tool-policy.test.ts b/src/agents/pi-embedded-runner/effective-tool-policy.test.ts
@@ -46,6 +46,24 @@ describe("applyFinalEffectiveToolPolicy", () => {
     expect(filtered.map((tool) => tool.name)).toEqual(["mcp__bundle__fs_read"]);
   });
 
+  it("applies channel-normalized per-sender policy to bundled tools", () => {
+    const filtered = applyFinalEffectiveToolPolicy({
+      bundledTools: [makeTool("mcp__bundle__exec"), makeTool("mcp__bundle__read")],
+      config: {
+        tools: {
+          toolsBySender: {
+            "channel:msteams:alice": { deny: ["mcp__bundle__exec"] },
+          },
+        },
+      },
+      messageProvider: "teams",
+      senderId: "alice",
+      warn: () => {},
+    });
+
+    expect(filtered.map((tool) => tool.name)).toEqual(["mcp__bundle__read"]);
+  });
+
   it("applies owner-only filtering to bundled tools", () => {
     const filtered = applyFinalEffectiveToolPolicy({
       bundledTools: [makeTool("mcp__bundle__read"), makeTool("mcp__bundle__admin", true)],
diff --git a/src/agents/pi-embedded-runner/effective-tool-policy.ts b/src/agents/pi-embedded-runner/effective-tool-policy.ts
@@ -6,6 +6,7 @@ import {
   resolveTrustedGroupId,
   resolveSubagentToolPolicyForSession,
 } from "../pi-tools.policy.js";
+import { resolveSenderToolPolicy } from "../sender-tool-policy.js";
 import {
   isSubagentEnvelopeSession,
   resolveSubagentCapabilityStore,
@@ -106,6 +107,15 @@ export function applyFinalEffectiveToolPolicy(
     senderUsername: params.senderUsername,
     senderE164: params.senderE164,
   });
+  const senderPolicy = resolveSenderToolPolicy({
+    config: params.config,
+    agentId,
+    messageProvider: params.messageProvider,
+    senderId: params.senderId,
+    senderName: params.senderName,
+    senderUsername: params.senderUsername,
+    senderE164: params.senderE164,
+  });
   const profilePolicy = resolveToolProfilePolicy(profile);
   const providerProfilePolicy = resolveToolProfilePolicy(providerProfile);
   const profilePolicyWithAlsoAllow = mergeAlsoAllowPolicy(profilePolicy, profileAlsoAllow);
@@ -154,6 +164,7 @@ export function applyFinalEffectiveToolPolicy(
       agentPolicy,
       agentProviderPolicy,
       groupPolicy,
+      senderPolicy,
       agentId,
     }),
     { policy: params.sandboxToolPolicy, label: "sandbox tools.allow" },
diff --git a/src/agents/pi-tools-agent-config.test.ts b/src/agents/pi-tools-agent-config.test.ts
@@ -420,6 +420,65 @@ describe("Agent-specific tool filtering", () => {
     ).toEqual({ allow: ["read"] });
   });
 
+  it("should apply global per-sender tool policy to core tools", () => {
+    const cfg: OpenClawConfig = {
+      tools: {
+        toolsBySender: {
+          "id:guest": { deny: ["exec", "process"] },
+        },
+      },
+    };
+
+    const tools = createOpenClawCodingTools({
+      config: cfg,
+      messageProvider: "discord",
+      senderId: "guest",
+      workspaceDir: "/tmp/test-global-sender-policy",
+      agentDir: "/tmp/agent-global-sender-policy",
+    });
+    const names = tools.map((tool) => tool.name);
+
+    expect(names).toContain("read");
+    expect(names).not.toContain("exec");
+    expect(names).not.toContain("process");
+  });
+
+  it("should let agent per-sender policy override global sender wildcard", () => {
+    const cfg: OpenClawConfig = {
+      tools: {
+        toolsBySender: {
+          "*": { deny: ["exec"] },
+        },
+      },
+      agents: {
+        list: [
+          {
+            id: "trusted",
+            workspace: "~/openclaw-trusted",
+            tools: {
+              toolsBySender: {
+                "id:alice": {},
+              },
+            },
+          },
+        ],
+      },
+    };
+
+    const tools = createOpenClawCodingTools({
+      config: cfg,
+      sessionKey: "agent:trusted:discord:dm:alice",
+      messageProvider: "discord",
+      senderId: "alice",
+      workspaceDir: "/tmp/test-agent-sender-policy",
+      agentDir: "/tmp/agent-sender-policy",
+    });
+    const names = tools.map((tool) => tool.name);
+
+    expect(names).toContain("read");
+    expect(names).toContain("exec");
+  });
+
   it("should not let default sender policy override group tools", () => {
     const cfg: OpenClawConfig = {
       channels: {
diff --git a/src/agents/pi-tools.policy.ts b/src/agents/pi-tools.policy.ts
@@ -561,6 +561,7 @@ export function resolveGroupToolPolicy(params: {
   const configTools = resolveChannelGroupToolsPolicy({
     cfg: params.config,
     channel,
+    messageProvider: channel,
     groupId: groupIds[0],
     groupIdCandidates: groupIds.slice(1),
     accountId: params.accountId,
diff --git a/src/agents/pi-tools.ts b/src/agents/pi-tools.ts
@@ -57,6 +57,7 @@ import { cleanToolSchemaForGemini, normalizeToolParameters } from "./pi-tools.sc
 import type { AnyAgentTool } from "./pi-tools.types.js";
 import type { SandboxContext } from "./sandbox.js";
 import { SANDBOX_AGENT_WORKSPACE_MOUNT } from "./sandbox/constants.js";
+import { resolveSenderToolPolicy } from "./sender-tool-policy.js";
 import {
   isSubagentEnvelopeSession,
   resolveSubagentCapabilityStore,
@@ -482,6 +483,15 @@ export function createOpenClawCodingTools(options?: {
     senderUsername: options?.senderUsername,
     senderE164: options?.senderE164,
   });
+  const senderPolicy = resolveSenderToolPolicy({
+    config: options?.config,
+    agentId,
+    messageProvider: options?.messageProvider,
+    senderId: options?.senderId,
+    senderName: options?.senderName,
+    senderUsername: options?.senderUsername,
+    senderE164: options?.senderE164,
+  });
   const profilePolicy = resolveToolProfilePolicy(profile);
   const providerProfilePolicy = resolveToolProfilePolicy(providerProfile);
 
@@ -545,6 +555,7 @@ export function createOpenClawCodingTools(options?: {
   const agentProviderPolicyWithToolSearchControls =
     mergeToolSearchControlAllowlist(agentProviderPolicy);
   const groupPolicyWithToolSearchControls = mergeToolSearchControlAllowlist(groupPolicy);
+  const senderPolicyWithToolSearchControls = mergeToolSearchControlAllowlist(senderPolicy);
   const sandboxToolPolicyWithToolSearchControls =
     mergeToolSearchControlAllowlist(sandboxToolPolicy);
   const subagentPolicyWithToolSearchControls = mergeToolSearchControlAllowlist(subagentPolicy);
@@ -556,6 +567,7 @@ export function createOpenClawCodingTools(options?: {
     agentPolicyWithToolSearchControls,
     agentProviderPolicyWithToolSearchControls,
     groupPolicyWithToolSearchControls,
+    senderPolicyWithToolSearchControls,
     sandboxToolPolicyWithToolSearchControls,
     subagentPolicyWithToolSearchControls,
   ]);
@@ -724,6 +736,7 @@ export function createOpenClawCodingTools(options?: {
     agentPolicy,
     agentProviderPolicy,
     groupPolicy,
+    senderPolicy,
     sandboxToolPolicy,
     subagentPolicy,
     options?.runtimeToolAllowlist ? { allow: options.runtimeToolAllowlist } : undefined,
@@ -736,6 +749,7 @@ export function createOpenClawCodingTools(options?: {
     agentPolicy,
     agentProviderPolicy,
     groupPolicy,
+    senderPolicy,
     sandboxToolPolicy,
     subagentPolicy,
   ]);
@@ -935,6 +949,7 @@ export function createOpenClawCodingTools(options?: {
         agentPolicy: agentPolicyWithToolSearchControls,
         agentProviderPolicy: agentProviderPolicyWithToolSearchControls,
         groupPolicy: groupPolicyWithToolSearchControls,
+        senderPolicy: senderPolicyWithToolSearchControls,
         agentId,
       }),
       { policy: sandboxToolPolicyWithToolSearchControls, label: "sandbox tools.allow" },
diff --git a/src/agents/sender-tool-policy.ts b/src/agents/sender-tool-policy.ts
@@ -0,0 +1,47 @@
+import { resolveToolsBySender } from "../config/group-policy.js";
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { resolveAgentConfig } from "./agent-scope.js";
+import { pickSandboxToolPolicy } from "./sandbox-tool-policy.js";
+import type { SandboxToolPolicy } from "./sandbox/types.js";
+
+type SenderToolPolicyParams = {
+  config?: OpenClawConfig;
+  agentId?: string;
+  messageProvider?: string | null;
+  senderId?: string | null;
+  senderName?: string | null;
+  senderUsername?: string | null;
+  senderE164?: string | null;
+};
+
+export function resolveSenderToolPolicy(
+  params: SenderToolPolicyParams,
+): SandboxToolPolicy | undefined {
+  const cfg = params.config;
+  if (!cfg) {
+    return undefined;
+  }
+  const sender = {
+    messageProvider: params.messageProvider,
+    senderId: params.senderId,
+    senderName: params.senderName,
+    senderUsername: params.senderUsername,
+    senderE164: params.senderE164,
+  };
+  const agentTools =
+    params.agentId && params.agentId.trim()
+      ? resolveAgentConfig(cfg, params.agentId)?.tools
+      : undefined;
+  const agentPolicy = resolveToolsBySender({
+    toolsBySender: agentTools?.toolsBySender,
+    ...sender,
+  });
+  if (agentPolicy) {
+    return pickSandboxToolPolicy(agentPolicy);
+  }
+  const globalPolicy = resolveToolsBySender({
+    toolsBySender: cfg.tools?.toolsBySender,
+    ...sender,
+  });
+  return pickSandboxToolPolicy(globalPolicy);
+}
diff --git a/src/agents/tool-policy-pipeline.ts b/src/agents/tool-policy-pipeline.ts
@@ -48,6 +48,7 @@ export function buildDefaultToolPolicyPipelineSteps(params: {
   agentPolicy?: ToolPolicyLike;
   agentProviderPolicy?: ToolPolicyLike;
   groupPolicy?: ToolPolicyLike;
+  senderPolicy?: ToolPolicyLike;
   agentId?: string;
 }): ToolPolicyPipelineStep[] {
   const agentId = params.agentId?.trim();
@@ -86,6 +87,7 @@ export function buildDefaultToolPolicyPipelineSteps(params: {
       stripPluginOnlyAllowlist: true,
     },
     { policy: params.groupPolicy, label: "group tools.allow", stripPluginOnlyAllowlist: true },
+    { policy: params.senderPolicy, label: "tools.toolsBySender", stripPluginOnlyAllowlist: true },
   ];
 }
 
diff --git a/src/config/group-policy.test.ts b/src/config/group-policy.test.ts
@@ -180,6 +180,37 @@ describe("resolveToolsBySender", () => {
     ).toEqual({ allow: ["exec"] });
   });
 
+  it("matches channel-scoped sender IDs through canonical channel aliases", () => {
+    expect(
+      resolveToolsBySender({
+        toolsBySender: {
+          "channel:msteams:user:alice": { allow: ["exec"] },
+          "id:user:alice": { deny: ["exec"] },
+          "*": { deny: ["write"] },
+        },
+        messageProvider: "teams",
+        senderId: "user:alice",
+      }),
+    ).toEqual({ allow: ["exec"] });
+  });
+
+  it("keeps legacy colon sender IDs as sender IDs, not channel keys", () => {
+    const warningSpy = vi.spyOn(process, "emitWarning").mockImplementation(() => undefined);
+
+    expect(
+      resolveToolsBySender({
+        toolsBySender: {
+          "discord:user:alice": { allow: ["exec"] },
+          "channel:discord:user:alice": { deny: ["exec"] },
+        },
+        messageProvider: "slack",
+        senderId: "discord:user:alice",
+      }),
+    ).toEqual({ allow: ["exec"] });
+
+    expect(warningSpy).toHaveBeenCalledTimes(1);
+  });
+
   it("does not allow senderName collisions to match id keys", () => {
     const victimId = "f4ce8a7d-1111-2222-3333-444455556666";
     expect(
@@ -274,6 +305,20 @@ describe("resolveToolsBySender", () => {
     ).toEqual({ deny: ["exec"] });
   });
 
+  it("prefers channel-specific sender policy before generic id policy", () => {
+    expect(
+      resolveToolsBySender({
+        toolsBySender: {
+          "channel:discord:alice": { allow: ["read"] },
+          "id:alice": { deny: ["read"] },
+          "*": { deny: ["exec"] },
+        },
+        messageProvider: "discord",
+        senderId: "alice",
+      }),
+    ).toEqual({ allow: ["read"] });
+  });
+
   it("emits one deprecation warning per legacy key", () => {
     const warningSpy = vi.spyOn(process, "emitWarning").mockImplementation(() => undefined);
     const legacyKey = "legacy-warning-key";
diff --git a/src/config/group-policy.ts b/src/config/group-policy.ts
diff --git a/src/config/types.tools.ts b/src/config/types.tools.ts
diff --git a/src/config/zod-schema.agent-runtime.ts b/src/config/zod-schema.agent-runtime.ts
