Bug Report: Session file path must be within sessions directory — All non-default agents fail to respond

Version: 2026.2.12 (f9e444d)
Platform: Ubuntu 24 (server, no GUI session)
Node.js: v22.22.0

Summary

All agents other than the default (main) silently fail to process incoming Telegram messages. The gateway starts successfully, bots show "typing..." in Telegram, but no response is ever sent. The error Session file path must be within sessions directory is thrown on every inbound message for non-default agents.

Steps to Reproduce

1. Configure multiple agents (e.g. main, coder, writer, researcher, etc.)
2. Start the gateway: openclaw gateway start
3. Send a message to any non-default agent via Telegram
4. Observe: bot shows "typing..." but never responds

Expected Behavior

All agents should process messages and respond normally.

Actual Behavior

Gateway logs show:

[telegram] handler failed: Error: Session file path must be within sessions directory

This error fires immediately on every inbound message for any agent that is not the DEFAULT_AGENT_ID.

Root Cause

In reply-B5GoyKpI.js, line 63597, inside runPreparedReply:

const sessionFile = resolveSessionFilePath(sessionIdFinal, sessionEntry);

This call passes no agentId and no sessionsDir. As a result, resolveSessionFilePath falls through to resolveAgentSessionsDir(DEFAULT_AGENT_ID) — always resolving to the main agent's sessions directory regardless of which agent is actually handling the message.

When the security check in resolvePathWithinSessionsDir (paths-B49s6UZQ.js, line 38) compares the resolved path against the agent's actual storePath, it detects a mismatch (the path is outside the expected sessions directory) and throws:

Error: Session file path must be within sessions directory

Relevant code path:

resolveSessionFilePath(sessionIdFinal, sessionEntry)
  → resolveSessionsDir(opts)           // opts has no agentId/sessionsDir
  → resolveAgentSessionsDir(DEFAULT_AGENT_ID)  // always "main"
  → returns /home/user/.openclaw/agents/main/sessions
  
// But storePath is /home/user/.openclaw/agents/coder/sessions/sessions.json
// path.dirname(storePath) = /home/user/.openclaw/agents/coder/sessions
// → security check fails → throws

Fix Applied

Passing the agentId from the session context resolves the issue:

// Before (line 63597):
const sessionFile = resolveSessionFilePath(sessionIdFinal, sessionEntry);

// After:
const sessionFile = resolveSessionFilePath(sessionIdFinal, sessionEntry, { agentId: params.agentId ?? sessionCtx?.AgentId });

This was applied as a manual patch to the dist file and confirmed working — all agents now respond correctly.

Impact

• Severity: Critical — affects all multi-agent deployments
• All agents except the default (main) are completely non-functional
• The error is silent from the user's perspective (only "typing..." is shown, no error message is delivered)
• Took several hours to diagnose due to the error occurring deep in the session resolution stack with no clear indication of which agent or path was involved

Additional Notes

• The doctor --fix command does not detect or resolve this issue
• Clearing sessions.json files does not help (the bug is in the path resolution logic, not stored data)
• The issue affects Telegram channel; other channels were not tested but likely affected as well
• The gateway otherwise starts and runs normally — openclaw gateway status shows healthy, RPC probe: ok

Environment

OpenClaw: 2026.2.12 (f9e444d)
Node.js: v22.22.0
OS: Ubuntu 24 (server)
Agents: main, coder, writer, researcher, clawma, reasoning, support, heartbeat
Channel: Telegram (polling mode)