Skip to content

fix(message-tool): use agent-scoped media roots for path validation#36219

Closed
Sid-Qin wants to merge 1 commit into
openclaw:mainfrom
Sid-Qin:fix/36185-message-tool-agent-scoped-media-roots
Closed

fix(message-tool): use agent-scoped media roots for path validation#36219
Sid-Qin wants to merge 1 commit into
openclaw:mainfrom
Sid-Qin:fix/36185-message-tool-agent-scoped-media-roots

Conversation

@Sid-Qin

@Sid-Qin Sid-Qin commented Mar 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Problem: The message tool resolved agentId only from agentSessionKey, leaving it undefined for cron/hook sessions that lack a session key. This caused getAgentScopedMediaLocalRoots(cfg, undefined) to return only default roots (e.g. ~/.openclaw/media), rejecting files under the agent's configured workspace directory with LocalMediaAccessError: path-not-allowed.
  • Why it matters: Agents cannot send files from their own workspace via the message tool, forcing a manual workaround of copying files to ~/.openclaw/media/outbound/.
  • What changed: Added an agentId field to MessageToolOptions and threaded requesterAgentIdOverride (already available in createOpenClawTools) into the message tool creation. When agentSessionKey is unavailable, this explicit agentId is forwarded to runMessageAction, which passes it to getAgentScopedMediaLocalRoots to include the agent's workspace in the allowed media roots.
  • What did NOT change: The getAgentScopedMediaLocalRoots function, the runMessageAction function, or any media path validation logic. The fix only ensures the existing agent-scoped path is reachable.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

User-visible / Behavior Changes

  • Files under the agent's configured workspace directory (e.g. /home/user/clawd/) are now accepted by the message tool's media path validation, instead of being rejected with path-not-allowed.

Security Impact (required)

  • New permissions/capabilities? No — the agent workspace was already an allowed root in getAgentScopedMediaLocalRoots; this fix just ensures it's actually used.
  • Secrets/tokens handling changed? No
  • New/changed network calls? No
  • Command/tool execution surface changed? No
  • Data access scope changed? No

Repro + Verification

Environment

  • OS: any
  • Runtime: Node.js
  • Integration/channel: WhatsApp (or any channel using the message tool)

Steps

  1. Configure agents.defaults.workspace to a custom path (e.g. /home/user/clawd)
  2. Place a file in that workspace
  3. Use the message tool to send the file as an attachment

Expected

  • File is accepted and sent

Actual

  • Before fix: LocalMediaAccessError: path-not-allowed
  • After fix: File is accepted (workspace is included in allowed roots)

Evidence

Two files changed:

src/agents/tools/message-tool.ts: Added agentId?: string to MessageToolOptions and used it as fallback when agentSessionKey is unavailable.

src/agents/openclaw-tools.ts: Passed requesterAgentIdOverride as agentId when creating the message tool.

TypeScript check passes (npx tsc --noEmit — only pre-existing errors in extensions/diffs and extensions/tlon).

Human Verification (required)

  • Verified scenarios: TypeScript compilation, code review of runMessageAction resolution chain
  • Edge cases checked: agentSessionKey present (uses session-based resolution as before), both agentSessionKey and agentId absent (falls through to undefined as before), requesterAgentIdOverride set (used as fallback)
  • What I did not verify: End-to-end test with actual file sending from agent workspace

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Migration needed? No

Failure Recovery (if this breaks)

  • How to disable/revert: Revert the two-file change; the original behavior (default roots only) returns
  • Files/config to restore: src/agents/tools/message-tool.ts, src/agents/openclaw-tools.ts
  • Known bad symptoms: None expected — the agentId only widens the allowed media roots to include the agent's own workspace

Risks and Mitigations

None — this aligns the message tool with the existing behavior of other code paths that already use getAgentScopedMediaLocalRoots with a resolved agentId.

@Sid-Qin
fix(message-tool): use agent-scoped media roots for path validation
f451373 
The message tool resolved agentId only from agentSessionKey, leaving it
undefined for cron/hook sessions that lack a session key.  This caused
getAgentScopedMediaLocalRoots to fall back to default roots, rejecting
files under the agent's configured workspace directory.

Thread the requesterAgentIdOverride (already available) into
MessageToolOptions.agentId so runMessageAction receives a valid agentId
and includes the agent workspace in the allowed media roots.

Closes openclaw#36185
@greptile-apps

greptile-apps Bot commented Mar 5, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR fixes a bug where the message tool would fail to access files under an agent's configured workspace directory (e.g. /home/user/clawd/) when running in cron/hook sessions that lack an agentSessionKey. The root cause was that agentId was only resolved from the session key, leaving it undefined for non-session contexts and causing getAgentScopedMediaLocalRoots to skip the agent's workspace root.

The fix is minimal and surgical: it adds an agentId field to MessageToolOptions and uses requesterAgentIdOverride (already available in createOpenClawTools) as a fallback when the session key is absent. This mirrors the pattern already established for createAgentsListTool and createSessionsListTool, making the message tool consistent with the rest of the tool factory.

Key points:

  • No media path validation logic was changed — the fix only ensures the existing agent-scoped roots are reachable
  • Session-key-based resolution still takes precedence when agentSessionKey is present
  • requesterAgentIdOverride is a system-provided value (set in pi-tools.ts) and is not controllable by user input, so no security surface is widened
  • Backward compatible: when both agentSessionKey and agentId are absent, behaviour is unchanged (agentId remains undefined)

Confidence Score: 5/5

  • Safe to merge — the change is minimal, follows established patterns, and is strictly additive with no regressions in existing code paths.
  • The two-line logic change correctly threads a pre-existing system value (requesterAgentIdOverride) into the message tool, matching what other tools in the same factory already do. The ternary expression preserves existing session-based resolution when agentSessionKey is present, and the fallback only activates for cron/hook sessions. No new permissions are granted beyond what getAgentScopedMediaLocalRoots already intended to provide.
  • No files require special attention.

Last reviewed commit: f451373

@vincentkoc vincentkoc mentioned this pull request Mar 7, 2026
Closed
18 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

agents Agent runtime and tooling size: XS

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

message tool uses default media roots instead of agent-scoped roots

2 participants

@Sid-Qin @thewilloftheshadow