gateway-token-doctor

What This Skill Does

The gateway-token-doctor skill acts as an automated diagnostic and remediation utility for the OpenClaw ecosystem. Its primary function is to detect and resolve authentication failures commonly signaled by 401 Unauthorized errors. These errors frequently stem from desynchronized token configurations across the three critical surfaces of the OpenClaw architecture: the local configuration file (openclaw.json), the remote gateway settings, and the environment-level service variables. By performing a comprehensive audit of these disparate storage locations, the tool identifies discrepancies, prompts or performs alignment, and enforces a single source of truth for the token. This process eliminates the tedious manual verification typically required to troubleshoot authentication drift, ensuring that the CLI, UI, and backend services remain consistently authenticated.

Installation

To integrate the gateway-token-doctor into your environment, use the OpenClaw package manager. Ensure your terminal has sufficient privileges to modify local configuration files within the home directory.

Command: clawhub install openclaw/skills/skills/dalomeve/gateway-token-doctor

Once installed, the tool adds a diagnostic layer that can be invoked whenever the CLI reports auth failures or when gateway connectivity drops unexpectedly.

Use Cases

This skill is essential in scenarios involving complex environment deployments or manual configuration updates. Common use cases include:

• Recovery after service restarts that resulted in silent authentication degradation.
• Troubleshooting '401 Unauthorized' errors occurring during CLI interactions.
• Resolving authentication failures triggered by stale configuration files after an OpenClaw version upgrade.
• Ensuring consistent auth states during automated script executions where environment variables might collide with local file configurations.

Example Prompts

1. "OpenClaw is throwing a 401 error every time I try to run a command. Can you use the gateway-token-doctor to check my auth setup?"
2. "I just updated my gateway config but now the service won't start. Please diagnose and fix my token mismatch."
3. "Run a full audit of my gateway credentials and ensure the CLI and service tokens are synced correctly."

Tips & Limitations

• Safety First: The skill is designed to redact sensitive information in logs by showing only the first four characters of tokens. Never transmit full token strings in unprotected environments.
• Scope: This tool operates specifically on local configuration files and environment variables. It does not interface with external identity providers or third-party SSO providers.
• Verification: Always run the post-fix verification workflow. If 401 errors persist after alignment, check your system logs for network-level issues or potential clock skew on the host machine.