#21622: fix(gateway): include read/write in CLI default operator scopes
gateway
size: XS
experienced-contributor
Cluster:
Device Pairing and Gateway Fixes
## Summary
- **Problem:** `CLI_DEFAULT_OPERATOR_SCOPES` only included `admin`, `approvals`, and `pairing` — missing `read` and `write`
- **Why it matters:** Localhost auto-pair granted only those 3 scopes, so any subsequent CLI operation requiring `operator.read` or `operator.write` triggered a scope-upgrade check and failed with "pairing required" (with no one to approve on localhost)
- **What changed:** Added `READ_SCOPE` and `WRITE_SCOPE` to `CLI_DEFAULT_OPERATOR_SCOPES`
- **What did NOT change (scope boundary):** No gateway auth logic, pairing flow, or scope enforcement was modified — only the default set of scopes requested during CLI connections
## Change Type (select all)
- [x] Bug fix
- [ ] Feature
- [ ] Refactor
- [ ] Docs
- [ ] Security hardening
- [ ] Chore/infra
## Scope (select all touched areas)
- [x] Gateway / orchestration
- [ ] Skills / tool execution
- [x] Auth / tokens
- [ ] Memory / storage
- [ ] Integrations
- [ ] API / contracts
- [ ] UI / DX
- [ ] CI/CD / infra
## Linked Issue/PR
- Closes #21593
## User-visible / Behavior Changes
Localhost auto-pair now grants all 5 operator scopes (`admin`, `read`, `write`, `approvals`, `pairing`). Commands like `openclaw devices list`, `openclaw status`, sub-agent spawning, and cron jobs no longer fail with "pairing required" after a fresh install.
## Security Impact (required)
- New permissions/capabilities? `No` — read/write scopes were already designed to be part of the CLI operator set; they were accidentally omitted
- 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 (localhost gateway)
- Runtime/container: Node
- Relevant config: default loopback gateway
### Steps
1. `openclaw devices clear --yes && openclaw gateway restart`
2. Device auto-pairs on localhost
3. Run `openclaw status` or `openclaw devices list`
### Expected
Commands succeed without "pairing required" error.
### Actual (before fix)
`gateway closed (1008): pairing required`
## Evidence
- [x] Failing test/log before + passing after
- Added regression test: `CLI_DEFAULT_OPERATOR_SCOPES` must contain all 5 scopes
## Human Verification (required)
- Verified scenarios: new test asserts all 5 scopes present; existing method-scopes tests pass (8/8)
- Edge cases checked: `authorizeOperatorScopesForMethod` already treats `admin` as super-scope; adding `read`/`write` is additive and non-breaking
- What you did **not** verify: full end-to-end localhost pairing flow (requires running gateway)
## Compatibility / Migration
- Backward compatible? `Yes`
- Config/env changes? `No`
- Migration needed? `No` — existing paired devices may need `openclaw devices clear --yes && openclaw gateway restart` to re-pair with updated scopes
## Failure Recovery (if this breaks)
- How to disable/revert this change quickly: revert the 2-line addition in `method-scopes.ts`
- Known bad symptoms: if scopes are over-granted, worst case is that a CLI session can call read/write methods it could already call via admin scope
## Risks and Mitigations
- Risk: Existing paired devices retain old scope set until re-paired
- Mitigation: users who hit #21593 already need to `openclaw devices clear` as a workaround; this fix prevents the issue on fresh pairs going forward
---
🤖 Generated with Claude Code
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Added `operator.read` and `operator.write` to `CLI_DEFAULT_OPERATOR_SCOPES` in src/gateway/method-scopes.ts:14-20. This fixes localhost auto-pairing which previously only granted `admin`, `approvals`, and `pairing` scopes, causing "pairing required" errors when CLI operations needed read/write access. The regression test in src/gateway/method-scopes.test.ts:55-63 now verifies all 5 scopes are present.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The change is a simple 2-line addition to a constant array, adding missing scopes that were already defined and tested elsewhere. The `authorizeOperatorScopesForMethod` function (src/gateway/method-scopes.ts:176-194) already treats `admin` as a super-scope that allows all operations, so adding `read` and `write` is purely additive and non-breaking. The new test ensures all 5 scopes are present, and existing authorization tests continue to pass.
- No files require special attention
<sub>Last reviewed commit: f0e227e</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#21476: fix(cli): include operator.read in default CLI scopes
by heyrtl · 2026-02-20
91.9%
#22583: fix(gateway): add operator.write to scope hierarchy (#22574)
by lailoo · 2026-02-21
87.4%
#17195: fix: Add operator.read/write scopes to Dashboard auto-pairing
by MisterGuy420 · 2026-02-15
86.4%
#17425: fix(gateway): auto-approve scope/role upgrades for already-paired d...
by sauerdaniel · 2026-02-15
85.5%
#12802: fix(gateway): default unscoped operator connections to read-only
by yubrew · 2026-02-09
84.7%
#22712: fix(gateway): auto-approve all device pairing for localhost connect...
by NewdlDewdl · 2026-02-21
84.1%
#22666: fix(gateway): operator.admin should imply all operator scopes
by maximveksler · 2026-02-21
84.0%
#17127: fix(webchat): include operator.read and operator.write in connect s...
by brandonwise · 2026-02-15
83.9%
#23708: fix(gateway): auto-approve scope upgrades for loopback clients
by widingmarcus-cyber · 2026-02-22
83.4%
#21666: fix(gateway): restrict auto-paired device scopes to safe defaults
by AI-Reviewer-QS · 2026-02-20
82.8%