Bug type

Crash (process/app exits or hangs)

Beta release blocker

No

Summary

I've been getting consistent timeout errors when OpenClaw is running tool calls, even with a good gateway connection. I've had OpenClaw try to diagnose itself. These were the findings:

Still the same error. Even with allowInsecureAuth=false, it's still requiring pairing. This confirms that there's something fundamentally different about how tools try to connect vs how webchat connects.

Final Conclusion based on what we've learned:

The Gateway is working correctly (webchat connections succeed) Tools are failing due to a WebSocket handshake/pairing issue that's specific to the tool-layer authentication flow We've tried: restarts, config updates, credential files, disabling insecure auth, doctor command The pairing system (openclaw pairing) shows no pending requests, suggesting it's not about an unapproved inbound request but rather an incomplete device registration or handshake process Recommendation: The issue appears to be a deeper authentication flow bug in OpenClaw's tool layer. You have two options:

Use webchat directly - Your control UI is already connected and working, so just manually check in every 30-60 minutes File an issue with OpenClaw maintainers - Report this "pairing required" error when using tool-layer APIs (cron, sessions_send, etc.) vs successful webchat connections For now, since the cron job won't work, let me update your reminder file with final conclusions and recommendations.

Steps to reproduce

🐛 Reproduction Report: Tool-Layer Pairing Authentication Error Issue OpenClaw tool-layer APIs (cron, sessions_send, etc.) fail with "pairing required" authentication error, even though webchat connections work fine.

Steps to Reproduce Start OpenClaw Gateway:

Copy openclaw gateway start Verify Gateway is running:

Copy openclaw gateway status Expected: Gateway shows as "running" on ws://127.0.0.1:18789

Attempt to create a cron job (any operation):

Copy openclaw cron add --job '{"name":"test","schedule":{"kind":"every","everyMs":180000},"payload":{"kind":"systemEvent","text":"test"},"sessionTarget":"current"}' Observe error:

Copy Status: error Error: "gateway closed (1008): pairing required" Gateway target: ws://127.0.0.1:18789 Source: local loopback Config: ~/.openclaw/openclaw.json Bind: loopback Expected vs Actual Expected: Cron job created successfully via tool API Actual: Authentication error with "pairing required" message despite Gateway being operational and webchat connections working Environment Details OpenClaw version: 2026.4.2 (d74a122) Model: lmstudio-anthropic/qwen/qwen3.5-9b Gateway bind: loopback (127.0.0.1:18789) Auth mode: token with 07ba66920affb68f034bfe9eeb95c98094cdfa534879963e Device ID in logs: 8ea7d3c379f5f5e4017ff3f45a078e53e3ada7f775e3e50526b325680b8aaecd Control UI authentication: allowInsecureAuth=false (set to false after testing) Related Logs From \tmp\openclaw\openclaw-2026-04-05.log:

Copy "gateway connect failed: GatewayClientRequestError: pairing required" "cause": "pairing-required", "reason": "scope-upgrade" Attempts Made (All Failed) Multiple gateway restarts ✓ Created credentials directory with auth token ✓ Removed allowInsecureAuth=true flag ✓ Fixed config.yml syntax errors ✓ Ran openclaw doctor --fix ✓ Tried different session keys/labels ✓ Workarounds Implemented Manual webchat messages - Send message every 30-60 min via control UI (works) Task Scheduler health monitor - Logs Gateway status every 3 min (working, but doesn't prevent timeout) Created files: heartbeat-minimal.ps1 - Working health check script ✅ HEARTBEAT-SETUP-README.md - Task Scheduler setup guide SOLUTION-HEARTBEAT-README.md - Complete solution document Root Cause Theory (Based on Logs) The logs show "scope-upgrade" error with device pairing authentication. Webchat connections succeed because they bypass the tool-layer authentication flow. The tool APIs appear to require a different type of device pairing that isn't being triggered properly.

Request Investigate why tool-layer WebSocket handshakes fail while webchat succeeds Check if there's a missing device pairing step or incomplete registration Verify session authentication flow differs between tools vs webchat Consider exposing REST API endpoints for heartbeat/session-pinging (404 errors observed)

Expected behavior

🎯 Expected Behavior Report: OpenClaw Tool-Layer Authentication What SHOULD Work (Current Broken State) Create cron jobs via tool API

Copy openclaw cron add ... Expected: Cron job created and scheduled Actual: Fails with "gateway closed (1008): pairing required"

Send messages to sessions via sessions_send

Copy sessions_send(label="agent:main:main", message="test") Expected: Message sent successfully to session Actual: Fails with "gateway closed (1008): pairing required" or "No session found"

Spawn persistent sessions

Copy sessions_spawn(runtime="subagent", task="...") Expected: Session spawned and running Actual: Fails with same pairing error

Session health monitoring via HTTP API

Copy Invoke-RestMethod -Uri "http://127.0.0.1:18789/webchat/messages" ... Expected: HTTP endpoint responds with 200 OK Actual: Returns 404 Not Found (endpoint doesn't exist)

What SHOULD Work (Currently Working) Webchat connections from control UI ✓

Manual message sending via webchat client works WebSocket handshake succeeds Tool invocations through webchat work normally Gateway status and health checks ✓

Copy openclaw gateway status Expected: Gateway shows "running" on port 18789 ✓ Actual: Matches expected behavior ✓

Tool-layer WebSocket discovery ✓

Gateway correctly identifies and manages sessions Session list returns correct data ✓ Memory operations work through webchat ✓ Authentication Flow Comparison Operation Connection Type Auth Method Status Webchat from control UI WebSocket Token + Device Pairing ✅ Working Cron via tool API WebSocket (direct) Token only ❌ Fails sessions_send via tool WebSocket (direct) Token only ❌ Fails HTTP REST endpoints HTTP POST Token only ❌ 404 Not Found Security Implications Current config: allowInsecureAuth=false (disabled after testing) Token configured: 07ba66920affb68f034bfe9eeb95c98094cdfa534879963e Device pairing required for tools: Logs show "scope-upgrade" and device ID authentication attempts failing Acceptance Criteria (What We Want) ✅ Gateway running on ws://127.0.0.1:18789 ✅ Token-based authentication working ❌ Tool-layer APIs accessible via cron/sessions_send/spawn ❌ Session heartbeat/ping prevention enabled (currently disabled due to auth issue) ✅ Manual webchat session management available Success Metrics Short-term success:

All tool-layer operations succeed without "pairing required" error HTTP REST API endpoints accessible for programmatic access Long-term success:

Automated heartbeat cron job preventing session timeouts No manual intervention needed to keep sessions alive External tools/SDKs can interact with OpenClaw programmatically This clarifies what should work vs what's currently failing due to the authentication layer issue.

Actual behavior

⚠️ Actual Behavior Report: OpenClaw Tool-Layer Authentication What's BROKEN (Actual State) Create cron jobs via tool API ❌

Copy openclaw cron add ... Result:

Send messages to sessions ❌

Copy sessions_send(label="agent:main:main", message="test") Result:

Sometimes fails with "No session found" (invalid request) Often fails with same "pairing required" error Spawn persistent sessions ❌

Copy sessions_spawn(runtime="subagent", task="...") Result: Same pairing authentication failure

HTTP REST API endpoints ❌

Copy Invoke-RestMethod -Uri "http://127.0.0.1:18789/webchat/messages" ... Result:

Copy The remote server returned an error: (404) Not Found Session health monitoring via HTTP ✅ (partial workaround)

Copy Invoke-RestMethod -Uri "http://127.0.0.1:18789/status" -Method GET Result: Returns 200 OK but no useful data for session ping

Error Patterns Observed Error code: 1008 (GatewayClientRequestError) Error message: "gateway closed (1008): pairing required" Cause in logs: "pairing-required", "reason": "scope-upgrade" Device ID: 8ea7d3c379f5f5e4017ff3f45a078e53e3ada7f775e3e50526b325680b8aaecd

Logs Evidence (From \tmp\openclaw\openclaw-2026-04-05.log) What Actually Works Webchat from control UI ✅

All operations work normally WebSocket connections succeed Tool invocations through webchat succeed Gateway startup and status ✅

Copy openclaw gateway start/status Gateway runs on ws://127.0.0.1:18789 Probe returns "ok" Listener detected on port 18789 Session discovery ✅ (but not usage)

Copy sessions_list() Returns session list correctly But cannot use sessions_send with these keys Health monitor script ✅ (limited utility)

Copy powershell -File heartbeat-minimal.ps1 Confirms Gateway is running Logs to heartbeat-logs.txt Does NOT prevent timeout or send heartbeats Authentication Flow Reality Operation Result Reason Webchat WebSocket handshake ✅ Succeeds Proper device pairing, auth flow working Tool-layer WebSocket (cron) ❌ Fails at 1008 ms Missing pair/authentication step HTTP REST calls ❌ 404 Endpoints don't exist or require different auth Actual State Summary Gateway: Running normally ✅ Token config: Valid and loaded ✅ Device pairing for tools: MISSING/FAILED ❌ HTTP API availability: INCOMPLETE (some work, most return 404) ❌ Tool-layer functionality: BLOCKED by authentication layer ❌ This shows the actual behavior without idealization - the tool layer is fundamentally blocked despite Gateway being operational.

OpenClaw version

2026.4.2

Operating system

Windows 11

Install method

npm global

Model

qwen/qwen3.5-9b

Provider / routing chain

Custom - LM studio

Additional provider/model setup details

🤖 Model & Provider Configuration Current Setup (From ~/.openclaw/openclaw.json) Primary Model:

ID: lmstudio-anthropic/qwen/qwen3.5-9b Alias: qwen3.5b Provider: Custom lmstudio provider API Provider: anthropic-messages (Anthropic-style message format) Model Configuration:

Context & Token Settings Context Window: 190,000 tokens (configured) Max Tokens: 262,144 tokens (hard limit) Provider Mode: merge (multiple providers can merge responses) Reasoning enabled: false Cost Settings Input cost: $0.00 per token Output cost: $0.00 per token Cache read: $0.00 Cache create: $0.00 Estimated total session cost: $0.00 USD (local model) Provider Details Local LMStudio Server:

Host: http://192.168.0.183:1234 API Version: /v1 (OpenAI-compatible endpoint) Model ID in server: qwen/qwen3.5-9b Authentication:

API Key: lmstudio (placeholder for local access) Protocol: HTTP/HTTPS (not WebSocket) Model Capabilities Based on the qwen3.5-9b model:

✅ Text generation ✅ Tool calling (via anthropic-messages format) ✅ System prompts ✅ Context window up to 190K tokens ❌ Real-time audio/image processing (not configured in provider settings) Current Session Stats (From logs) Note: The model configuration is working fine - the issue is isolated to the Gateway tool-layer authentication, not the model provider itself.

Logs, screenshots, and evidence

📋 Log Evidence Report: Tool-Layer Pairing Failure
Critical Error Snippets
1. Tool-Cron Authentication Failure:

2. Error Summary:

Copy
gateway connect failed: GatewayClientRequestError: pairing required
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: C:\\Users\\dtrou\\.openclaw\\openclaw.json
Bind: loopback
3. Device Access Scope Upgrade Requested:

4. Successful Webchat vs Failed Tools:

Copy
// Webchat (SUCCESS):
"webchat connected conn=ebc71e5d-82eb-4df2-afb6-b83e841d896b remote=127.0.0.1 client=openclaw-control-ui webchat vcontrol-ui"

// Cron tool (FAIL):
"[tools] cron failed: gateway closed (1008): pairing required\nGateway target: ws://127.0.0.1:18789\nSource: local loopback"
Successful Operations (Evidence Gateway Works)
Gateway Running:

Copy
{"subsystem":"gateway"},"1":{"logLevelId":3,"logLevelName":"INFO","name":"{\"subsystem\":\"gateway\"}"},
"time":"2026-04-05T17:19:25.495-05:00"}

Gateway status shows:
- Runtime: running (pid 14940)
- Listener detected on port 18789
- Probe target: ws://127.0.0.1:18789
- RPC probe: ok
Session Discovery Works:

Copy
"webchat connected conn=cd999400-b605 remote=127.0.0.1 client=openclaw-control-ui"
"channels.status\" res=OK"
Configuration State
openclaw.json Gateway Config:

HTTP API Status (Evidence of Missing Endpoints)
Session Ping Attempts:

Copy
// Direct session endpoint:
"The remote server returned an error: (404) Not Found"

// Webchat messages endpoint:
"The remote server returned an error: (404) Not Found"

// Heartbeat endpoint:
"The remote server returned an error: (404) Not Found"

// Only status works:
"http://127.0.0.1:18789/status" → 200 OK (but minimal data)
Health Monitor Logs (Created During Testing)
heartbeat-minimal.ps1 Results:

Copy
Starting session health check...
Gateway check passed! Status:
Session health check complete at 2026-04-05 12:40:21
This log evidence confirms Gateway is operational but tool-layer authentication fails while webchat succeeds, indicating a missing device pairing step or incomplete WebSocket handshake flow for tools.

Impact and severity

No response

Additional information

No response