Skip to content

README.md

Latest commit

 

History

History
77 lines (65 loc) · 3.29 KB

README.md

File metadata and controls

77 lines (65 loc) · 3.29 KB

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)