#21476: fix(cli): include operator.read in default CLI scopes
gateway
size: XS
Cluster:
Device Pairing and Gateway Fixes
Fixes #21470
## Summary
- **Problem**: CLI auto-paired with only `operator.admin`, `operator.approvals`, `operator.pairing` — missing `operator.read`
- **Why it matters**: Commands like `openclaw cron list`, `openclaw gateway status` failed with "pairing required"
- **What changed**: Added `READ_SCOPE` to `CLI_DEFAULT_OPERATOR_SCOPES` constant
- **What did NOT change**: No config/API changes, backward compatible
## Change Type
- [x] Bug fix
## Scope
- [x] Gateway / orchestration
- [x] Auth / tokens
## Linked Issue/PR
- Closes #21470
## User-visible / Behavior Changes
**Before**: Fresh `openclaw gateway install` → CLI commands fail with "pairing required"
**After**: CLI auto-pairs with full operator scopes → all commands work immediately
## Security Impact
- New permissions/capabilities? **No** (just fixing missing default scope)
- Secrets/tokens handling changed? **No**
- New/changed network calls? **No**
- Command/tool execution surface changed? **No**
- Data access scope changed? **No**
## Repro + Verification
### Environment
- OS: macOS 26.2 (Apple Silicon - arm64)
- Runtime: Homebrew at `/opt/homebrew/`, Node v22.14.0
- Gateway mode: local loopback
### Steps
1. Fresh `openclaw gateway install`
2. Run `openclaw cron list` or `openclaw gateway status`
3. **Before**: Error: "pairing required"
4. **After**: Commands work ✅
### Expected
CLI commands should work immediately after install on loopback connections
### Actual
Commands failed due to missing `operator.read` scope
## Evidence
- [x] Code logic verified (one-line addition)
- [x] Scope definition aligns with method requirements in `METHOD_SCOPE_GROUPS`
**Code change**:
```diff
export const CLI_DEFAULT_OPERATOR_SCOPES: OperatorScope[] = [
ADMIN_SCOPE,
+ READ_SCOPE,
APPROVALS_SCOPE,
PAIRING_SCOPE,
];
```
## Human Verification
- Code compiles
- Logic verified: CLI now gets read scope by default
- Aligns with method scope requirements
## Compatibility / Migration
- Backward compatible? **Yes**
- Config/env changes? **No**
- Migration needed? **No**
Existing paired devices unaffected. New CLI pairings get correct scopes.
## Failure Recovery
**Revert**: Remove `READ_SCOPE,` line from `CLI_DEFAULT_OPERATOR_SCOPES`
**Symptoms**: CLI commands fail with "pairing required" (original issue)
## Risks and Mitigations
**Risk**: None identified. This adds a missing scope that should have been there.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds `READ_SCOPE` to `CLI_DEFAULT_OPERATOR_SCOPES` to fix CLI commands that require read permissions. Commands like `openclaw cron list` and `openclaw gateway status` were failing with "pairing required" errors because the CLI was auto-paired without read scope.
The fix is minimal and correct:
- `READ_SCOPE` includes methods like `cron.list`, `cron.status`, `status`, and other read-only operations (lines 43-75)
- The CLI default scopes now match the intended behavior: admin, read, approvals, and pairing
- `WRITE_SCOPE` was intentionally excluded from defaults (appropriate for CLI security)
- No changes to API, backward compatible with existing paired devices
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with no risk
- Single-line fix adds a missing required scope to the CLI defaults. The change is well-understood, properly scoped, and fixes a clear bug. The authorization logic already handles `READ_SCOPE` correctly, and the scope system is well-defined with explicit method-to-scope mappings.
- No files require special attention
<sub>Last reviewed commit: 916f594</sub>
<!-- greptile_other_comments_section -->
<sub>(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#21622: fix(gateway): include read/write in CLI default operator scopes
by zerone0x · 2026-02-20
91.9%
#17195: fix: Add operator.read/write scopes to Dashboard auto-pairing
by MisterGuy420 · 2026-02-15
83.1%
#17425: fix(gateway): auto-approve scope/role upgrades for already-paired d...
by sauerdaniel · 2026-02-15
82.5%
#17127: fix(webchat): include operator.read and operator.write in connect s...
by brandonwise · 2026-02-15
81.6%
#22583: fix(gateway): add operator.write to scope hierarchy (#22574)
by lailoo · 2026-02-21
81.5%
#22712: fix(gateway): auto-approve all device pairing for localhost connect...
by NewdlDewdl · 2026-02-21
80.9%
#23039: fix: subagent announce fails with pairing required due to missing o...
by ascott · 2026-02-21
80.4%
#17753: fix: Control UI unusable over HTTP - missing scopes
by MisterGuy420 · 2026-02-16
80.2%
#21664: fix(gateway): require re-pairing for legacy devices that lack scope...
by AI-Reviewer-QS · 2026-02-20
79.4%
#21666: fix(gateway): restrict auto-paired device scopes to safe defaults
by AI-Reviewer-QS · 2026-02-20
79.2%