openclaw.json 配置、安全与权限说明

先说重点

OpenClaw 的安全与权限不是一个开关，而是三层：

1. sandbox：决定工具在哪里运行

2. tool policy：决定哪些工具能用

3. elevated + approvals：决定是否允许高风险宿主机执行

官方参考

• Sandboxing: https://docs.openclaw.ai/sandboxing
• Sandbox CLI: https://docs.openclaw.ai/sandbox/
• Sandbox vs Tool Policy vs Elevated: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated
• Exec Approvals: https://docs.openclaw.ai/tools/exec-approvals
• Config CLI: https://docs.openclaw.ai/cli/config
• Security: https://docs.openclaw.ai/zh-CN/gateway/security

openclaw.json 在哪里

本机路径：

C:\Users\PC\.openclaw\openclaw.json

当前本机主要内容：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.3-codex"
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token"
    }
  }
}

Warning

真实文件中还有 Gateway token。这个 token 属于敏感信息，不能公开分享。

openclaw.json 主要管什么

你可以把它理解成 OpenClaw 的主配置文件，主要负责：

• Gateway 模式和鉴权
• 默认模型
• 智能体默认行为
• 工具策略
• 沙箱策略
• 浏览器、节点、渠道等运行参数

常用命令：

openclaw config get gateway
openclaw config get agents.defaults
openclaw config set gateway.mode local

Note

openclaw config set 的值按 JSON5 解析；改完配置后通常需要重启 Gateway。

你当前配置里每一块是什么意思

gateway

你当前是：

• gateway.mode = local
• gateway.auth.mode = token

含义：

• local：Gateway 以本机方式运行
• token：Control UI / 客户端连接 Gateway 时必须带 token

agents.defaults.model

你当前是：

• primary = openai-codex/gpt-5.3-codex

含义：

• 默认 agent 回答时优先走 Codex 模型

commands

你当前是：

• native = auto
• nativeSkills = auto
• restart = true
• ownerDisplay = raw

这块更偏命令执行和显示行为，不是核心安全边界。

安全围栏的三层模型

第一层：Sandbox

关键字段：

• agents.defaults.sandbox.mode
• agents.defaults.sandbox.scope
• agents.defaults.sandbox.workspaceAccess

常见值：

• mode: "off"：不使用沙箱，工具直接跑宿主机
• mode: "non-main"：只有非主会话进沙箱
• mode: "all"：所有会话都进沙箱

workspaceAccess：

• "none"：最严，只给沙箱自己的工作目录
• "ro"：把 agent workspace 只读挂进去
• "rw"：把 agent workspace 可读写挂进去

第二层：Tool Policy

关键字段：

• tools.allow
• tools.deny
• tools.sandbox.tools.allow
• tools.sandbox.tools.deny
• agents.list[].tools.*

规则：

• deny 优先级最高
• 如果 allow 非空，未列入的工具默认禁用
• 开了 sandbox 也不会让 deny 的工具重新可用

第三层：Elevated + Approvals

关键字段：

• tools.elevated.enabled
• tools.elevated.allowFrom.<provider>
• tools.exec.*

配套本地审批文件：

~/.openclaw/exec-approvals.json

简单理解：

• sandbox 决定地点
• tool policy 决定能不能用
• elevated 决定能不能回宿主机
• approvals 决定回宿主机后是否还需要人工批准

你这台机器当前的实际状态

1. 沙箱状态

执行：

openclaw sandbox explain --json

当前结果：

• sandbox.mode = off
• scope = agent
• workspaceAccess = none
• sessionIsSandboxed = false

解释：

• 你当前没有启用 Docker 沙箱
• 工具当前是在宿主机上直接运行

2. Elevated 状态

当前结果：

• elevated.enabled = true
• 但 allowedByConfig = false
• 原因是 tools.elevated.allowFrom.webchat 没有放行

3. Exec approvals 状态

执行：

openclaw approvals get

当前结果：

• ~/.openclaw/exec-approvals.json 不存在
• 没有 allowlist
• 没有 agent 级审批规则

4. Security audit 状态

执行：

openclaw security audit

当前结果：

• 0 critical
• 1 warn
• 1 info

主要告警：

• gateway.trustedProxies 未设置

解释：

• 如果你只是在本机回环访问 127.0.0.1，问题不大
• 如果以后要反向代理或开放到局域网，就要补 trustedProxies

5. 本次已经实际写入的安全配置

{
  "gateway": {
    "bind": "loopback"
  },
  "tools": {
    "elevated": {
      "allowFrom": {
        "webchat": []
      }
    }
  }
}

含义：

• gateway.bind = loopback：明确只监听本机回环地址
• tools.elevated.allowFrom.webchat = []：显式不允许 Dashboard / webchat 直接获得 elevated 宿主机执行通道

最值得关注的配置项

单机本地使用时优先关注

• gateway.mode
• gateway.bind
• gateway.auth.mode
• gateway.auth.token
• agents.defaults.model.primary
• agents.defaults.sandbox.mode
• tools.elevated.allowFrom.webchat

如果要开放给别人访问，再关注

• gateway.trustedProxies
• tools.allow / deny
• tools.exec.*
• exec-approvals.json

你现在最实际的建议

1. 保持 gateway.mode = local
2. 保持 gateway.auth.mode = token
3. 保持 gateway.bind = loopback
4. 暂时不要开放 tools.elevated.allowFrom.webchat
5. 暂时不要把 Gateway 暴露到局域网或公网
6. 如果后面开始让它大量读写本机文件，再考虑开启 sandbox

Tip

你这台机器目前没有安装 Docker，因此现在不建议把 sandbox.mode 改成 non-main 或 all。

常用检查命令

openclaw config get gateway
openclaw config get agents.defaults
openclaw sandbox explain --json
openclaw approvals get
openclaw security audit
openclaw gateway status --json

一句话理解

• openclaw.json 是总配置
• sandbox 管运行位置
• tool policy 管能不能用
• elevated 管能不能回宿主机
• exec-approvals.json 管要不要人工批准

---

分类：OpenClaw