LLM Wiki

Appearance

Built 26/04/16 06:15commit dacb639

OpenClaw Cron Pairing And Operator Scopes ​

中文 | English

Summary ​

Cron creation can fail even when the gateway is up and the machine looks otherwise healthy. In one real OpenClaw setup, the actual problem was not cron itself but insufficient paired-device operator scopes, which caused the gateway to reject cron operations with a pairing-flavored close reason.

Symptom ​

Cron operations such as cron(action="status") or job creation failed with:

text
gateway closed (1008): pairing required

This was easy to misread as an incomplete pairing flow or a broken cron subsystem.

Root Cause ​

The failure was caused by an operator-scope mismatch on the runtime identity that actually talked to the gateway. The machine already had pairing data, but the effective client was gateway-client, and its granted scopes were too narrow for cron actions. That made the gateway reject the request with a pairing-flavored close reason even though pairing had already happened.

A second trap was that updating only the paired-device record was not enough in this setup. The runtime also carried its own local auth view in identity/device-auth.json, so the effective scopes could still stay stale after paired.json was edited.

How To Confirm ​

  • Inspect ~/.openclaw/identity/device.json to identify the runtime device and client actually used by the local OpenClaw process.
  • Inspect ~/.openclaw/identity/device-auth.json to see the scopes currently attached to that runtime identity.
  • Inspect ~/.openclaw/devices/paired.json and confirm the matching paired-device record for the same device or client.
  • Verify whether the runtime identity is gateway-client or some other client instead of assuming the active device is the UI-facing entry you edited first.
  • If the device looks paired but cron still returns gateway closed (1008): pairing required, treat runtime-scope mismatch as a prime suspect.

Fix ​

Update both the paired-device record and the runtime auth record for the actual gateway client so they agree on the full operator set needed for cron management:

  • operator.read
  • operator.write
  • operator.admin
  • operator.pairing
  • operator.approvals

In the reproduced setup, that meant fixing the gateway-client entry in ~/.openclaw/devices/paired.json and the matching runtime scopes in ~/.openclaw/identity/device-auth.json, not just editing a different paired device such as openclaw-control-ui.

After both records matched, cron(action="status") worked again and cron jobs could be created normally.

Operational Lesson ​

A pairing-related gateway close message does not always mean "this device is unpaired". In practice it can mean "the runtime client is paired but under-scoped for the requested operator action", and the decisive record may live in both paired state and runtime auth state.