picoclaw/docs/channels/matrix

Back to README

Matrix Channel Configuration Guide

1. Example Configuration

Add this to config.json:

{
  "channel_list": {
    "matrix": {
      "enabled": true,
      "type": "matrix",
      "homeserver": "https://matrix.org",
      "user_id": "@your-bot:matrix.org",
      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
      "device_id": "",
      "join_on_invite": true,
      "allow_from": [],
      "group_trigger": {
        "mention_only": true
      },
      "placeholder": {
        "enabled": true,
        "text": ["Thinking...", "Processing...", "Typing..."]
      },
      "reasoning_channel_id": "",
      "message_format": "richtext",
      "crypto_database_path": "",
      "crypto_passphrase": "YOUR_MATRIX_CRYPTO_PICKLE_KEY"
    }
  }
}

2. Field Reference

Field	Type	Required	Description
enabled	bool	Yes	Enable or disable the Matrix channel
homeserver	string	Yes	Matrix homeserver URL (for example https://matrix.org)
user_id	string	Yes	Bot Matrix user ID (for example @bot:matrix.org)
access_token	string	Yes	Bot access token
device_id	string	No	Optional Matrix device ID
join_on_invite	bool	No	Auto-join invited rooms
allow_from	[]string	No	User whitelist (Matrix user IDs)
group_trigger	object	No	Group trigger strategy (mention_only / prefixes)
placeholder	object	No	Placeholder message config (see below)
reasoning_channel_id	string	No	Target channel for reasoning output
message_format	string	No	Output format: "richtext" (default) renders markdown as HTML; "plain" sends plain text only
crypto_database_path	string	No	Path to store the crypto database (uses workspace path ~/.picoclaw/workspace if empty)
crypto_passphrase	string	No	Serialization key for encrypting session keys in the database; must remain unchanged once set

Placeholder Config

Field	Type	Required	Description
enabled	bool	No	Enable placeholder messages (default: false)
text	string/[]string	No	Placeholder text(s). Can be a single string or array of strings. If multiple texts are provided, one is randomly selected at runtime. Default: "Thinking..."

3. Currently Supported

• Text message send/receive with markdown rendering (bold, italic, headers, code blocks, etc.)
• Configurable message format (richtext / plain)
• Incoming image/audio/video/file download (MediaStore first, local path fallback)
• Incoming audio normalization into existing transcription flow ([audio: ...])
• Outgoing image/audio/video/file upload and send
• Group trigger rules (including mention-only mode)
• Typing state (m.typing)
• Placeholder message + final reply replacement
• Auto-join invited rooms (can be disabled)
• End-to-end encryption (E2EE) support for encrypted messages

4. TODO

• Rich media metadata improvements (for example image/video size and thumbnails)