Gateway Token Doctor

Diagnose and fix gateway token mismatches causing 401 errors. Align tokens across config, service, and CLI surfaces.

Security Scan

The skill's purpose and actions align (it reads/writes OpenClaw config and restarts the gateway), but the runtime instructions modify local config and startup scripts without safety checks and reference an environment variable that the metadata does not declare — proceed only after backing up files and reviewing the steps.

Purpose & Capability

The name/description match the actions in SKILL.md: auditing and aligning gateway tokens stored in $HOME/.openclaw/openclaw.json, the gateway startup script, and the OPENCLAW_GATEWAY_TOKEN environment variable. Asking to read and update those files is coherent with the stated purpose.

Instruction Scope

Instructions directly read and overwrite $HOME/.openclaw/openclaw.json and $HOME/.openclaw/gateway.cmd and then restart the gateway. There are no safety measures (no backups, no validation of a non-empty token, no dry-run). Regex replacement ('OPENCLAW_GATEWAY_TOKEN=.*') and writing token values directly can accidentally clobber files or inject malformed values. Verification steps reference logs generically ('Select-String "401" logs') without specifying paths. These are functional for the task but risky and insufficiently defensive.

Install Mechanism

This is an instruction-only skill with no install spec and no code files. Nothing is written to disk by an installer, which is the lowest-risk install profile.

Credentials

The SKILL.md reads the OPENCLAW_GATEWAY_TOKEN environment variable and other local config paths, but the registry metadata lists no required env vars. That mismatch reduces transparency. While the env var and files are relevant to the stated purpose, the skill asks to read and overwrite local configuration and a startup script — privileges that should be clearly declared and confirmed with the user beforehand.

Persistence & Privilege

The skill does not request permanent presence (always:false) and does not include installation steps that persist beyond execution. Autonomous invocation is enabled by default on the platform, but this skill does not escalate privileges beyond modifying only OpenClaw-related files.

What to consider before installing

This skill will read and overwrite your OpenClaw config (~/.openclaw/openclaw.json) and edit the gateway startup script (~/.openclaw/gateway.cmd), then restart the gateway. Before using it: 1) Back up the files mentioned (copy openclaw.json and gateway.cmd). 2) Inspect openclaw.json to confirm where tokens are stored and that the auth token is valid (the script uses auth => remote => service). 3) Run the steps manually first (don't run them as a blind script) or add a dry-run that prints intended changes without writing. 4) Ensure the openclaw CLI is present and you can restart the gateway manually. 5) Be aware that SKILL.md reads the OPENCLAW_GATEWAY_TOKEN env var even though metadata lists no env requirements — confirm any environment-token source before letting the skill modify files. 6) After changes, verify logs and CLI auth in a controlled environment (staging) before applying in production. If you are not comfortable with file edits or service restarts, ask an admin to perform these steps.

Diagnose and fix 401 errors from token mismatches.

Problem

Gateway token inconsistencies cause:

• 401 Unauthorized errors
• CLI/UI authentication failures
• Service startup failures
• Silent auth degradation

Workflow

1. Token Audit

# Check all token surfaces
$cfg = Get-Content "$HOME/.openclaw/openclaw.json" -Raw | ConvertFrom-Json
$auth = $cfg.gateway.auth.token
$remote = $cfg.gateway.remote.token
$service = $env:OPENCLAW_GATEWAY_TOKEN

"auth.token   = $auth"
"remote.token = $remote"
"service.token = $service"

if ($auth -and $remote -and $auth -ne $remote) {
    Write-Warning "Token mismatch: auth != remote"
}

2. Alignment Fix

# Generate or use existing token
$token = $auth

# Update config
$cfg.gateway.auth.token = $token
$cfg.gateway.remote.token = $token
$cfg | ConvertTo-Json -Depth 10 | Out-File "$HOME/.openclaw/openclaw.json" -Encoding UTF8

# Update service startup script
$servicePath = "$HOME/.openclaw/gateway.cmd"
$content = Get-Content $servicePath -Raw
$content = $content -replace 'OPENCLAW_GATEWAY_TOKEN=.*', "OPENCLAW_GATEWAY_TOKEN=$token"
$content | Out-File $servicePath -Encoding UTF8

# Restart
openclaw gateway restart

3. Verification

# Test gateway access
openclaw gateway status

# Test CLI auth
openclaw whoami

Executable Completion Criteria

Criteria	Verification
All tokens aligned	auth == remote == service
Gateway responds	openclaw gateway status succeeds
CLI auth works	openclaw whoami returns user
No 401 in logs	Select-String "401" logs returns nothing

Privacy/Safety

• Never log actual token values
• Redact tokens in output (show first 4 chars only)
• Store tokens only in config files

Self-Use Trigger

Use when:

• 401 errors appear
• Gateway restart after config change
• CLI shows auth mismatch
• Service fails to start

---

Align tokens. Restore access.