A specialized maintenance skill for diagnosing and repairing Matrix communication channel issues within Openclaw Skills environments.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install matrix-fix
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install matrix-fix using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Matrix Channel Repair (matrix-fix)?
The matrix-fix skill is a dedicated troubleshooting toolkit designed to address common technical hurdles encountered when using Matrix as a communication layer. It focuses on resolving high-impact issues such as missing encryption modules, invalid access tokens (M_UNKNOWN_TOKEN), and DNS resolution failures that can take your AI agents offline. By providing a structured set of recovery procedures, this utility ensures that Openclaw Skills maintain persistent and secure connections to their designated homeservers.
This skill is essential for developers maintaining long-running bots that require End-to-End Encryption (E2EE) and stable session management. It provides clear, actionable steps to rebuild native modules and refresh authentication states without losing core agent functionality.
Matrix Channel Repair (matrix-fix) Use Cases
- Resolving E2EE (End-to-End Encryption) initialization errors and missing crypto node modules.
- Refreshing expired or invalid access tokens to restore bot connectivity after a session timeout.
- Reconfiguring homeserver settings, user IDs, and device names after a server migration or update.
- Mass-leaving rooms to reset bot state or clear unnecessary message listeners.
- Diagnosing connection status and probing channel health using Openclaw Skills CLI tools.
How Matrix Channel Repair (matrix-fix) Works
- Identification: The user or agent detects a failure in the Matrix channel, such as encryption warnings or authentication errors.
- Diagnosis: Run diagnostic commands like openclaw channels status --probe to pinpoint if the failure is at the network, auth, or module level.
- Module Repair: If encryption fails, the skill guides the installation and rebuilding of the native crypto-nodejs package within the installation directory.
- Authentication Reset: For token errors, the skill clears local account caches and triggers a fresh login flow to obtain a new access token.
- Configuration Update: Users can reset or update homeserver details via CLI commands to ensure correct routing to the Matrix API.
- Verification: Restart the gateway and monitor filtered logs to confirm the Matrix channel is fully operational within the Openclaw Skills ecosystem.
Matrix Channel Repair (matrix-fix) Setup
To fix encryption and initialization issues within your Openclaw Skills environment, execute the following commands in your terminal:
# Navigate to the Openclaw installation
cd /usr/local/lib/node_modules/openclaw
# Install and rebuild the crypto module
pnpm add @matrix-org/matrix-sdk-crypto-nodejs
pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs
# Restart the gateway to apply changes
openclaw gateway restart
To clear invalid tokens:
rm -rf ~/.openclaw/matrix/accounts/*
openclaw gateway restart
Matrix Channel Repair (matrix-fix) Data Schema & Taxonomy
The matrix-fix skill interacts with the local configuration and credential storage used by Openclaw Skills. The following table describes the data components managed:
| Component | Path / Key | Description |
|---|---|---|
| Accounts Cache | ~/.openclaw/matrix/accounts/* |
Stores local session tokens and device identification data. |
| Config Key | channels.matrix |
The root configuration object containing homeserver URL and credentials. |
| Encryption Module | @matrix-org/matrix-sdk-crypto-nodejs |
Native node module required for secure E2EE communication. |
| Log Stream | openclaw logs |
Source of truth for debugging ENOTFOUND and M_UNKNOWN_TOKEN errors. |
Matrix Channel Repair (matrix-fix) Advanced Features
- Automated Gateway Restart: Quickly cycle the gateway service via CLI to apply new configurations instantly.
- Deep Channel Probing: Advanced connectivity testing that validates both network reachability and API responsiveness.
- Scripted Room Management: Automation templates for managing room memberships and bot access tokens via the Matrix Client-Server API.
- Targeted Telemetry: Integrated log filtering to isolate Matrix-specific events for faster debugging of Openclaw Skills.
SKILL.md
Loading
Related Openclaw Skills
Xiaohongshu Data API
A specialized skill for programmatically fetching public Xiaohongshu posts, trending topics, and user data via the TikHub API.
V2Ray Proxy Manager
An automated utility for managing V2Ray proxy services and system-wide proxy settings via the command line.
Super Self-Improving Agent
An advanced AI agent skill that uses multi-modal memory and feedback loops to continuously optimize performance through meta-learning.
Polymarket Agent
An autonomous AI trading assistant that analyzes Polymarket data and real-world news to identify and execute profitable prediction market opportunities.
BKMRK
BKMRK is an AI-driven bookmarking tool that analyzes content like YouTube transcripts and GitHub repos to score their relevance to your specific coding projects.
TOON Context Compression
A specialized CLI utility that transforms JSON data into the TOON format to achieve approximately 40% savings in token context usage.
Featured*
