matrix-fix_skill

This skill fixes Matrix Channel issues by guiding crypto module installation, token refresh, reconfiguration, and status checks to restore normal operation.

Python

2.6k

GitHub Stars

2

Bundled Files

2 months ago

Catalog Refreshed

3 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill openclaw/skills --skill matrix-fix

_meta.json278 B
SKILL.md3.0 KB

Overview

This skill fixes common issues with the Matrix channel: missing crypto modules, expired tokens, DNS resolution, and misconfiguration. It provides step-by-step recovery actions and commands to reset credentials, reinstall crypto dependencies, and reconfigure the channel. The guidance targets Matrix integrations running under the OpenClaw gateway environment.

How this skill works

The skill inspects runtime errors and log messages, then suggests targeted shell commands to resolve the underlying cause. It covers installing the Node.js crypto dependency, clearing stale access tokens, verifying DNS connectivity, fully reconfiguring the Matrix channel, and forcing the bot to leave rooms when needed. Diagnostic commands are included to validate success and check channel status.

When to use it

The Matrix channel fails to initialize or shows E2EE/crypto errors.
You see M_UNKNOWN_TOKEN or other access token authentication errors.
DNS lookups for the homeserver fail (ENOTFOUND).
The bot behaves incorrectly and you need to reset its Matrix configuration.
You need the bot to leave all joined rooms or verify channel health.

Best practices

Back up any existing Matrix account directory before removing tokens or config.
Use the homeserver FQDN and test DNS with host/ping before reconfiguring.
Rebuild native crypto modules after installing them to ensure node bindings load.
Restart the gateway after each config or dependency change to apply settings.
Limit password and token exposure by running commands in a secure shell.

Example use cases

Resolve 'Cannot find module @matrix-org/matrix-sdk-crypto-nodejs' by installing and rebuilding the package and restarting the gateway.
Fix M_UNKNOWN_TOKEN by removing stored account tokens then restarting the gateway to force a fresh login.
Diagnose homeserver name resolution with host and ping, then correct DNS or endpoint configuration.
Perform a full Matrix channel reset: unset old config, set homeserver/user/device/encryption fields, and restart the gateway.
Force the bot to leave rooms by obtaining an access token, listing joined rooms, and issuing leave requests.

FAQ

Removing locally stored tokens only forces reauthentication. It does not delete server-side message history, but device-specific encryption keys stored locally could affect E2EE sync.

Do I need to rebuild after installing the crypto module?

Yes. Rebuilding ensures native bindings are compiled and available to the running Node.js environment.

What if DNS checks succeed but the gateway still fails?

Confirm the homeserver URL, port, and TLS settings in the channel config, check gateway logs for specific errors, and verify network/firewall rules between the host and homeserver.