9999e3c668
- shared/long-term/lessons: OpenClaw exec 批准授权系统完整配置经验 - daily/2026-03-16: CLI安装、exec配置、待办记录 - daily/2026-03-15: 之前未提交的日志 - shared/long-term/decisions/acp-agents-integration.md - agents/openclaw-main: claude-switch/mcp 相关记录
162 lines
5.4 KiB
Markdown
162 lines
5.4 KiB
Markdown
# 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 设置 |
|