【OpenClaw】权限放开与免授权配置排查手册

背景

在本地部署 OpenClaw 后，常见诉求是：

1. 访问 workspace 之外的文件时不要再被额外拦截
2. 执行本地命令时不要频繁出现授权确认
3. apply_patch 可以修改 workspace 外的文件
4. 已经显式放开权限后，运行时行为和预期保持一致

本文沉淀一次完整排查过程，重点覆盖 OpenClaw 在 2026 年 4 月观察到的一组容易混淆的权限边界。

典型现象

常见报错包括：

exec denied: allowlist miss

以及：

Approval required
Host: gateway

另一类现象是：

Config invalid
Problem:
  - agents.defaults: Unrecognized key: "tools"

还有一类容易被误判成权限问题，但实际是技能加载问题：

Skipping skill path that resolves outside its configured root.

先说结论

要让 OpenClaw 在宿主机上以低摩擦方式运行，至少要同时处理 4 层：

1. 关闭 agent 沙箱
2. 放开文件工具的 workspaceOnly
3. 放开 apply_patch 的 workspaceOnly
4. 显式配置 tools.exec.host/security/ask

仅修改 exec-approvals.json 不够。

根因拆解

1. agents.defaults.sandbox.mode=off 只表示不启用沙箱

这只决定是否存在 sandbox runtime，并不等价于：

• 所有命令默认都在宿主机无审批执行
• 文件工具默认可访问 workspace 外路径
• apply_patch 默认可写出 workspace

2. tools.fs.workspaceOnly 与 tools.exec.applyPatch.workspaceOnly 是单独的边界

即使沙箱关闭，下面两个限制仍可能生效：

tools: {
  fs: { workspaceOnly: true },
  exec: {
    applyPatch: { workspaceOnly: true }
  }
}

如果要访问或修改 workspace 外文件，需要显式改成 false。

3. 当前版本的隐式 exec 默认不是固定宿主机直通

这是最容易踩坑的一点。

当 tools.exec.host 未配置时，默认是：

host=auto

其行为是：

• 有 sandbox runtime 时，优先走 sandbox
• 没有 sandbox runtime 时，回落到 gateway

而 gateway 场景下，如果 tools.exec.security 和 tools.exec.ask 都没配置，默认值会落到：

security=allowlist
ask=on-miss

这就是已经关闭沙箱、也改了审批文件，但仍然报：

exec denied: allowlist miss

的根因。

4. exec-approvals.json 是宿主机审批策略，不等于 exec 默认行为

即便审批文件中已经是：

{
  "defaults": {
    "security": "full",
    "ask": "off"
  }
}

如果运行时 tools.exec.host/security/ask 仍走默认推导，实际效果仍可能先落到 gateway + allowlist + on-miss，从而出现和预期不一致的行为。

5. 配置改完后需要重启 gateway

磁盘上的配置与运行中的 gateway 不是同一回事。

如果修改了：

• ~/.openclaw/openclaw.json
• ~/.openclaw/exec-approvals.json

但没有重启 gateway，运行中的服务可能继续沿用旧值。

推荐配置

以下配置用于宿主机全放开场景。

注意：这意味着 agent 对本机拥有较大权限，仅适用于可信使用环境。

~/.openclaw/openclaw.json

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      sandbox: {
        mode: "off"
      }
    }
  },
  tools: {
    fs: {
      workspaceOnly: false
    },
    exec: {
      host: "gateway",
      security: "full",
      ask: "off",
      applyPatch: {
        workspaceOnly: false
      }
    }
  }
}

说明：

• workspace 是否修改取决于个人目录管理习惯，不是必须项
• tools.exec.host 必须显式写，避免落到 auto
• tools.exec.security/full + ask/off 必须一起写，避免继续走 allowlist

~/.openclaw/exec-approvals.json

{
  "version": 1,
  "defaults": {
    "security": "full",
    "ask": "off",
    "askFallback": "full"
  },
  "agents": {
    "main": {
      "security": "full",
      "ask": "off",
      "askFallback": "full",
      "allowlist": []
    }
  }
}

正确的排查顺序

第一步：确认当前配置文件值

openclaw config get agents
openclaw config get tools
openclaw config get tools.exec
openclaw approvals get

重点检查：

• agents.defaults.sandbox.mode
• tools.fs.workspaceOnly
• tools.exec.applyPatch.workspaceOnly
• tools.exec.host
• tools.exec.security
• tools.exec.ask

第二步：确认 gateway 实际加载的是哪份配置

openclaw gateway status

关注输出中的：

• Config (cli)
• Config (service)

两者应指向同一份目标配置文件。

第三步：重启 gateway 让新配置生效

openclaw gateway restart

第四步：再次确认运行时配置

openclaw config get tools.exec
openclaw gateway status

如果此时 tools.exec.host/security/ask 已经是目标值，但行为仍不符合预期，再去看日志。

第五步：查看日志

tail -n 200 /tmp/openclaw/openclaw-$(date +%F).log

重点搜索：

allowlist miss
Approval required
Skipping skill path that resolves outside its configured root

常见误区

误区 1：把 tools 写到 agents.defaults 下

错误示例：

{
  agents: {
    defaults: {
      tools: {
        fs: { workspaceOnly: false }
      }
    }
  }
}

这会直接触发 schema 错误：

agents.defaults: Unrecognized key: "tools"

正确做法是把 tools 写在顶层，或写到 agents.list[].tools 的具体 agent 上。

误区 2：以为 task:* 会自动变成异步任务

task 只是 session key 命名，不是调度开关。

真正的后台异步任务要通过：

• sessions_spawn
• ACP runtime
• background exec
• cron

等显式机制触发。

误区 3：把技能加载失败当成 exec 权限失败

如果日志中出现：

Skipping skill path that resolves outside its configured root.

说明是技能目录解析边界问题，而不是 exec 审批问题。

典型场景是：

• ~/.openclaw/workspace/skills/<skill> 是一个软链
• 实际目标指向 workspace 外目录

这类问题需要调整技能放置方式，而不是继续改 exec 权限。

误区 4：把系统级授权弹窗和 OpenClaw 审批混为一谈

如果弹窗来自操作系统本身，例如桌面目录、下载目录、完整磁盘访问，这不是 OpenClaw 的 exec approvals 能解决的问题，需要在系统权限侧单独授权。

一套最小可执行命令

openclaw config set agents.defaults.sandbox.mode off
openclaw config set tools.fs.workspaceOnly false
openclaw config set tools.exec.applyPatch.workspaceOnly false
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart
openclaw config get tools.exec
openclaw approvals get

适用边界

这套方案适合：

• 单人本机使用
• 对宿主机执行权限有明确掌控
• 需要频繁访问 workspace 外项目目录
• 希望 coding agent 低摩擦执行脚本、读写代码、打补丁

不适合：

• 多人共享聊天入口
• 对外开放群聊
• 不可信输入直接触发工具执行
• 希望保留严格审计和逐次审批的环境

最终建议

如果目标是“本机个人 coding assistant”，建议直接显式固定：

tools.exec.host=gateway
tools.exec.security=full
tools.exec.ask=off
tools.fs.workspaceOnly=false
tools.exec.applyPatch.workspaceOnly=false
agents.defaults.sandbox.mode=off

如果目标是“多人共享或对外暴露”，则不应该使用这套配置，应保留：

• allowlist
• on-miss
• sandbox
• workspaceOnly

等保护边界。