[neekolas]

Summary

• Problem: XMTP extension lacked support for media attachments and owner auto-pairing
• Why it matters: Users need to share files/images and have reliable owner communication
• What changed: Added attachment handling, owner address auto-pairing, and improved documentation formatting
• What did NOT change: Core XMTP message handling and DM policy architecture

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

• Closes #

User-visible / Behavior Changes

• Added support for receiving XMTP attachments (images, files)
• New ownerAddress configuration option for auto-pairing with the bot owner
• Improved documentation formatting with proper spacing and table alignment

Security Impact (required)

• New permissions/capabilities? (Yes)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (Yes)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: The extension now downloads and processes attachments from XMTP messages, but uses the existing media handling pipeline with proper validation. Owner auto-pairing creates a DM channel on startup but follows existing security policies.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node.js
• Model/provider: N/A
• Integration/channel: XMTP
• Relevant config: ownerAddress: "0x123..."

Steps

1. Configure XMTP with an owner address
2. Start the gateway
3. Send an attachment from the owner's wallet
4. Verify the attachment is received and processed

Expected

• Owner DM is automatically created on startup
• Attachments are properly downloaded, saved, and presented to the agent

Actual

• Owner DM is created and ready for communication
• Attachments are processed and available to the agent

Evidence

• Trace/log snippets

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Owner auto-pairing, attachment reception from both DMs and group chats
• Edge cases checked: Invalid attachments, owner address format variations
• What you did not verify: Performance with very large attachments

Compatibility / Migration

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

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Remove ownerAddress from config
• Files/config to restore: ~/.openclaw/openclaw.json (XMTP section)
• Known bad symptoms reviewers should watch for: Errors in logs about attachment processing

Risks and Mitigations

• Risk: Malicious attachments could be sent
  • Mitigation: Uses existing media pipeline with proper validation and sandboxing

[neekolas]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Update fly.io config #28
• Refactor XMTP Extension And Fix Bugs #27
• Add ENS resolution design doc for XMTP extension #26
• Add full media support and owner address #25 👈 (View in Graphite)
• Add reactions support and account autocreation #24
• feat(xmtp): add XMTP extension with type fixes for current API #23
• Get up to date with OpenClaw main #22
• staging

This stack of pull requests is managed by Graphite. Learn more about stacking.

[macroscopeapp]

Add inbound XMTP media handling and auto-pair DMs with configured owner wallet address across extensions/xmtp

Add attachment and inline-attachment handlers, wire media metadata through the inbound pipeline, register media events in startup, and include ownerAddress in config, account resolution, DM policy, onboarding, and setup.

📍Where to Start

Start with startAccount in gateway-lifecycle.ts, then review buildAttachmentHandler/buildInlineAttachmentHandler and the inbound save paths in handleInboundAttachment/handleInboundInlineAttachment in channel.ts, followed by media propagation in runInboundPipeline in inbound-pipeline.ts.

---

Macroscope summarized 088f1dc.

[github-actions]

⚠️ Formal models conformance drift detected

The formal models extracted constants (generated/*) do not match this openclaw PR.

This check is informational (not blocking merges yet).
See the formal-models-conformance-drift artifact for the diff.

If this change is intentional, follow up by updating the formal models repo or regenerating the extracted artifacts there.