10. 安全配置指南

课程信息
难度等级：🔴 高级
阅读时间：30 分钟
前置知识：已完成基本配置（03-快速开始指南）
本篇你将学会： 保护你的 AI 助手不被未授权访问、配置沙箱隔离、管理用户权限
谁需要看这篇？ 如果你只是在自己电脑上用、不对外暴露，默认安全配置已经够了。如果你要把 OpenClaw 暴露到公网、或者给多人使用，这篇必看
小白速通： 只看"DM Pairing 配对系统"和"最小安全清单"两节就够了

为什么安全是第一优先级？

OpenClaw 不是一个普通的聊天机器人。它是一个能读写文件、执行 Shell 命令、调用 API、发送消息的 AI Agent。换句话说，它拥有你赋予它的一切权限。

如果配置不当，后果可能很严重：

你的 API Key 被泄露，别人拿你的额度跑模型

恶意消息触发 Agent 执行危险命令（比如 rm -rf /）

文件系统被暴露，敏感数据被读取

未授权用户通过消息平台控制你的 Agent

提示词注入攻击让 AI 绕过安全限制

OpenClaw 在 2026 年初曾爆出 CVE 安全漏洞，社区对安全问题高度重视。从 v2026.2.1 开始，多项安全特性被设为强制启用。

这篇指南会从架构层面到具体配置，帮你把 OpenClaw 的安全做到位。

⏭️ 小白可跳过 — 这部分面向安全专家和企业用户

OpenClaw 安全架构概述

安全分层模型

OpenClaw 的安全设计采用纵深防御（Defense in Depth）策略，分为五个层次：

┌─────────────────────────────────────────────┐
│           第 1 层：网络边界安全               │
│     TLS 1.3 / 防火墙 / IP 白名单            │
├─────────────────────────────────────────────┤
│           第 2 层：认证与授权                 │
│     Gateway Token / 配对系统 / 用户权限      │
├─────────────────────────────────────────────┤
│           第 3 层：输入验证与过滤             │
│     提示词护栏 / 消息过滤 / 长度限制         │
├─────────────────────────────────────────────┤
│           第 4 层：执行隔离                   │
│     Docker 沙箱 / 文件系统隔离 / 资源限制    │
├─────────────────────────────────────────────┤
│           第 5 层：审计与监控                 │
│     操作日志 / 异常检测 / 告警通知           │
└─────────────────────────────────────────────┘

每一层都是独立的防线。即使某一层被突破，下一层仍然能提供保护。不要只依赖单一安全措施。

安全组件关系

用户消息 → [消息平台] → [Webhook 验证] → [Gateway Token 认证]
                                              ↓
                                        [配对系统检查]
                                              ↓
                                        [提示词护栏过滤]
                                              ↓
                                        [Agent 权限检查]
                                              ↓
                                        [沙箱内执行工具]
                                              ↓
                                        [审计日志记录]
                                              ↓
                                        返回结果给用户

零信任原则

OpenClaw 的安全设计遵循零信任原则：

不信任任何输入 — 所有用户消息都经过过滤和验证

不信任任何网络 — 即使在内网也使用 TLS（传输层安全协议，保护网络通信不被窃听）加密

不信任任何执行 — 所有工具调用都在沙箱（Sandbox，限制 AI 执行危险操作的隔离环境）中隔离运行

最小权限 — Agent 只拥有完成任务所需的最少权限

持续验证 — 每次操作都重新检查权限，不依赖缓存的认证状态

API Key 安全管理

API Key 是 OpenClaw 最敏感的资产。一旦泄露，攻击者可以用你的额度调用模型，甚至访问你的账户数据。

基本原则：永远不要硬编码

环境变量管理

方法一：系统环境变量（推荐用于服务器）

方法二：.env 文件（推荐用于开发）

OpenClaw 启动时会自动读取 ~/.openclaw/.env 文件。

方法三：密钥管理服务（推荐用于团队/企业）

密钥轮换策略

定期更换 API Key 是安全最佳实践。建议每 90 天轮换一次。

密钥泄露检测

密钥泄露应急处理

如果你发现 Key 已经泄露：

立即撤销 — 去提供商后台撤销泄露的 Key

生成新 Key — 创建新的 API Key

更新配置 — 用新 Key 替换所有引用

检查用量 — 查看是否有异常 API 调用

清理历史 — 从 git 历史、日志文件中清除泄露的 Key

复盘原因 — 找出泄露的根本原因，防止再次发生

沙箱系统详解

沙箱是 OpenClaw 安全架构中最关键的一环。它确保 Agent 执行的代码和命令被隔离在受控环境中，不会影响宿主机。

为什么需要沙箱？

想象一下这个场景：有人给你的 Agent 发了一条消息："帮我整理一下文件"，但消息中嵌入了恶意指令，让 Agent 执行 rm -rf / 或者读取 /etc/passwd。没有沙箱的话，这些命令会直接在你的机器上执行。

沙箱模式配置

OpenClaw 使用 mode 字段控制沙箱行为，而非简单的 enabled 开关。最常用的模式是 "non-main"，表示非主会话在 Docker 沙箱中运行，主会话保持正常执行：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "sandbox": {
        // "non-main" — 非主会话在 Docker 沙箱中运行（推荐）
        // "all"      — 所有会话都在沙箱中运行
        // "off"      — 禁用沙箱（不推荐用于生产）
        "mode": "non-main",
      }
    }
  }
}

`mode` 值	说明	适用场景
`"non-main"`	非主会话在 Docker 沙箱中运行	生产环境推荐默认值
`"all"`	所有会话都在沙箱中运行	高安全要求场景
`"off"`	禁用沙箱	仅限开发/调试

工具 Allow 与 Deny

沙箱内可用的工具通过 tools.allow/tools.deny 控制（注意：不是 toolAllowlist/toolDenylist）：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "tools": {
          // 沙箱内允许使用的工具
          "allow": [
            "bash", "process", "read", "write", "edit",
            "sessions_list", "sessions_history",
            "sessions_send", "sessions_spawn"
          ],
          // 沙箱内禁止使用的工具
          "deny": [
            "browser", "canvas", "nodes",
            "cron", "discord", "gateway"
          ]
        }
      }
    }
  }
}

按 Agent 配置不同的沙箱策略

不同的 Agent 可以覆盖默认的沙箱模式：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
      }
    },
    "list": [
      // coder Agent 始终在沙箱中运行（更严格）
      {
        "id": "coder",
        "workspace": "~/.openclaw/workspace-coder",
        "sandbox": {
          "mode": "all",
          "tools": {
            "allow": ["bash", "read", "write", "edit"]
          }
        }
      },
      // researcher Agent 允许更多工具
      {
        "id": "researcher",
        "workspace": "~/.openclaw/workspace-researcher",
        "sandbox": {
          "mode": "non-main",
          "tools": {
            "allow": [
              "bash", "read", "write", "edit", "browser"
            ]
          }
        }
      },
      // assistant Agent 最小权限
      {
        "id": "assistant",
        "workspace": "~/.openclaw/workspace-assistant",
        "sandbox": {
          "mode": "all",
          "tools": {
            "allow": ["read", "sessions_list", "sessions_history"],
            "deny": ["bash", "process", "browser", "gateway"]
          }
        }
      }
    ]
  }
}

沙箱逃逸防护

OpenClaw 的 Docker 沙箱支持以下安全加固选项（在 sandbox.docker 下配置）：

// ~/.openclaw/openclaw.json — Docker 沙箱安全加固
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "docker": {
          // 移除所有 Linux capabilities（真实字段）
          "capDrop": ["ALL"],
          // 根文件系统只读（注意：字段名是 readOnlyRoot，不是 readOnlyRootfs）
          "readOnlyRoot": true,
          // tmpfs 挂载路径数组（用于只读根文件系统时提供可写临时目录）
          "tmpfs": ["/tmp", "/run"]
        }
      }
    }
  }
}

capDrop: ["ALL"] — 移除所有 Linux capabilities，最小权限原则

readOnlyRoot: true — 根文件系统只读，防止恶意写入

tmpfs — 挂载临时文件系统的路径列表，容器销毁后数据消失

注意：securityOpt、noSetuid 等字段在 OpenClaw 配置中不存在。如需额外的 Docker 安全选项，应在 docker-compose.yml 或 Docker 运行命令中直接配置。

不使用 Docker 的环境

如果你的环境不支持 Docker，可以通过 OPENCLAW_DISABLE_DOCKER=1 环境变量禁用 Docker 沙箱。但请注意，禁用沙箱后 Agent 将直接在宿主机上执行工具调用，安全风险显著增加。

在不支持 Docker 的环境中，建议通过以下方式补偿安全性：

使用 SOUL.md 中的行为约束限制 Agent 操作

设置严格的操作系统文件权限

使用专用的低权限用户运行 OpenClaw

限制工具的 allowlist，禁用 bash/process 等危险工具

权限控制

OpenClaw 的权限系统分为三个维度：用户权限、工具权限、文件访问权限。

Gateway 认证（必须设置）

Gateway 认证是 OpenClaw 的第一道防线。没有认证的 Gateway 任何人都能连接。OpenClaw 支持 Token 和密码两种认证模式。

方式一：Token 认证

方式二：密码认证

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "auth": {
      // "password" — 密码认证模式
      // "token"    — Token 认证模式
      "mode": "password",
    }
  }
}

凭证存储

Gateway 认证凭证存储在 ~/.openclaw/credentials 文件中。确保该文件权限正确：

认证要求：

Token 至少 32 个字符

使用密码学安全的随机数生成

不要使用可猜测的字符串（比如 password123、admin）

不同环境（开发、测试、生产）使用不同的凭证

gateway.bind 必须是 loopback 地址（127.0.0.1），除非通过 Tailscale（零配置 VPN 工具，让你安全地远程访问）等安全隧道暴露

DM Pairing 配对系统（配对机制，新用户首次私聊 AI 时需要你手动批准）

配对系统控制谁可以给你的 Agent 发私信（DM）。默认策略是 "pairing"：当未知发送者发来消息时，Agent 会回复一个配对码，你需要手动批准。

dmPolicy 策略

// ~/.openclaw/openclaw.json
{
  "channels": {
    // "pairing" — 未知发送者收到配对码，需手动批准（默认，推荐）
    // "open"    — 允许所有人发消息（需配合 allowFrom 使用）
    "dmPolicy": "pairing",
  }
}

配对操作

公开模式（谨慎使用）

如果你确实需要让 Agent 接受所有人的消息，可以使用公开模式：

// ~/.openclaw/openclaw.json — 公开模式（不推荐用于生产）
{
  "channels": {
    "dmPolicy": "open",
    // "*" 表示允许所有人
    "allowFrom": ["*"],
  }
}

强烈建议：保持默认的 "pairing" 策略。公开模式意味着任何人都能控制你的 Agent，仅在受信任的封闭环境中使用。

安全诊断

使用 openclaw doctor 检查配对系统和其他安全配置是否正确：

openclaw doctor 会检查：

配对系统是否启用

Gateway 认证是否配置

沙箱是否启用

文件权限是否正确

其他安全配置项

用户访问控制

OpenClaw 采用单一信任边界安全模型：每个 Gateway 实例对应一个受信任的操作者。它不是多租户 RBAC 系统，不支持在同一个 Gateway 上为不同用户分配不同权限角色。

访问控制通过以下机制实现：

DM 配对系统 — 默认策略 pairing，未知发送者需要输入配对码，操作者审批后才能对话

allowFrom 白名单 — 在 channels 中配置允许的发送者列表

多 Agent 隔离 — 不同用户路由到不同 Agent，每个 Agent 有独立的 workspace 和工具权限

// ~/.openclaw/openclaw.json — 通过 channels 控制谁能访问
{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",       // 默认：配对码审批
      allowFrom: ["+15555550123"],
    },
    telegram: {
      dmPolicy: "pairing",       // 配对码审批
      allowFrom: ["123456789"],  // 允许的用户白名单
    },
  }
}

如果需要多用户隔离，应该为每个信任边界部署独立的 Gateway 实例（独立的 OS 用户/主机），而不是在一个 Gateway 上做角色分级。

工具权限控制

工具的权限控制通过 sandbox（沙箱）和审批系统实现，而不是通过 tools.permissions 字段。tools 顶层字段用于配置工具本身的参数（如 tools.web.search.apiKey），不包含权限控制结构。

实际的工具权限控制方式：

1. 沙箱隔离 — 限制 Agent 能做什么

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",        // 非主 Agent 在沙箱中运行
        // 可选值："off"（关闭）| "non-main"（非主 Agent）| "all"（所有 Agent）
      },
    },
  },
}

2. 审批系统 — 运行时控制工具调用

3. Agent 级别的工具限制

通过 SOUL.md（Agent 人格文件）明确告诉 AI 哪些操作是禁止的：

文件访问权限

文件系统是最需要保护的资源之一。OpenClaw 通过沙箱隔离和操作系统级别的权限来保护文件系统，而不是通过配置文件中的路径规则。

实际的文件保护方式：

1. 沙箱隔离（推荐）

通过沙箱模式限制 Agent 的文件访问：

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",             // 所有 Agent 都在沙箱中运行
      },
    },
  },
}

2. 操作系统权限

通过 Unix 文件权限限制 OpenClaw 进程的访问范围：

3. SOUL.md 行为约束

通过 Agent 人格文件明确禁止访问敏感路径：

这种多层防护（沙箱 + OS 权限 + AI 行为约束）比单一的配置文件规则更可靠。

网络安全

TLS 1.3（v2026.2.1 强制）

从 v2026.2.1 开始，OpenClaw 强制使用 TLS 1.3 作为最低标准。

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "tls": {
      "enabled": true,
      "minVersion": "1.3",
      "certPath": "/path/to/cert.pem",
      "keyPath": "/path/to/key.pem",
    },
  }
}

使用 Let's Encrypt 获取免费证书

自签名证书（仅用于开发/测试）

自签名证书仅用于开发环境。生产环境请使用 Let's Encrypt 或其他 CA 签发的证书。

绑定地址

Gateway 默认绑定 127.0.0.1（仅本地访问）。gateway.bind 必须是 loopback 地址，除非你明确知道自己在做什么。

// ~/.openclaw/openclaw.json
{
  "gateway": {
    // 必须是 loopback 地址
    "bind": "127.0.0.1",
    "port": 18789,
  }
}

如果需要远程访问，推荐使用 SSH 隧道、Tailscale 或 VPN，而不是直接暴露端口：

Tailscale Serve/Funnel 的优势：Gateway 仍然绑定 127.0.0.1，Tailscale 在网络层处理加密和认证，无需手动配置 TLS 证书。Funnel 模式会自动提供公网 HTTPS 端点。

防火墙配置

UFW（Ubuntu/Debian）

firewalld（CentOS/RHEL）

iptables

IP 白名单

OpenClaw 没有内置的 gateway.security.ipWhitelist 配置。IP 访问控制通过以下方式实现：

1. 绑定地址限制

默认绑定 127.0.0.1（仅本地访问）。如果需要远程访问，通过防火墙规则控制允许的 IP：

// ~/.openclaw/openclaw.json
{
  gateway: {
    bind: "127.0.0.1",       // 仅允许本地访问（最安全）
    // bind: "0.0.0.0",      // 如需远程访问，配合防火墙使用
    port: 18789,
  },
}

2. 反向代理场景

如果 TLS 由反向代理（如 Nginx）终止，使用 trustedProxies 确保 OpenClaw 能正确获取客户端 IP：

// ~/.openclaw/openclaw.json
{
  gateway: {
    trustedProxies: ["127.0.0.1", "::1"],  // 信任的代理 IP（仅用于 IP 检测场景）
  },
}

注意区分： 上面的 trustedProxies 用于 IP 检测场景（告诉 Gateway 信任代理传来的 X-Forwarded-For）。如果你使用 trusted-proxy 认证模式（gateway.auth.mode: "trusted-proxy"），则 trustedProxies 不能填 loopback 地址。详见本文后面的"反向代理 Forwarded Headers 安全模型"章节。

3. 防火墙规则（推荐）

IP 白名单应该在操作系统或网络层面实现，而不是在应用层：

速率限制

OpenClaw 在控制面写入操作（如 config.apply、config.patch、update.run）上内置了速率限制（每 60 秒 3 次），但这是运行时内置行为，不通过配置文件控制。

如果需要更精细的速率限制，建议在反向代理层实现：

反向代理 Forwarded Headers 安全模型（v2026.4.x+）

从 v2026.4.x 开始，OpenClaw 加强了对转发头的安全检查。核心规则：转发头证据会覆盖 loopback 本地性。

具体来说：如果一个请求通过 loopback（127.0.0.1 / ::1）到达 Gateway，但携带了 X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto 头指向非本地来源，Gateway 会认定该请求来自远程，不再享有 loopback 本地信任。这防止了 same-host loopback 代理"洗白"转发头身份到 trusted-proxy 认证路径的攻击。

配置要点：

// ~/.openclaw/openclaw.json
{
  "gateway": {
    // 信任的代理 IP（不能是 loopback 地址）
    "trustedProxies": ["10.0.0.1"],

    "auth": {
      "mode": "trusted-proxy",
      "trustedProxy": {
        "userHeader": "x-forwarded-user",      // 必填：包含用户身份的头
        "requiredHeaders": [],                  // 可选：额外验证头
        "allowUsers": []                        // 可选：用户白名单（空=允许所有）
      }
    }
  }
}

安全检查清单：

反向代理必须覆盖（不是追加）来自客户端的转发头

trustedProxies 只填具体 IP，不要填子网

不能同时配置 gateway.auth.token 和 trusted-proxy 模式（Gateway 会拒绝启动）

Gateway 端口必须通过防火墙限制，只允许代理 IP 访问

same-host loopback 代理不满足 trusted-proxy 认证，请改用 token/password 认证

Owner-Enforced Commands（v2026.4.5+）

从 v2026.4.5 开始，OpenClaw 加强了命令执行的所有者认证。关键变化：

/allowlist 命令需要 Owner 授权： /allowlist add 和 /allowlist remove 操作现在要求实际的 Owner 身份验证，不再接受宽松的回退（permissive fallback）。这意味着只有经过身份验证的 Gateway 所有者才能修改工具白名单。

控制面工具限制： 两个高风险内置工具强制为 owner-only：

gateway 工具 -- 查看/修改持久化配置，拒绝重写执行审批设置

cron 工具 -- 创建超出当前会话范围的持久化定时任务

建议： 对于处理不可信内容的 Agent/Surface，在配置中明确拒绝这些工具：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "list": [
      {
        "id": "public-facing",
        "sandbox": {
          "tools": {
            "deny": ["gateway", "cron", "sessions_spawn", "sessions_send"]
          }
        }
      }
    ]
  }
}

插件白名单（Plugin Allowlist，v2026.4.5+）

从 v2026.4.5 开始，OpenClaw 引入了插件级别的白名单机制：

插件白名单持久化：用户批准的工具白名单作为持久化信任存储，不会因 Gateway 重启而丢失

Bundled 合并：v2026.4.7+ 将内置插件的 capabilities 自动合并到白名单条目中

保留命名空间：核心管理命名空间（config.*、exec.approvals.*、wizard.*、update.*）始终保持 operator.admin 权限级别，即使插件尝试指定更窄的作用域也会被忽略

本地部署的隐私优势

OpenClaw 最大的卖点之一就是数据隐私。所有数据都在你自己的设备上，不经过第三方服务器。

传统云端 AI 助手：
你的消息 → 云端服务器（第三方存储） → AI 处理 → 返回结果
         ↑ 你的数据在别人的服务器上

OpenClaw：
你的消息 → 你的服务器（本地存储） → AI API 处理 → 返回结果
         ↑ 你的数据始终在你自己的设备上

注意：虽然 OpenClaw 本身不存储数据到云端，但调用 AI API 时，你的消息内容会发送到 AI 提供商（OpenAI、Anthropic 等）。如果对此有顾虑，可以使用本地模型（如 Ollama）。

数据加密

静态数据加密

OpenClaw 没有内置的 storage.encryption 配置字段。静态数据加密应通过操作系统级别的磁盘加密实现：

操作系统	加密方案
macOS	FileVault（系统偏好设置 → 安全性与隐私）
Linux	LUKS（`cryptsetup`）
Windows	BitLocker

这比应用层加密更安全 — 即使 OpenClaw 进程被攻破，攻击者也无法绕过磁盘加密读取数据。

OpenClaw 存储在磁盘上的数据包括：

聊天记录（sessions/*.jsonl）

记忆文件（MEMORY.md、memory/*.md）

用户画像（USER.md）

配置文件（openclaw.json）

传输加密

所有网络通信都通过 TLS 1.3 加密（前面已经配置过）。确保：

Gateway 启用了 TLS

Webhook 回调使用 HTTPS

API 调用使用 HTTPS（所有主流 AI 提供商默认 HTTPS）

配置文件保护

使用本地模型保护隐私

如果你不想让任何数据离开你的设备，可以使用本地模型（如 Ollama）：

// ~/.openclaw/openclaw.json — 配置使用本地模型
{
  agents: {
    defaults: {
      model: "ollama/llama3.1",
    },
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
      },
    },
  },
}

这样所有数据都在本地处理，零网络传输。

消息平台安全

Webhook 验证

每个消息平台都有自己的 Webhook 签名验证机制。OpenClaw 会自动验证，但你需要正确配置。

Telegram 的 Webhook 验证通过 webhookSecret 字段配置（不是嵌套在 security 子对象中）：

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456:ABC-DEF...",     // 或使用环境变量 TELEGRAM_BOT_TOKEN
      webhookUrl: "https://your-domain.com/webhook/telegram",
      webhookSecret: "your-webhook-secret",  // Webhook 签名验证密钥
    },
  },
}

Discord

Discord 的签名验证由 OpenClaw 自动处理，只需正确配置 Bot Token：

// ~/.openclaw/openclaw.json
{
  channels: {
    discord: {
      token: "YOUR_DISCORD_BOT_TOKEN",   // 或使用环境变量 DISCORD_BOT_TOKEN
      // Discord 使用 Ed25519 签名验证，OpenClaw 内部自动处理
    },
  },
}

WhatsApp（通过 Baileys 非官方库）使用扫码认证，凭证自动存储在 ~/.openclaw/credentials 目录中：

// ~/.openclaw/openclaw.json
{
  channels: {
    whatsapp: {
      allowFrom: ["+8613800138000"],     // 控制谁可以和 Bot 对话
      // 凭证通过 openclaw channels login whatsapp 扫码获取
    },
  },
}

注意：各消息平台的 Webhook 签名验证是 OpenClaw 内部自动处理的，不需要在配置文件中手动配置 security 子对象。你只需要确保 Token 和 Secret 正确填写即可。

Token 管理

消息平台的 Bot Token 和 API Key 一样敏感：

Token 安全要点：

不要在配置文件中明文存储 Token

不要在日志中打印 Token

定期轮换 Token（尤其是怀疑泄露时）

每个环境使用不同的 Bot Token

⏭️ 小白可跳过 — 这部分面向安全专家和企业用户

提示词注入防护

提示词注入是 AI Agent 面临的最大安全威胁之一。攻击者通过精心构造的消息，试图让 AI 忽略系统提示词，执行恶意操作。

提示词注入防护

OpenClaw 没有内置的 systemPrompt.guardrails 或 systemPrompt.injection 配置字段。提示词注入防护主要通过以下方式实现：

1. SOUL.md 行为约束（推荐）

在 Agent 的人格文件中明确安全规则：

2. 沙箱隔离（兜底）

即使提示词注入成功，沙箱确保 Agent 的操作被隔离：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",  // 最严格：所有会话都在沙箱中
        "tools": {
          "deny": ["gateway", "cron"]  // 禁用高风险工具
        }
      }
    }
  }
}

3. 工具审批系统

提示词注入是 AI Agent 领域的已知难题，没有 100% 的技术解决方案。最有效的防护是：沙箱隔离 + 最小工具权限 + SOUL.md 行为约束的多层防御组合。

⏭️ 小白可跳过 — 这部分面向安全专家和企业用户

日志审计

日志配置

OpenClaw 没有内置的 logging.audit 审计日志子配置。LoggingConfig 支持的字段是：

// ~/.openclaw/openclaw.json — 实际可用的日志配置
{
  "logging": {
    "level": "info",              // 日志级别：silent, fatal, error, warn, info, debug, trace
    "file": "~/.openclaw/logs/openclaw.log",  // 日志文件路径
    "consoleLevel": "info",       // 控制台日志级别
    "consoleStyle": "pretty",       // 控制台输出风格："pretty" | "compact" | "json"
    "redactSensitive": "tools",     // 脱敏模式："off" | "tools"（对工具输出脱敏）
    "redactPatterns": [           // 自定义脱敏正则
      "sk-proj-[A-Za-z0-9]+",
      "sk-ant-[A-Za-z0-9]+"
    ]
  }
}

注意：logging.audit、logging.events 等字段在 OpenClaw 中不存在。如需专门的审计日志，建议通过外部日志收集工具（如 ELK Stack、Loki）分析 OpenClaw 的标准日志输出。

日志查看

日志格式

OpenClaw 使用结构化 JSON 日志，便于机器解析：

{
  "timestamp": "2026-02-25T10:30:00Z",
  "level": "warn",
  "event": "tool.blocked",
  "correlationId": "req-abc123",
  "userId": "telegram:12345",
  "agent": "assistant",
  "tool": "shell",
  "command": "rm -rf /",
  "reason": "blocked_command",
  "ip": "192.168.1.100"
}

日志监控与告警

日志安全

日志本身也需要保护：

安全最佳实践清单

每次部署前过一遍这个清单：

必须做（CRITICAL）

Gateway 认证已设置（Token 或密码模式）

API Key 使用环境变量，不在配置文件中明文存储

DM 配对系统已启用（dmPolicy: "pairing"）

Gateway 绑定 127.0.0.1（gateway.bind 为 loopback）

配置文件和凭证权限设为 600（~/.openclaw/openclaw.json、~/.openclaw/credentials）

TLS 1.3 已启用

沙箱已启用（sandbox.mode: "non-main" 或 "all"）

SOUL.md 中设置了安全行为约束

运行 openclaw doctor 确认安全配置无误

强烈建议（HIGH）

防火墙已配置，OpenClaw 端口不对外暴露

使用 SSH 隧道或 VPN 进行远程访问

日志已配置（logging.level、logging.file）

速率限制已配置

文件访问通过沙箱和 OS 权限控制

工具权限已配置（禁用不需要的工具）

Webhook 签名验证已启用

反向代理已配置覆盖（非追加）客户端转发头（v2026.4.x+）

处理不可信内容的 Agent 已禁用 gateway、cron 等高风险工具

建议做（MEDIUM）

IP 白名单已配置

密钥轮换计划已制定（每 90 天）

静态数据加密已启用

日志监控和告警已配置

用户权限分级已配置

定期安全审计

持续维护

定期更新到最新版本

定期检查日志中的异常事件

定期轮换 API Key 和 Token

关注 OpenClaw 安全公告

常见安全威胁和防护

威胁 1：提示词注入攻击

攻击者通过消息让 AI 执行非预期操作。

防护措施：

在 SOUL.md 中设置安全行为约束

启用沙箱隔离（sandbox.mode: "all"）

限制 Agent 可用的工具（tools.deny）

设置敏感工具需要审批（openclaw approvals set）

威胁 2：API Key 泄露

Key 被泄露后，攻击者可以用你的额度。

防护措施：

使用环境变量存储 Key

设置配置文件权限为 600

定期轮换 Key

监控 API 用量异常

威胁 3：未授权访问

未经授权的用户控制你的 Agent。

防护措施：

设置 Gateway 认证（Token 或密码模式）

启用 DM 配对系统（dmPolicy: "pairing"）

配置用户权限分级

启用 IP 白名单

运行 openclaw doctor 检查配置

威胁 4：文件系统攻击

Agent 被诱导读取或修改敏感文件。

防护措施：

启用沙箱隔离

通过 OS 文件权限限制访问范围

限制可写路径

阻止访问敏感目录（.ssh、.gnupg）

威胁 5：网络攻击

中间人攻击、端口扫描、暴力破解。

防护措施：

强制 TLS 1.3

绑定 127.0.0.1

配置防火墙

启用速率限制

威胁 6：供应链攻击

恶意的第三方技能或插件。

防护措施：

只安装来自可信来源的技能

审查技能的源代码

在沙箱中运行第三方技能

限制技能的权限

使用插件白名单机制（v2026.4.5+）控制可加载的插件

威胁 7：环境变量注入（v2026.4.7+ 防护）

恶意插件或工具通过环境变量注入危险配置。

防护措施（v2026.4.7+ 自动生效）：

Gateway 自动拦截危险的环境变量覆盖（Java、Rust、Cargo、Git、Kubernetes、云凭证等相关变量）

MCP stdio 服务器启动时自动屏蔽 NODE_OPTIONS 等解释器级环境变量

建议定期运行 openclaw security audit --deep 检查环境变量配置

⏭️ 小白可跳过 — 这部分面向安全专家和企业用户

合规性考虑

GDPR（欧盟通用数据保护条例）

如果你的用户中有欧盟居民，需要考虑 GDPR 合规：

数据最小化 — 只收集必要的数据。OpenClaw 默认不收集用户数据，但聊天记录和记忆系统会存储用户信息

数据本地化 — OpenClaw 的本地部署天然满足数据本地化要求

删除权 — 用户有权要求删除他们的数据

数据保留策略

OpenClaw 没有内置的 storage.retention 配置字段。数据保留需要手动管理：

建议定期清理旧数据，既节省磁盘空间，也减少潜在的数据泄露风险。

其他合规框架

CCPA（加州消费者隐私法）— 类似 GDPR，关注用户数据权利

HIPAA（健康保险可携带性和责任法案）— 如果处理健康数据，需要额外的加密和访问控制

SOC 2 — 如果在企业环境中使用，需要完善的审计日志和访问控制

OpenClaw 的本地部署模式天然满足大部分合规要求，因为数据不离开你的控制范围。但调用云端 AI API 时，数据会发送到提供商，需要评估提供商的合规性。

⏭️ 小白可跳过 — 这部分面向安全专家和企业用户

安全事件响应

事件分级

级别	描述	响应时间	示例
P0 - 紧急	系统被入侵，数据泄露	立即	API Key 泄露、未授权访问
P1 - 高	安全漏洞被发现	4 小时内	沙箱逃逸、提示词注入成功
P2 - 中	可疑活动	24 小时内	异常登录尝试、异常 API 用量
P3 - 低	安全配置问题	1 周内	权限配置不当、日志未启用

P0 事件应急流程

1. 立即隔离
   - 停止 OpenClaw 服务：openclaw gateway stop
   - 断开网络连接（如果可能）

2. 评估影响
   - 检查审计日志：确定攻击范围
   - 检查文件系统：是否有文件被修改
   - 检查 API 用量：是否有异常调用

3. 遏制损害
   - 撤销所有 API Key
   - 更换 Gateway Token
   - 更换 Bot Token

4. 恢复服务
   - 生成新的 Key 和 Token
   - 更新配置
   - 重启服务
   - 验证安全配置

5. 复盘
   - 记录事件时间线
   - 分析根本原因
   - 制定改进措施
   - 更新安全配置

安全更新

OpenClaw 更新非常频繁，安全修复通常在 24 小时内发布：

建议：订阅 OpenClaw 的 GitHub Security Advisories，第一时间获取安全更新通知。

常见问题

Q：我在本地跑 OpenClaw，还需要配置安全吗？

需要。即使在本地，也要设置 Gateway Token 和文件访问权限。原因：

本地网络中的其他设备可能访问你的 OpenClaw

恶意消息仍然可能通过消息平台到达你的 Agent

提示词注入攻击不依赖网络位置

Q：沙箱会影响性能吗？

Docker 沙箱会有轻微的性能开销（通常 < 5%）。对于大多数使用场景，这个开销可以忽略不计。如果你对性能非常敏感，可以：

增加沙箱的资源限制（maxMemory、maxCpu）

对不需要沙箱的 Agent 单独关闭（不推荐）

使用进程级沙箱替代 Docker 沙箱

Q：API Key 泄露了怎么办？

立即去提供商后台撤销泄露的 Key

生成新 Key 并更新配置

检查 API 用量是否有异常

从 git 历史和日志中清除泄露的 Key

复盘泄露原因，防止再次发生

Q：如何检测提示词注入攻击？

在 SOUL.md 中设置安全行为约束

监控日志中的可疑操作

定期检查 Agent 的执行历史，看是否有异常操作

限制 Agent 的工具权限，减少攻击面

Q：多人共用一个 OpenClaw 实例安全吗？

OpenClaw 采用单一信任边界模型，不是多租户 RBAC 系统。如果需要多人使用：

为每个信任边界部署独立的 Gateway 实例（独立的 OS 用户/主机）

通过多 Agent + 独立 workspace 实现逻辑隔离

使用 DM 配对系统控制谁能访问

启用审计日志追踪操作

Q：OpenClaw 会把我的数据发送到哪里？

OpenClaw 本身不会把数据发送到任何地方。但当你使用云端 AI 模型时，消息内容会发送到 AI 提供商的 API。如果你对此有顾虑：

使用本地模型（Ollama）

查看 AI 提供商的数据使用政策

启用 API 请求日志，监控发送的数据

Q：如何安全地备份 OpenClaw 数据？

备份时注意：

备份文件也要设置严格的权限（chmod 600）

不要把备份上传到公开的云存储

定期测试备份的恢复流程

下一步

安全加固完成！去 11. 常见问题看看其他人踩过的坑！

10-安全配置指南

10. 安全配置指南#

为什么安全是第一优先级？#

OpenClaw 安全架构概述#

安全分层模型#

安全组件关系#

零信任原则#

API Key 安全管理#

基本原则：永远不要硬编码#

环境变量管理#

方法一：系统环境变量（推荐用于服务器）#

方法二：.env 文件（推荐用于开发）#

方法三：密钥管理服务（推荐用于团队/企业）#

密钥轮换策略#

密钥泄露检测#

密钥泄露应急处理#

沙箱系统详解#

为什么需要沙箱？#

沙箱模式配置#

工具 Allow 与 Deny#

按 Agent 配置不同的沙箱策略#

沙箱逃逸防护#

不使用 Docker 的环境#

权限控制#

Gateway 认证（必须设置）#

方式一：Token 认证#

方式二：密码认证#

凭证存储#

DM Pairing 配对系统（配对机制，新用户首次私聊 AI 时需要你手动批准）#

dmPolicy 策略#

配对操作#

公开模式（谨慎使用）#

安全诊断#

用户访问控制#

工具权限控制#

文件访问权限#

网络安全#

TLS 1.3（v2026.2.1 强制）#

使用 Let's Encrypt 获取免费证书#

自签名证书（仅用于开发/测试）#

绑定地址#

防火墙配置#

UFW（Ubuntu/Debian）#

firewalld（CentOS/RHEL）#

iptables#

IP 白名单#

速率限制#

反向代理 Forwarded Headers 安全模型（v2026.4.x+）#

Owner-Enforced Commands（v2026.4.5+）#

插件白名单（Plugin Allowlist，v2026.4.5+）#

本地部署的隐私优势#

数据加密#

静态数据加密#

传输加密#

配置文件保护#

使用本地模型保护隐私#

消息平台安全#

Webhook 验证#

Telegram#

Discord#

WhatsApp#

Token 管理#

提示词注入防护#

提示词注入防护#

日志审计#

日志配置#

日志查看#

日志格式#

日志监控与告警#

日志安全#

安全最佳实践清单#

必须做（CRITICAL）#

强烈建议（HIGH）#

建议做（MEDIUM）#

持续维护#

常见安全威胁和防护#

威胁 1：提示词注入攻击#

威胁 2：API Key 泄露#

威胁 3：未授权访问#

威胁 4：文件系统攻击#

10. 安全配置指南

为什么安全是第一优先级？

OpenClaw 安全架构概述

安全分层模型

安全组件关系

零信任原则

API Key 安全管理

基本原则：永远不要硬编码

环境变量管理

方法一：系统环境变量（推荐用于服务器）

方法二：.env 文件（推荐用于开发）

方法三：密钥管理服务（推荐用于团队/企业）

密钥轮换策略

密钥泄露检测

密钥泄露应急处理

沙箱系统详解

为什么需要沙箱？

沙箱模式配置

工具 Allow 与 Deny

按 Agent 配置不同的沙箱策略

沙箱逃逸防护

不使用 Docker 的环境

权限控制

Gateway 认证（必须设置）

方式一：Token 认证

方式二：密码认证

凭证存储

DM Pairing 配对系统（配对机制，新用户首次私聊 AI 时需要你手动批准）

dmPolicy 策略

配对操作

公开模式（谨慎使用）

安全诊断

用户访问控制

工具权限控制

文件访问权限

网络安全

TLS 1.3（v2026.2.1 强制）

使用 Let's Encrypt 获取免费证书

自签名证书（仅用于开发/测试）

绑定地址

防火墙配置

UFW（Ubuntu/Debian）

firewalld（CentOS/RHEL）

iptables

IP 白名单

速率限制

反向代理 Forwarded Headers 安全模型（v2026.4.x+）

Owner-Enforced Commands（v2026.4.5+）

插件白名单（Plugin Allowlist，v2026.4.5+）

本地部署的隐私优势

数据加密

静态数据加密

传输加密

配置文件保护

使用本地模型保护隐私

消息平台安全

Webhook 验证

Telegram

Discord

WhatsApp

Token 管理

提示词注入防护

提示词注入防护

日志审计

日志配置

日志查看

日志格式

日志监控与告警

日志安全

安全最佳实践清单

必须做（CRITICAL）

强烈建议（HIGH）

建议做（MEDIUM）

持续维护

常见安全威胁和防护

威胁 1：提示词注入攻击

威胁 2：API Key 泄露

威胁 3：未授权访问

威胁 4：文件系统攻击

威胁 5：网络攻击