Chrome Extension Relay Authentication Failing with 401 - Valid HMAC Token Rejected

Tue, 10 Mar 2026 00:00:00 +0000

Symptom

When attempting to connect the OpenClaw Chrome extension to the browser control server, authentication fails with 401 Unauthorized even when:

The gateway token is correctly configured
The HMAC-SHA256 token is properly derived using the documented formula: HMAC(gatewayToken, "openclaw-extension-relay-v1:{port}")
The correct port (18791 = Gateway + 2) is used

The extension options page displays the error: “Gateway token rejected. Check token and save again.”

Diagnostic Evidence

Direct API calls with derived HMAC tokens also fail:

HMAC-derived relay token

curl -H “x-openclaw-relay-token: 31ef63af71285c00acf36a78a3a33619a34b947fa99c4d8b149f5566b22d219f”
http://127.0.0.1:18791/json/version

Result: 401 Unauthorized

The browser control server is confirmed to be running: Browser control listening on http://127.0.0.1:18791/ (auth=token)

Root Cause Analysis

1. Server-Side HMAC Relay Authentication Not Implemented

The primary root cause appears to be that the browser control server does not implement HMAC relay token authentication. The server is configured with auth=token but only accepts the raw gateway Bearer token, not the HMAC-SHA256 derived relay tokens that the extension generates.

The extension correctly derives the relay token using: HMAC-SHA256(gatewayToken, “openclaw-extension-relay-v1:{port}”)

However, the server’s authentication middleware only validates Bearer tokens directly, failing to:

Recognize the x-openclaw-relay-token header format
Validate HMAC-derived tokens against the gateway token

2. Port Derivation Documentation Mismatch

There is a discrepancy between documentation and implementation:

Documentation states: Relay port = Gateway + 3 (e.g., 18789 + 3 = 18792)
Actual behavior: Server listens on Gateway + 2 (e.g., 18789 + 2 = 18791)

While the actual port (18791) works for connection, this inconsistency may cause confusion during troubleshooting.

3. Dual Installation Conflict (Contributing Factor)

The user performed a dual installation:

Installed via OpenClaw.app on February 9
Added CLI setup on February 13

This creates two separate state directories:

App state: ~/Library/Application Support/OpenClaw/
CLI state: ~/.openclaw/

Configuration stored in one location may conflict with the other, though the immediate authentication failure occurs regardless of which state directory is active.

Solution

Immediate Workaround

Use the raw gateway Bearer token instead of HMAC-derived token:

For direct API calls: curl -H “Authorization: Bearer fc001f30ef28a2a7e12f6f39e46ac4337cbfaff08c00585c”
http://127.0.0.1:18791/json/version

Note: This workaround may not resolve extension connectivity since the extension code specifically uses HMAC-derived tokens.

Verify Correct Port Configuration

The relay server listens on Gateway + 2, not Gateway + 3:

Gateway Port	Expected (Docs)	Actual (Server)
18789	18792	18791

Confirm your extension options use port 18791 (Gateway + 2).

Check Server Logs for Authentication Attempts

openclaw logs –level debug | grep -i “auth|relay|401|token”

Look for entries indicating whether the server received the x-openclaw-relay-token header and why it was rejected.

Verify Configuration File Location

Ensure you are editing the correct configuration file:

For CLI installation: cat ~/.openclaw/openclaw.json

For App installation: cat ~/Library/Application\ Support/OpenClaw/openclaw.json

Prevention

1. Use Single Installation Method

Avoid using both OpenClaw.app and CLI on the same system. Choose one installation method:

For GUI-focused usage: Use OpenClaw.app only
For CLI/developer usage: Use CLI installation only (npm install -g openclaw)

2. Document Your Installation Method

After installation, note which method was used and the associated configuration path:

CLI: ~/.openclaw/
App: ~/Library/Application Support/OpenClaw/

3. Verify Extension Relay Port

Before configuring the extension, verify the actual relay port by checking the server startup logs:

openclaw browser start

Look for: Browser control listening on http://127.0.0.1:XXXXX/

4. Validate Gateway Token Format

Ensure the gateway token:

Is 40+ characters (hex-encoded)
Does not contain typos
Matches exactly between config file and extension options

Additional Information

HMAC Token Derivation Reference

The Chrome extension derives relay tokens using this formula:

const relayToken = HMAC-SHA256( gatewayToken, openclaw-extension-relay-v1:${port} );

Where:

gatewayToken = The token from openclaw.json gateway config
port = Browser control server port (18791)

Expected Server Behavior

The browser control server should:

Accept Authorization: Bearer {gatewayToken} header (direct API access)
Accept x-openclaw-relay-token: {hmacDerivedToken} header (extension relay)
Validate HMAC tokens by deriving them server-side and comparing

Environment Details

Component	Version/Value
OpenClaw	2026.3.1 (2a8ac97)
Node.js	v22.22.0
OS	macOS (Darwin 25.3.0 arm64)
Gateway Port	18789
Relay Port	18791 (Gateway + 2)

Sources

GitHub Issue #32449

Authentication on FixClaw