# 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` 块中添加：

```json
{
  "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`

```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"` 时不需要匹配白名单。

#### 修改后必须重启

```bash
# mac-5 gateway
openclaw gateway restart
```

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

```bash
openclaw node restart
```

#### 管理命令

```bash
# 查看 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 设置 |