Troubleshooting#

OpenClaw includes built-in tools to help diagnose and resolve common problems. The doctor command is your starting point for most issues. It identifies risky direct message policies, configuration validation failures, port collisions, plugin load errors, auth problems, and pairing drift. Many of these can be fixed automatically with the fix option. You can also use specific commands for plugins, configuration, nodes, and pairing to address targeted problems. For background on how sessions and channels work, see the concepts page.

The gateway refuses to start#

Symptom: The gateway command fails to start or reports errors on launch, such as validation problems or port issues.

Cause: This typically stems from invalid configuration, port collisions with other applications, or inconsistencies left after an upgrade or source installation.

Fix: Run the doctor command with the fix option. It repairs the last-known-good configuration, corrects prefixed or clobbered entries, and resolves certain runtime issues. After the repair completes, try starting the gateway again. For persistent problems, consider checking your environment for conflicting services using the same port.

Direct messages from unknown senders are ignored#

Symptom: You send a message to the agent in a channel but receive no response, especially from new contacts.

Cause: By default, the direct message policy is set to require pairing. Unknown senders receive a short code and the agent does not process the message until approved. This protects against untrusted input.

Fix: Approve the sender with the pairing approve command, specifying the channel and the code. You can change the policy to allowlist or open if appropriate for your use case, and configure allowFrom lists for control. Always run the doctor command to check for risky direct message configurations.

The agent cannot connect to models due to auth errors#

Symptom: Agent turns fail with messages about missing or expired credentials.

Cause: Auth profiles may lack valid credentials, tokens may have expired, or the order of profiles may exclude usable ones for the provider.

Fix: Probe your setup with the models status command using the probe option. This reports stable reason codes for issues like missing credentials or expired tokens. Add or update profiles as needed. The doctor command can help with auth drift and related problems.

Plugins do not load or their features are missing#

Symptom: Installed plugins do not appear in lists or their tools and channels are not functional.

Cause: Plugin load errors during startup, incomplete installation from external sources, or activation planning issues can prevent features from becoming available.

Fix: Use the plugins inspect command to review the status of a specific plugin and any reported errors. Reinstall the plugin using the install command if problems are found. The doctor command surfaces plugin load errors and compatibility advisories.

Companion nodes fail to connect or show capabilities#

Symptom: Nodes do not list in the interface or cannot execute commands like voice or screen capture.

Cause: New nodes require explicit pairing approval. Device tokens may be invalid, or the connection may not have completed the handshake with role and capability declarations.

Fix: Use the nodes commands to list nodes, request pairing, approve or reject requests, and verify. The gateway issues device tokens on successful pairing. Refresh the surface on the node side if capabilities are outdated. Non-local connections always require approval.

Configuration updates do not take effect#

Symptom: Changes made with configuration commands are not reflected in behavior.

Cause: Validation may fail silently on some entries, or the gateway process needs to be restarted to pick up updates.

Fix: Retrieve current values with the config get command to confirm they are set. Run the doctor command with the fix option to address validation failures. Restart the gateway after making changes to ensure they load properly.

If these steps do not resolve your issue, consult the FAQ for more details or review the common tasks guide.