Fix CLI Device Scope

修复 OpenClaw CLI 设备权限不足导致 subagent/spawn/cron 等操作被拒绝的问题。 触发词: pairing required, spawn失败, cron失败, 设备权限不足, admin scope, 死循环, CLI设备, scope不足。 当 spawn subagent 报...

Security Scan

The skill's code and runtime instructions are coherent with its stated purpose (repairing OpenClaw CLI device scopes) and do not call out to unexpected external endpoints, but it modifies local auth files and can generate elevated tokens — run with care and prefer dry-run and manual confirmation.

Purpose & Capability

The name/description match the actual behavior: all scripts diagnose, update, and verify OpenClaw device scope state stored under ~/.openclaw. Reading and updating paired.json, device-auth.json, and pending.json is expected to implement the described fix.

Instruction Scope

SKILL.md instructs running diagnose.py, fix.py (with --dry-run and interactive confirmation), and verify.py. The scripts do exactly that: they run local `openclaw` CLI commands and read/write files under the OpenClaw config directory. This is within scope, but the fix script writes new operator tokens and edits auth state — a sensitive operation that the skill documents and mitigates by default with a dry-run and an interactive confirmation prompt.

Install Mechanism

No install spec; this is instruction + script-only. Nothing is downloaded or installed from external sources, so there is no installer-related risk.

Credentials

The skill requests no environment variables and no external credentials. It does require filesystem access to ~/.openclaw (paired.json, device-auth.json, pending.json) and will overwrite those files — that is proportionate to the stated task but is high-sensitivity access because it modifies authentication tokens and approved scopes.

Persistence & Privilege

The skill does not request persistent platform privileges (always:false), but it can create new operator-admin tokens and persist them to device-auth.json and paired.json. Because platform agents may invoke skills autonomously (disable-model-invocation is false by default), an autonomous invocation combined with the script's --force option could escalate the local agent's privileges without manual confirmation. The SKILL.md and code default to interactive confirmation (dry-run / prompt), mitigating this risk if run by a human.

Assessment

This skill appears to do what it claims: diagnose and repair OpenClaw CLI device scope problems by editing OpenClaw config files under ~/.openclaw. Before using it: (1) review the scripts yourself (they are included); (2) always run python3 scripts/fix.py --dry-run first to see exactly what will change; (3) keep backups of paired.json and device-auth.json (the script also creates .bak files); (4) do not run with --force unless you trust the environment and intent; (5) be aware the script generates and writes a new operator-admin token — treat those files as sensitive; (6) if you are worried about automated/agent invocation, disable autonomous invocation for this skill or only invoke it manually so a human can confirm changes.

修复 OpenClaw CLI 设备 scope 权限不足导致的配对失败。

症状

sessions_spawn error: gateway closed (1008): pairing required
[tools] cron failed: gateway closed (1008): pairing required

同时确认：

• openclaw gateway status 显示 gateway running
• openclaw devices list 显示 CLI 设备 Paired 但 scopes 只有 operator.read，没有 admin

---

快速诊断

一行命令输出完整诊断：

python3 scripts/diagnose.py

输出示例（需要修复）：

=== CLI Device Scope 诊断 ===

✓ Gateway 正在运行
  设备 ID:    2f5c98cfd06a980cb20ca1217580e6d8be7df78034a278b0fdaf81a9d8ac99c5
  当前 scopes: ['operator.read']
  pending:    1 repair 请求

⚠️  需要修复：CLI 设备缺少 admin scope
   死循环：当前只有 read，无法 approve 自己的升级请求

修复命令：
  python3 scripts/fix.py --dry-run  # 先预览
  python3 scripts/fix.py            # 执行修复

---

核心原因

Gateway 设备的 scope 太低（只有 operator.read），而 subagent spawn / cron 等操作需要 operator.admin。有一个 repair pending 请求在队列里等着升级 scope，但当前 token 权限不够 approve 不了——死循环：

需要 admin scope → 才能 approve → admin scope 申请

---

⚠️ 检查点：修复前确认

执行修复脚本前，必须先展示将要改动的配置，等待用户确认：

# 先用 --dry-run 看改动（不执行写入）
python3 scripts/fix.py --dry-run

# 输出示例：
# Device: 2f5c98cf...
# Current scopes: ['operator.read']
# New scopes: ['operator.admin', 'operator.read', 'operator.write', ...]
# Files to modify:
#   - paired.json
#   - device-auth.json
#   - pending.json (cleanup)
#
# ❓ Proceed? [y/N]:

用户确认后才执行：

python3 scripts/fix.py  # 默认会先展示再询问
python3 scripts/fix.py --force  # 跳过确认（仅限自动化场景）

---

验证修复

# 重启 gateway 加载新 scope
openclaw gateway restart

# 等待 ~5 秒后测试 spawn

用 sessions_spawn 工具验证，应该返回 status: accepted。

---

预防措施

• 修改前先备份 paired.json.bak 和 device-auth.json.bak
• 确认 DEVICE_ID 是要修的设备（看 clientId=cli 且 platform=linux）
• 不要删除其他正常设备的 paired 记录
• 修复后建议 openclaw doctor --fix 检查整体健康状态

---

注意事项

• 必须重启 gateway 才能加载新 scopes
• 新 token 格式 cli_admin_<random>，每次修复会更新
• 如果 gateway 从旧备份恢复，旧 token 会重新生效，需重新修复
• 没有 pending repair 请求的情况下，可手动构造 full_scopes 列表写入（['operator.admin', 'operator.read', 'operator.write', 'operator.approvals', 'operator.pairing', 'operator.talk.secrets']）