PR #59963: fix(telegram): keep inbound images readable on upgraded installs

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59963

Description (problem / solution / changelog)

Summary

• Problem: Telegram image attachments can fail on upgraded installs where the active state dir still resolves to the legacy ~/.clawdbot tree while inbound media is saved under ~/.openclaw/media.
• Why it matters: the hardened local-media allowlist rejects the saved image path, so Telegram photo-only turns can fail before the image reaches media understanding or the model.
• What changed: src/media/local-roots.ts now trusts the managed config-dir media cache in addition to the active state-dir roots, and src/media/local-roots.test.ts adds a regression test for the legacy/new dir split.
• What did NOT change (scope boundary): this does not widen local media reads beyond OpenClaw-managed directories and does not change Telegram download behavior itself.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• 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

• Closes #59956
• Related #59956
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: inbound media writes already target resolveConfigDir()/media, but the local-media allowlist only trusted roots derived from resolveStateDir(). On upgraded installs those can diverge (~/.clawdbot vs ~/.openclaw), so the just-saved Telegram image path was treated as outside the allowed roots.
• Missing detection / guardrail: there was no regression coverage for the legacy-state/new-config split in media local-root resolution.
• Prior context (git blame, prior PR, issue, or refactor if known): the user report in #59956 points at the 2026.4.x hardening changes; this fix stays in the hardened path and narrows the compatibility gap instead of weakening the policy.
• Why this regressed now: stricter local-media path validation made the state-dir/config-dir mismatch observable for Telegram inbound images.
• If unknown, what was ruled out: ruled out Telegram getFile/download failures because the failing path is after media save and before media understanding/model handoff.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/media/local-roots.test.ts
• Scenario the test should lock in: a legacy state dir and new config dir can diverge, but inbound media must still be readable from the managed config-dir media cache.
• Why this is the smallest reliable guardrail: the bug is in local-root resolution, so the direct root-merging test covers the exact regression without adding a heavier Telegram harness dependency.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Telegram image/photo turns on upgraded installs with legacy state-dir layouts can reach media understanding/model processing again instead of failing early.

Diagram (if applicable)

Before:
Telegram photo -> save under ~/.openclaw/media -> allowlist trusts ~/.clawdbot roots only -> attachment read blocked -> request fails

After:
Telegram photo -> save under ~/.openclaw/media -> allowlist trusts managed state-dir + config-dir media roots -> attachment read succeeds -> request proceeds

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 24 / pnpm workspace
• Model/provider: N/A for the regression test
• Integration/channel (if any): Telegram
• Relevant config (redacted): upgraded install with legacy state dir still resolving to ~/.clawdbot

Steps

1. Start from an upgraded install where resolveStateDir() still resolves to the legacy state tree.
2. Receive a Telegram photo so inbound media is saved under the managed config-dir media cache.
3. Process the turn through the hardened local-media allowlist path.

Expected

• The saved inbound image remains readable and the turn proceeds to media understanding/model handling.

Actual

• The saved path is rejected as outside allowed roots, which can fail the turn before the model sees the image.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: ran pnpm test -- src/media/local-roots.test.ts and pnpm check; confirmed the new regression test passes and the repo check gate is green.
• Edge cases checked: verified the merged roots still keep the state-dir workspace/sandbox roots and only add the managed config-dir media cache.
• What you did not verify: I did not run a live Telegram bot roundtrip against a real upgraded account in this environment.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: trusting the wrong extra root could widen local reads more than intended.
  • Mitigation: the added root is limited to the managed config-dir media cache only; workspace and sandbox trust still stays anchored to the active state dir.

Made with Cursor

Changed files

• src/media/local-roots.test.ts (modified, +22/-0)
• src/media/local-roots.ts (modified, +19/-9)

PR #59971: fix(telegram): keep inbound images readable on upgraded installs

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/59971

Description (problem / solution / changelog)

Summary

• Problem: Telegram image attachments can fail on upgraded installs where the active state dir still resolves to the legacy ~/.clawdbot tree while inbound media is saved under ~/.openclaw/media.
• Why it matters: the hardened local-media allowlist rejects the saved image path, so Telegram photo-only turns can fail before the image reaches media understanding or the model.
• What changed: src/media/local-roots.ts now trusts the managed config-dir media cache in addition to the active state-dir roots, and src/media/local-roots.test.ts adds a regression test for the legacy/new dir split.
• What did NOT change (scope boundary): this does not widen local media reads beyond OpenClaw-managed directories and does not change Telegram download behavior itself.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• 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

• Closes #59956
• Related #59956
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: inbound media writes already target resolveConfigDir()/media, but the local-media allowlist only trusted roots derived from resolveStateDir(). On upgraded installs those can diverge (~/.clawdbot vs ~/.openclaw), so the just-saved Telegram image path was treated as outside the allowed roots.
• Missing detection / guardrail: there was no regression coverage for the legacy-state/new-config split in media local-root resolution.
• Prior context (git blame, prior PR, issue, or refactor if known): the user report in #59956 points at the 2026.4.x hardening changes; this fix stays in the hardened path and narrows the compatibility gap instead of weakening the policy.
• Why this regressed now: stricter local-media path validation made the state-dir/config-dir mismatch observable for Telegram inbound images.
• If unknown, what was ruled out: ruled out Telegram getFile/download failures because the failing path is after media save and before media understanding/model handoff.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/media/local-roots.test.ts
• Scenario the test should lock in: a legacy state dir and new config dir can diverge, but inbound media must still be readable from the managed config-dir media cache.
• Why this is the smallest reliable guardrail: the bug is in local-root resolution, so the direct root-merging test covers the exact regression without adding a heavier Telegram harness dependency.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Telegram image/photo turns on upgraded installs with legacy state-dir layouts can reach media understanding/model processing again instead of failing early.

Diagram (if applicable)

Before:
Telegram photo -> save under ~/.openclaw/media -> allowlist trusts ~/.clawdbot roots only -> attachment read blocked -> request fails

After:
Telegram photo -> save under ~/.openclaw/media -> allowlist trusts managed state-dir + config-dir media roots -> attachment read succeeds -> request proceeds

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 24 / pnpm workspace
• Model/provider: N/A for the regression test
• Integration/channel (if any): Telegram
• Relevant config (redacted): upgraded install with legacy state dir still resolving to ~/.clawdbot

Steps

1. Start from an upgraded install where resolveStateDir() still resolves to the legacy state tree.
2. Receive a Telegram photo so inbound media is saved under the managed config-dir media cache.
3. Process the turn through the hardened local-media allowlist path.

Expected

• The saved inbound image remains readable and the turn proceeds to media understanding/model handling.

Actual

• The saved path is rejected as outside allowed roots, which can fail the turn before the model sees the image.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: ran pnpm test -- src/media/local-roots.test.ts and pnpm check; confirmed the regression test passes and the repo check gate is green after addressing the prior review note on the test.
• Edge cases checked: verified the merged roots still keep the state-dir workspace/sandbox roots and only add the managed config-dir media cache.
• What you did not verify: I did not run a live Telegram bot roundtrip against a real upgraded account in this environment.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: trusting the wrong extra root could widen local reads more than intended.
  • Mitigation: the added root is limited to the managed config-dir media cache only; workspace and sandbox trust still stays anchored to the active state dir.

Made with Cursor

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/media/local-roots.test.ts (modified, +17/-0)
• src/media/local-roots.ts (modified, +19/-9)