collective-memory-repo/shared/long-term/lessons/openclawd-ops-lessons.md

OpenClaw Ops Lessons (Imported)

• imported_from: /Users/lingyuzeng/openclawd/vaults/memory/lessons.md
• imported_at_utc: 2026-03-10T07:53:38Z
• note: migrated from openclawd/vaults to collective-memory-repo.

---

memory/lessons.md

[HIGH] 多机架构唯一 Gateway 约束

• 结论: Gateway 只能在 mac-5；其他节点一律 Node Host。
• 风险: 在 mac-6/7/8 启动 Gateway 会导致控制面冲突和排障复杂化。
• 应对: 统一通过 mac-5 控制面 + openclaw nodes run 调度。

[MEDIUM] 节点接入失败排查顺序

• 结论: 先看 token，再看 pairing，再看 allowlist。
• 错误关键词: unauthorized / pairing required / approval required。

[HIGH] Exec 批准授权系统完整配置（2026-03-16 实战验证）

问题现象

• openclaw nodes run --raw "npm -v" 等远程命令被拦截
• Control UI 弹出 Exec approval needed，显示 Security: allowlist / Ask: on-miss
• 即使节点本地 exec-approvals.json 已设为 security: "full" + ask: "off"，仍然弹窗

根因

OpenClaw 的 exec 审批有两个配置面，必须同时配置才能生效：

1. Gateway 侧（mac-5）：~/.openclaw/openclaw.json 中的 tools.exec.* 和 approvals.exec.*
2. Node 侧（mac-6/7）：~/.openclaw/exec-approvals.json

Gateway 侧没有显式配置时，tools.exec.ask 默认为 "on-miss"，不会继承 node 侧 exec-approvals.json 的设置。这导致请求在到达 node 之前就被 gateway 拦截弹窗。

解决方案

必须修改的文件一：mac-5 ~/.openclaw/openclaw.json

在 tools 块中添加：

{
  "tools": {
    "exec": {
      "security": "full",
      "ask": "off"
    }
  },
  "approvals": {
    "exec": {
      "enabled": false
    }
  }
}

• tools.exec.security: "full" — 本机 exec 完全放行
• tools.exec.ask: "off" — 不弹审批提示（关键！默认 "on-miss" 会弹窗）
• approvals.exec.enabled: false — 禁用整个 exec 审批流程

必须修改的文件二：各节点 ~/.openclaw/exec-approvals.json

{
  "version": 1,
  "defaults": {
    "security": "full",
    "ask": "off",
    "askFallback": "full",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "full",
      "ask": "off",
      "askFallback": "full",
      "autoAllowSkills": false,
      "allowlist": [
        { "pattern": "/bin/sh" },
        { "pattern": "/bin/bash" },
        { "pattern": "/bin/zsh" },
        { "pattern": "/opt/homebrew/bin/*" },
        { "pattern": "/usr/bin/*" },
        { "pattern": "/bin/*" },
        { "pattern": "/usr/local/bin/*" },
        { "pattern": "/opt/homebrew/Cellar/*/*/bin/*" }
      ]
    }
  }
}

关键字段说明：

字段	推荐值	说明
defaults.security	"full"	默认放行所有命令
defaults.ask	"off"	不弹审批提示
defaults.askFallback	"full"	UI 不可达时也放行
agents.main.security	"full"	main agent 放行
agents.main.askFallback	"full"	不要用 "deny"，否则 fallback 到 defaults 时可能被拒

allowlist 条目保留为文档记录，即使 security: "full" 时不需要匹配白名单。

修改后必须重启

# mac-5 gateway
openclaw gateway restart

Node 侧 exec-approvals.json 通过 Gateway RPC 热更新，通常不需要重启 node。但如果问题持续，重启 node：

openclaw node restart

管理命令

# 查看 node 当前审批配置
openclaw approvals get --node "Executor Node (mac-6)"
openclaw approvals get --node "Browser Node (mac-7)"

# 从文件批量写入配置
openclaw approvals set --node "Executor Node (mac-6)" --file ./approvals.json

# 单条添加白名单
openclaw approvals allowlist add --node "Executor Node (mac-6)" "/opt/homebrew/bin/*"

# CLI 需要 gateway 可达（注意 tailnet bind 问题时用 --url 和 --token）
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 openclaw approvals get --node "..." --url ws://100.64.0.19:18789 --token "<token>"

/bin/sh -lc shell wrapper 问题

nodes run --raw "npm install ..." 实际启动的是 /bin/sh -lc "npm install ..."。 即使 security: "full"，shell wrapper 形式会触发额外的安全绑定检查： SYSTEM_RUN_DENIED: approval cannot safely bind this interpreter/runtime command

Workaround：在 allowlist 中加入 /bin/sh、/bin/bash、/bin/zsh 精确条目。 但根因仍是 gateway 侧配置缺失，修好 tools.exec 后不再触发。

排查清单

1. 检查 mac-5 openclaw.json 是否有 tools.exec.ask: "off"
2. 检查 mac-5 openclaw.json 是否有 approvals.exec.enabled: false
3. 检查 node 侧 exec-approvals.json 的 defaults 和 agents.main 是否统一为 full/off
4. 重启 gateway
5. 先测简单命令 /usr/bin/uname -a，再测 shell wrapper 形式
6. 观察 Control UI 弹窗中的 effective policy 是否变为 full/off

相关 OpenClaw 配置文件路径

文件	位置	作用
Gateway 主配置	~/.openclaw/openclaw.json (mac-5)	全局配置，含 tools.exec / approvals
Node exec 审批	~/.openclaw/exec-approvals.json (各节点)	节点本地执行审批策略
acpx 配置	~/.acpx/config.json	acpx CLI 全局配置
opencode 配置	~/.config/opencode/opencode.json	opencode 权限配置
Gemini 配置	~/.gemini/settings.json	gemini CLI 设置