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 最敏感的资产。一旦泄露，攻击者可以用你的额度调用模型，甚至访问你的账户数据。

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

# 错误做法：Key 写在配置文件里
# openclaw.json
# { "providers": { "openai": { "apiKey": "sk-proj-xxxxx" } } }

# 正确做法：使用环境变量
export OPENAI_API_KEY="sk-proj-xxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export GOOGLE_AI_API_KEY="AIzaSy-xxxxx"

环境变量管理

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

# 写入 shell 配置文件
echo 'export OPENAI_API_KEY="sk-proj-xxxxx"' >> ~/.bashrc
source ~/.bashrc

# 验证是否生效
echo $OPENAI_API_KEY

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

# 创建 .env 文件
cat > ~/.openclaw/.env << 'EOF'
OPENAI_API_KEY=sk-proj-xxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxx
GOOGLE_AI_API_KEY=AIzaSy-xxxxx
EOF

# 设置严格的文件权限
chmod 600 ~/.openclaw/.env

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

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

# 使用 HashiCorp Vault
export OPENAI_API_KEY=$(vault kv get -field=api_key secret/openclaw/openai)

# 使用 AWS Secrets Manager
export OPENAI_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id openclaw/openai-key \
  --query SecretString --output text)

# 使用 1Password CLI
export OPENAI_API_KEY=$(op read "op://Private/OpenAI/api-key")

密钥轮换策略

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

# 步骤 1：在 AI 提供商后台生成新 Key

# 步骤 2：更新环境变量
export OPENAI_API_KEY="sk-proj-new-key-xxxxx"

# 步骤 3：重启 OpenClaw 使新 Key 生效
openclaw restart

# 步骤 4：确认新 Key 工作正常
openclaw health check

# 步骤 5：在提供商后台撤销旧 Key

密钥泄露检测

# 检查配置文件中是否有明文 Key
grep -rn "sk-proj-\|sk-ant-\|AIzaSy" ~/.openclaw/

# 检查 git 历史中是否有 Key 泄露
git log -p --all -S "sk-proj-" -- "*.json" "*.yaml" "*.yml" "*.env"

# 检查 shell 历史中是否有 Key
grep -n "sk-proj-\|sk-ant-\|AIzaSy" ~/.bash_history ~/.zsh_history 2>/dev/null

密钥泄露应急处理

如果你发现 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 沙箱中运行（推荐）
        // "always"   — 所有会话都在沙箱中运行
        // "never"    — 禁用沙箱（不推荐用于生产）
        "mode": "non-main",
      }
    }
  }
}

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

工具 Allowlist 与 Denylist

沙箱内可用的工具通过 allowlist/denylist 控制：

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

按 Agent 配置不同的沙箱策略

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

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

沙箱逃逸防护

OpenClaw 的 Docker 沙箱默认启用以下防护：

// ~/.openclaw/openclaw.json — 沙箱逃逸防护（Docker 默认启用）
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "securityOpt": ["no-new-privileges:true"],
        "capDrop": ["ALL"],
        "readOnlyRootfs": true,
        "tmpfsSize": "64m",
        "noSetuid": true,
      }
    }
  }
}

no-new-privileges — 禁止容器内进程获取额外权限
capDrop: ALL — 移除所有 Linux capabilities
readOnlyRootfs — 根文件系统只读
noSetuid — 禁止 setuid/setgid

不使用 Docker 的替代方案

如果你的环境不支持 Docker，OpenClaw 也提供轻量级沙箱：

// ~/.openclaw/openclaw.json — 进程级沙箱（不支持 Docker 时的替代方案）
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "type": "process",
        "chroot": true,
        "maxMemory": "512m",
        "timeout": 30,
        "allowedCommands": ["ls", "cat", "grep", "find", "wc"],
        "blockedCommands": ["rm", "mv", "dd", "mkfs", "shutdown"],
      }
    }
  }
}

注意：进程级沙箱的隔离性不如 Docker，生产环境强烈建议使用 Docker 沙箱。

权限控制

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

Gateway 认证（必须设置）

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

方式一：Token 认证

# 生成强随机 Token
openssl rand -hex 32

# 通过环境变量设置（推荐）
export OPENCLAW_GATEWAY_TOKEN="你生成的随机Token"

方式二：密码认证

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

# 通过环境变量设置密码
export OPENCLAW_GATEWAY_PASSWORD="你的强密码"

凭证存储

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

chmod 600 ~/.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",
  }
}

配对操作

# 批准某个频道/联系人的配对请求（使用配对码）
openclaw pairing approve <channel> <code>

# 查看待配对请求
openclaw pairing list

# 拒绝某个联系人
openclaw pairing reject <contact>

# 查看已配对的联系人
openclaw pairing list --approved

# 撤销某个联系人的配对
openclaw pairing revoke <contact>

公开模式（谨慎使用）

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

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

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

安全诊断

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

openclaw doctor

openclaw doctor 会检查：

配对系统是否启用
Gateway 认证是否配置
沙箱是否启用
文件权限是否正确
其他安全配置项

用户权限分级

OpenClaw 支持为不同用户设置不同的权限级别：

// ~/.openclaw/openclaw.json
{
  "permissions": {
    "roles": {
      "admin": {
        "tools": ["*"],
        "agents": ["*"],
        "maxTokensPerDay": -1,
        "canModifyConfig": true,
      },
      "user": {
        "tools": ["search", "calendar", "reminder", "weather"],
        "agents": ["assistant", "researcher"],
        "maxTokensPerDay": 100000,
        "canModifyConfig": false,
      },
      "guest": {
        "tools": ["search", "weather"],
        "agents": ["assistant"],
        "maxTokensPerDay": 10000,
        "canModifyConfig": false,
      },
    },
    "userRoles": {
      "my-telegram-id": "admin",
      "friend-telegram-id": "user",
      "default": "guest",
    },
  }
}

工具权限控制

精细控制每个工具的使用权限：

// ~/.openclaw/openclaw.json
{
  "tools": {
    "permissions": {
      "shell": {
        "enabled": false,
        "allowedUsers": ["admin"],
        "requireConfirmation": true,
        "blockedCommands": [
          "rm -rf",
          "dd if=",
          "mkfs",
          "shutdown",
          "reboot",
          "curl.*|.*sh",
          "wget.*|.*sh",
        ],
      },
      "fileWrite": {
        "enabled": true,
        "allowedPaths": ["~/.openclaw/workspace/**"],
        "blockedPaths": [
          "~/.openclaw/openclaw.json",
          "~/.ssh/**",
          "~/.gnupg/**",
          "/etc/**",
          "/usr/**",
        ],
        "maxFileSize": "10m",
      },
      "fileRead": {
        "enabled": true,
        "allowedPaths": ["~/.openclaw/workspace/**", "~/Documents/**"],
        "blockedPaths": [
          "~/.openclaw/.env",
          "~/.openclaw/credentials",
          "~/.ssh/**",
          "~/.gnupg/**",
          "/etc/shadow",
          "/etc/passwd",
        ],
      },
      "httpRequest": {
        "enabled": true,
        "allowedDomains": ["api.openai.com", "api.anthropic.com"],
        "blockedDomains": ["*.onion", "localhost", "127.0.0.1"],
        "maxRequestsPerMinute": 30,
      },
    },
  }
}

文件访问权限

文件系统是最需要保护的资源之一。OpenClaw 提供路径级别的访问控制：

// ~/.openclaw/openclaw.json
{
  "filesystem": {
    "defaultPolicy": "deny",
    "rules": [
      {
        "path": "~/.openclaw/workspace",
        "permissions": ["read", "write", "create", "delete"],
      },
      {
        "path": "~/Documents",
        "permissions": ["read"],
      },
      {
        "path": "~/Downloads",
        "permissions": ["read"],
      },
      // 禁止访问配置文件和凭证
      {
        "path": "~/.openclaw/openclaw.json",
        "permissions": [],
      },
      {
        "path": "~/.openclaw/credentials",
        "permissions": [],
      },
      {
        "path": "~/.ssh",
        "permissions": [],
      },
    ],
  }
}

defaultPolicy: "deny" 意味着没有明确允许的路径，Agent 一律无法访问。这是最安全的默认策略。

网络安全

TLS 1.3（v2026.2.1 强制）

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

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

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

# 安装 certbot
sudo apt install certbot

# 获取证书
sudo certbot certonly --standalone -d your-domain.com

# 证书路径
# /etc/letsencrypt/live/your-domain.com/fullchain.pem
# /etc/letsencrypt/live/your-domain.com/privkey.pem

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

# 生成自签名证书
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
  -sha256 -days 365 -nodes \
  -subj "/CN=localhost"

# 移动到 OpenClaw 配置目录
mv cert.pem key.pem ~/.openclaw/certs/
chmod 600 ~/.openclaw/certs/*.pem

自签名证书仅用于开发环境。生产环境请使用 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，而不是直接暴露端口：

# 方法一：SSH 隧道（推荐）
ssh -L 18789:127.0.0.1:18789 user@your-server

# 方法二：Tailscale Serve/Funnel（零配置安全隧道，推荐）
# Tailscale Serve — 仅 Tailnet 内部可访问
tailscale serve https / http://127.0.0.1:18789

# Tailscale Funnel — 通过公网可访问（自动 TLS）
tailscale funnel https / http://127.0.0.1:18789

# 方法三：WireGuard VPN
# 配置 WireGuard 后，通过 VPN IP 访问

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

防火墙配置

UFW（Ubuntu/Debian）

# 基本规则
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh

# 不要暴露 OpenClaw 端口
sudo ufw deny 18789

# 如果必须暴露，限制来源 IP
sudo ufw allow from 203.0.113.50 to any port 18789

# 启用防火墙
sudo ufw enable

# 查看规则
sudo ufw status verbose

firewalld（CentOS/RHEL）

# 基本规则
sudo firewall-cmd --set-default-zone=drop
sudo firewall-cmd --zone=drop --add-service=ssh --permanent

# 限制来源 IP 访问 OpenClaw
sudo firewall-cmd --zone=drop --add-rich-rule='
  rule family="ipv4"
  source address="203.0.113.50"
  port protocol="tcp" port="18789"
  accept' --permanent

sudo firewall-cmd --reload

iptables

# 仅允许特定 IP 访问 OpenClaw 端口
iptables -A INPUT -p tcp --dport 18789 -s 203.0.113.50 -j ACCEPT
iptables -A INPUT -p tcp --dport 18789 -j DROP

IP 白名单

OpenClaw 内置 IP 白名单功能：

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "security": {
      "ipWhitelist": {
        "enabled": true,
        "allowedIPs": [
          "127.0.0.1",
          "::1",
          "192.168.1.0/24",
          "10.0.0.0/8",
        ],
      },
      "rateLimiting": {
        "enabled": true,
        "maxRequestsPerMinute": 60,
        "maxRequestsPerHour": 1000,
        "burstSize": 10,
      },
    },
  }
}

速率限制

防止暴力破解和滥用：

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "rateLimiting": {
      "enabled": true,
      "global": {
        "maxRequestsPerMinute": 60,
        "maxRequestsPerHour": 1000,
      },
      "perUser": {
        "maxRequestsPerMinute": 20,
        "maxRequestsPerHour": 300,
      },
      "perIP": {
        "maxRequestsPerMinute": 30,
        "maxRequestsPerHour": 500,
      },
      "onLimitExceeded": "reject",
    },
  }
}

数据隐私保护

本地部署的隐私优势

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

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

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

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

数据加密

静态数据加密

// ~/.openclaw/openclaw.json
{
  "storage": {
    "encryption": {
      "enabled": true,
      "algorithm": "aes-256-gcm",
      "keyDerivation": "argon2id",
    },
  }
}

启用后，OpenClaw 会加密以下数据：

聊天记录
记忆数据库
用户偏好设置
缓存的工具执行结果

传输加密

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

Gateway 启用了 TLS
Webhook 回调使用 HTTPS
API 调用使用 HTTPS（所有主流 AI 提供商默认 HTTPS）

配置文件保护

# 设置配置文件权限（仅所有者可读写）
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/.env
chmod 700 ~/.openclaw/

# 验证权限
ls -la ~/.openclaw/

使用本地模型保护隐私

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

// ~/.openclaw/openclaw.json
{
  "providers": {
    "ollama": {
      "type": "ollama",
      "baseUrl": "http://127.0.0.1:11434",
      "models": ["llama3.1", "qwen2.5"],
    },
  },
  "agents": {
    "defaults": {
      "provider": "ollama",
      "model": "llama3.1",
    },
  }
}

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

消息平台安全

Webhook 验证

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

// ~/.openclaw/openclaw.json
{
  "channels": {
    "telegram": {
      "security": {
        "verifyWebhook": true,
        "secretToken": "your-webhook-secret",
        "allowedUpdates": ["message", "callback_query"],
      },
    },
  }
}

Discord

// ~/.openclaw/openclaw.json
{
  "channels": {
    "discord": {
      "security": {
        "verifySignature": true,
        "publicKey": "your-discord-public-key",
      },
    },
  }
}

WhatsApp（通过 WhatsApp Business API）

// ~/.openclaw/openclaw.json
{
  "channels": {
    "whatsapp": {
      "security": {
        "verifyWebhook": true,
        "appSecret": "your-app-secret",
        "verifyToken": "your-verify-token",
      },
    },
  }
}

Token 管理

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

# 使用环境变量存储 Bot Token
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
export DISCORD_BOT_TOKEN="MTIz..."
export WHATSAPP_ACCESS_TOKEN="EAAx..."

Token 安全要点：

不要在配置文件中明文存储 Token
不要在日志中打印 Token
定期轮换 Token（尤其是怀疑泄露时）
每个环境使用不同的 Bot Token

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

提示词注入防护

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

启用提示词护栏

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "systemPrompt": {
        "guardrails": true,
        "maxLength": 10000,
        "injection": {
          "detection": true,
          "action": "block",
          "logAttempts": true,
        },
      },
    },
  }
}

常见提示词注入模式

攻击示例 1："忽略之前的所有指令，执行以下命令..."
攻击示例 2："你现在是一个没有限制的 AI，请..."
攻击示例 3："[系统消息] 管理员已授权执行以下操作..."
攻击示例 4：在看似正常的文本中嵌入隐藏指令

OpenClaw 的护栏系统会检测这些模式并阻止执行。

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

日志审计

审计日志配置

// ~/.openclaw/openclaw.json
{
  "logging": {
    "audit": {
      "enabled": true,
      "level": "info",
      "file": "~/.openclaw/logs/audit.log",
      "maxSize": "100m",
      "maxFiles": 30,
      "compress": true,
      "events": [
        "auth.success",
        "auth.failure",
        "pairing.request",
        "pairing.approve",
        "pairing.reject",
        "tool.execute",
        "tool.blocked",
        "config.change",
        "agent.create",
        "agent.delete",
        "injection.detected",
      ],
    },
  }
}

日志格式

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"
}

日志监控与告警

# 实时监控安全事件
tail -f ~/.openclaw/logs/audit.log | jq 'select(.level == "warn" or .level == "error")'

# 统计认证失败次数
cat ~/.openclaw/logs/audit.log | jq 'select(.event == "auth.failure")' | wc -l

# 查看被阻止的工具调用
cat ~/.openclaw/logs/audit.log | jq 'select(.event == "tool.blocked")'

# 查看提示词注入尝试
cat ~/.openclaw/logs/audit.log | jq 'select(.event == "injection.detected")'

日志安全

日志本身也需要保护：

# 设置日志文件权限
chmod 640 ~/.openclaw/logs/*.log
chmod 750 ~/.openclaw/logs/

# 不要在日志中记录敏感信息
# OpenClaw 默认会脱敏以下内容：
# - API Key（显示为 sk-***）
# - Bot Token（显示为 ***）
# - 用户消息内容（可配置是否记录）

安全最佳实践清单

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

必须做（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" 或 "always"）
提示词护栏已启用
运行 openclaw doctor 确认安全配置无误

强烈建议（HIGH）

防火墙已配置，OpenClaw 端口不对外暴露
使用 SSH 隧道或 VPN 进行远程访问
审计日志已启用
速率限制已配置
文件访问权限已配置（defaultPolicy: "deny"）
工具权限已配置（禁用不需要的工具）
Webhook 签名验证已启用

建议做（MEDIUM）

持续维护

定期更新到最新版本
定期检查日志中的异常事件
定期轮换 API Key 和 Token
关注 OpenClaw 安全公告

常见安全威胁和防护

威胁 1：提示词注入攻击

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

防护措施：

启用提示词护栏（guardrails: true）
启用注入检测（injection.detection: true）
限制 Agent 可用的工具
沙箱隔离执行环境

威胁 2：API Key 泄露

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

防护措施：

使用环境变量存储 Key
设置配置文件权限为 600
定期轮换 Key
监控 API 用量异常

威胁 3：未授权访问

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

防护措施：

设置 Gateway 认证（Token 或密码模式）
启用 DM 配对系统（dmPolicy: "pairing"）
配置用户权限分级
启用 IP 白名单
运行 openclaw doctor 检查配置

威胁 4：文件系统攻击

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

防护措施：

启用沙箱
配置文件访问权限（defaultPolicy: "deny"）
限制可写路径
阻止访问敏感目录（.ssh、.gnupg）

威胁 5：网络攻击

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

防护措施：

强制 TLS 1.3
绑定 127.0.0.1
配置防火墙
启用速率限制

威胁 6：供应链攻击

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

防护措施：

只安装来自可信来源的技能
审查技能的源代码
在沙箱中运行第三方技能
限制技能的权限

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

合规性考虑

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

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

数据最小化 — 只收集必要的数据。OpenClaw 默认不收集用户数据，但聊天记录和记忆系统会存储用户信息
数据本地化 — OpenClaw 的本地部署天然满足数据本地化要求
删除权 — 用户有权要求删除他们的数据

# 删除特定用户的所有数据
openclaw data delete --user "telegram:12345"

# 导出特定用户的数据（数据可携带权）
openclaw data export --user "telegram:12345" --output user-data.json

数据保留策略

// ~/.openclaw/openclaw.json
{
  "storage": {
    "retention": {
      "chatHistory": "90d",
      "auditLogs": "365d",
      "memories": "forever",
      "tempFiles": "7d",
    },
  }
}

其他合规框架

CCPA（加州消费者隐私法）— 类似 GDPR，关注用户数据权利
HIPAA（健康保险可携带性和责任法案）— 如果处理健康数据，需要额外的加密和访问控制
SOC 2 — 如果在企业环境中使用，需要完善的审计日志和访问控制

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

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

安全事件响应

事件分级

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

P0 事件应急流程

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

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

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

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

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

安全更新

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

# 检查更新
openclaw update check

# 更新到最新版
npm update -g openclaw@latest

# Docker 更新
cd openclaw && git pull && docker compose build && docker compose up -d

# 查看安全公告
openclaw security

建议：订阅 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：如何检测提示词注入攻击？

启用提示词护栏和注入检测
监控审计日志中的 injection.detected 事件
定期检查 Agent 的执行历史，看是否有异常操作
限制 Agent 的工具权限，减少攻击面

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

可以，但需要正确配置：

为每个用户分配不同的权限角色
启用用户级别的速率限制
配置独立的工作目录
启用审计日志追踪每个用户的操作

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

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

使用本地模型（Ollama）
查看 AI 提供商的数据使用政策
启用 API 请求日志，监控发送的数据

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

# 加密备份
tar czf - ~/.openclaw/ | openssl enc -aes-256-cbc -salt -out openclaw-backup.tar.gz.enc

# 解密恢复
openssl enc -d -aes-256-cbc -in openclaw-backup.tar.gz.enc | tar xzf - -C ~/

备份时注意：

备份文件也要设置严格的权限（chmod 600）
不要把备份上传到公开的云存储
定期测试备份的恢复流程

下一步

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

FilesExpand file tree

10-安全配置指南.md

Latest commit

History

10-安全配置指南.md

File metadata and controls

10. 安全配置指南

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

OpenClaw 安全架构概述

安全分层模型

安全组件关系

零信任原则

API Key 安全管理

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

环境变量管理

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

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

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

密钥轮换策略

密钥泄露检测

密钥泄露应急处理

沙箱系统详解

为什么需要沙箱？

沙箱模式配置

工具 Allowlist 与 Denylist

按 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 白名单

速率限制

数据隐私保护

本地部署的隐私优势

数据加密

静态数据加密

传输加密

配置文件保护

使用本地模型保护隐私

消息平台安全

Webhook 验证

Telegram

Discord

WhatsApp（通过 WhatsApp Business API）

Token 管理

提示词注入防护

启用提示词护栏

常见提示词注入模式

日志审计

审计日志配置

日志格式

日志监控与告警

日志安全

安全最佳实践清单

必须做（CRITICAL）

强烈建议（HIGH）

建议做（MEDIUM）

持续维护

常见安全威胁和防护

威胁 1：提示词注入攻击