10-安全配置指南

10 安全配置指南 10 安全配置指南 Modified June 10 • 限制可写路径 • 阻止访问敏感目录（.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 的本地部署天然满足数据本地化要求 • 删除权 — 用户有权要求删除他们的数据 ⠀ Code block Plain Text 导出特定用户的数据（数据可携带权） openclaw backup create output user data.json 如需清除数据，可使用 reset 命令 openclaw reset user "telegram:12345" ⠀ 数据保留策略 ⠀ OpenClaw 没有内置的 storage.retention 配置字段。数据保留需要手动管理： ⠀ Code block Plain Text 手动清理超过 90 天的会话日志 find /.openclaw/workspace/sessions/ name " .jsonl" mtime +90 delete 归档超过 30 天的每日记忆日志 mkdir p /.openclaw/workspace/memory/archive mv /.openclaw/workspace/memory/2025 .md /.openclaw/workspace/memory/archive/ 用 Git 追踪记忆变更（推荐） cd /.openclaw/workspace && git init && git add . && git commit m "memory snapshot" ⠀ 建议定期清理旧数据，既节省磁盘空间，也减少潜在的数据泄露风险。 ⠀ 其他合规框架 ⠀ • CCPA（加州消费者隐私法）— 类似 GDPR，关注用户数据权利 • HIPAA（健康保险可携带性和责任法案）— 如果处理健康数据，需要额外的加密和访问控制 • SOC 2 — 如果在企业环境中使用，需要完善的审计日志和访问控制 ⠀ OpenClaw 的本地部署模式天然满足大部分合规要求，因为数据不离开你的控制范围。但调用云端 AI API 时，数据会发送到提供商，需要评估提供商的合规性。 ⏭️ 小白可跳过 — 这部分面向安全专家和企业用户 ⠀ 安全事件响应 ⠀ 事件分级 ⠀ 级别 描述 响应时间 示例 P0 紧急 系统被入侵，数据泄露 立即 API Key 泄露、未授权访问 P1 高 安全漏洞被发现 4 小时内 沙箱逃逸、提示词注入成功 P2 中 可疑活动 24 小时内 异常登录尝试、异常 API 用量 P3 低 安全配置问题 1 周内 权限配置不当、日志未启用 ⠀ P0 事件应急流程 ⠀ Code block Plain Text 1. 立即隔离 停止 OpenClaw 服务：openclaw gateway stop 断开网络连接（如果可能） 2. 评估影响 检查审计日志：确定攻击范围 检查文件系统：是否有文件被修改 检查 API 用量：是否有异常调用 3. 遏制损害 撤销所有 API Key 更换 Gateway Token 更换 Bot Token 4. 恢复服务 生成新的 Key 和 Token 更新配置 重启服务 验证安全配置 5. 复盘 记录事件时间线 分析根本原因 制定改进措施 更新安全配置 ⠀ 安全更新 ⠀ OpenClaw 更新非常频繁，安全修复通常在 24 小时内发布： ⠀ Code block Plain Text 检查更新 openclaw update status 更新到最新版 npm update g openclaw@latest Docker 更新 cd openclaw && git pull && docker compose build && docker compose up d 查看安全公告 openclaw security ⠀ 建议：订阅 OpenClaw 的 GitHub Security Advisories，第一时间获取安全更新通知。v2026.5.22 已包含 protobufjs 8.4.0 安全更新；v2026.5.27 又补充多项内容边界和远程暴露防护。如果你用 Docker 或固定 npm tag，升级后要重新构建镜像并保留 lockfile / shrinkwrap 完整性校验。 常见问题 ⠀ Q：我在本地跑 OpenClaw，还需要配置安全吗？ ⠀ 需要。即使在本地，也要设置 Gateway Token 和文件访问权限。原因： • 本地网络中的其他设备可能访问你的 OpenClaw • 恶意消息仍然可能通过消息平台到达你的 Agent • 提示词注入攻击不依赖网络位置 ⠀ Q：沙箱会影响性能吗？ ⠀ Docker 沙箱会有轻微的性能开销（通常 < 5%）。对于大多数使用场景，这个开销可以忽略不计。如果你对性能非常敏感，可以： • 增加沙箱的资源限制（maxMemory、maxCpu） • 对不需要沙箱的 Agent 单独关闭（不推荐） • 使用进程级沙箱替代 Docker 沙箱 ⠀ Q：API Key 泄露了怎么办？ ⠀ 1. 立即去提供商后台撤销泄露的 Key 2. 生成新 Key 并更新配置 3. 检查 API 用量是否有异常 4. 从 git 历史和日志中清除泄露的 Key 5. 复盘泄露原因，防止再次发生 ⠀ Q：如何检测提示词注入攻击？ ⠀ • 在 SOUL.md 中设置安全行为约束 • 监控日志中的可疑操作 • 定期检查 Agent 的执行历史，看是否有异常操作 • 限制可写路径 • 阻止访问敏感目录（.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 时，数据会发送到提供商，需要评估提供商的合规性。 OpenClaw 的本地部署模式天然满足大部分合规要求，因为数据不离开你的控制范围。但调用云端 AI API 时，数据会发送到提供商，需要评估提供商的合规性。 ⏭️ 小白可跳过 — 这部分面向安全专家和企业用户 ⏭️ 小白可跳过 — 这部分面向安全专家和企业用户 ⠀ 安全事件响应 ⠀ 事件分级 ⠀ 级别 描述 响应时间 示例 P0 紧急 系统被入侵，数据泄露 立即 API Key 泄露、未授权访问 P1 高 安全漏洞被发现 4 小时内 沙箱逃逸、提示词注入成功 P2 中 可疑活动 24 小时内 异常登录尝试、异常 API 用量 P3 低 安全配置问题 1 周内 权限配置不当、日志未启用 级别 级别 描述 描述 响应时间 响应时间 示例 示例 P0 紧急 P0 紧急 系统被入侵，数据泄露 系统被入侵，数据泄露 立即 立即 API Key 泄露、未授权访问 API Key 泄露、未授权访问 P1 高 P1 高 安全漏洞被发现 安全漏洞被发现 4 小时内 4 小时内 沙箱逃逸、提示词注入成功 沙箱逃逸、提示词注入成功 P2 中 P2 中 可疑活动 可疑活动 24 小时内 24 小时内 异常登录尝试、异常 API 用量 异常登录尝试、异常 API 用量 P3 低 P3 低 安全配置问题 安全配置问题 1 周内 1 周内 权限配置不当、日志未启用 权限配置不当、日志未启用 ⠀ P0 事件应急流程 ⠀ ⠀ 安全更新 ⠀ OpenClaw 更新非常频繁，安全修复通常在 24 小时内发布： ⠀ ⠀ 建议：订阅 OpenClaw 的 GitHub Security Advisories，第一时间获取安全更新通知。v2026.5.22 已包含 protobufjs 8.4.0 安全更新；v2026.5.27 又补充多项内容边界和远程暴露防护。如果你用 Docker 或固定 npm tag，升级后要重新构建镜像并保留 lockfile / shrinkwrap 完整性校验。 建议：订阅 OpenClaw 的 GitHub Security Advisories，第一时间获取安全更新通知。v2026.5.22 已包含 protobufjs 8.4.0 安全更新；v2026.5.27 又补充多项内容边界和远程暴露防护。如果你用 Docker 或固定 npm tag，升级后要重新构建镜像并保留 lockfile / shrinkwrap 完整性校验。 常见问题 ⠀ Q：我在本地跑 OpenClaw，还需要配置安全吗？ ⠀ 需要。即使在本地，也要设置 Gateway Token 和文件访问权限。原因： • 本地网络中的其他设备可能访问你的 OpenClaw • 恶意消息仍然可能通过消息平台到达你的 Agent • 提示词注入攻击不依赖网络位置 ⠀ Q：沙箱会影响性能吗？ ⠀ Docker 沙箱会有轻微的性能开销（通常 < 5%）。对于大多数使用场景，这个开销可以忽略不计。如果你对性能非常敏感，可以： • 增加沙箱的资源限制（maxMemory、maxCpu） • 对不需要沙箱的 Agent 单独关闭（不推荐） • 使用进程级沙箱替代 Docker 沙箱 ⠀ Q：API Key 泄露了怎么办？ ⠀ 1. 立即去提供商后台撤销泄露的 Key 2. 生成新 Key 并更新配置 3. 检查 API 用量是否有异常 4. 从 git 历史和日志中清除泄露的 Key 5. 复盘泄露原因，防止再次发生 ⠀ 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. 常见问题 看看其他人踩过的坑！ 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 难度等级：🔴 高级 • 阅读时间：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）策略，分为五个层次： ⠀ ⠀ 每一层都是独立的防线。即使某一层被突破，下一层仍然能提供保护。不要只依赖单一安全措施。 ⠀ 安全组件关系 ⠀ ⠀ 零信任原则 ⠀ OpenClaw 的安全设计遵循零信任原则： ⠀ • 不信任任何输入 — 所有用户消息都经过过滤和验证 • 不信任任何网络 — 即使在内网也使用 TLS（传输层安全协议，保护网络通信不被窃听）加密 • 不信任任何执行 — 所有工具调用都在沙箱（Sandbox，限制 AI 执行危险操作的隔离环境）中隔离运行 • 最小权限 — Agent 只拥有完成任务所需的最少权限 • 持续验证 — 每次操作都重新检查权限，不依赖缓存的认证状态 API Key 安全管理 ⠀ API Key 是 OpenClaw 最敏感的资产。一旦泄露，攻击者可以用你的额度调用模型，甚至访问你的账户数据。 ⠀ 基本原则：永远不要硬编码 ⠀ ⠀ 环境变量管理 ⠀ 方法一：系统环境变量（推荐用于服务器） ⠀ ⠀ 方法二：.env 文件（推荐用于开发） ⠀ ⠀ OpenClaw 启动时会自动读取 /.openclaw/.env 文件。 ⠀ 方法三：密钥管理服务（推荐用于团队/企业） ⠀ ⠀ v2026.5.27 安全更新：models status 会保留 SecretRef backed custom provider 的 apiKey 标记，避免把解析后的明文 secret 写回 models.json。doctor 也会提示明文 secret bearing config fields。v2026.5.26 / v2026.5.27 继续强化安全边界：Browser snapshot URL 需过 SSRF policy，外部文件文本会作为 external content 包装，群提示词元数据不进入 system prompt，side effecting command wrapper、unsafe Node runtime env override、no auth Tailscale 暴露和未授权 node/device role approval 都会被阻断。团队配置里优先使用 SecretRef、环境变量或外部密钥服务，不要把 provider API key 和敏感 headers 写成普通 JSON 字段。 v2026.5.27 安全更新：models status 会保留 SecretRef backed custom provider 的 apiKey 标记，避免把解析后的明文 secret 写回 models.json。doctor 也会提示明文 secret bearing config fields。v2026.5.26 / v2026.5.27 继续强化安全边界：Browser snapshot URL 需过 SSRF policy，外部文件文本会作为 external content 包装，群提示词元数据不进入 system prompt，side effecting command wrapper、unsafe Node runtime env override、no auth Tailscale 暴露和未授权 node/device role approval 都会被阻断。团队配置里优先使用 SecretRef、环境变量或外部密钥服务，不要把 provider API key 和敏感 headers 写成普通 JSON 字段。 ⠀ 推荐排查顺序： ⠀ 1. openclaw doctor 看是否提示 plaintext secret。 2. 检查 /.openclaw/openclaw.json 是否含真实 key。 3. 检查 shell history 和日志里是否打印过 key。 4. 迁移到 SecretRef / 环境变量后重启 Gateway。 ⠀ 示例文档里如果必须出现占位符，使用 secret scanner safe placeholder，例如 YOUR OPENAI API KEY，不要写看起来像真实 token 的长字符串。配置 include path 也要使用明确文件名和最小目录范围；新版会加强 include path validation，路径过宽时应当改成显式白名单。 ⠀ 密钥轮换策略 ⠀ 定期更换 API Key 是安全最佳实践。建议每 90 天轮换一次。 ⠀ ⠀ 密钥泄露检测 ⠀ ⠀ 密钥泄露应急处理 ⠀ 如果你发现 Key 已经泄露： ⠀ 1. 立即撤销 — 去提供商后台撤销泄露的 Key 2. 生成新 Key — 创建新的 API Key 3. 更新配置 — 用新 Key 替换所有引用 4. 检查用量 — 查看是否有异常 API 调用 5. 清理历史 — 从 git 历史、日志文件中清除泄露的 Key 6. 复盘原因 — 找出泄露的根本原因，防止再次发生 沙箱系统详解 ⠀ 沙箱是 OpenClaw 安全架构中最关键的一环。它确保 Agent 执行的代码和命令被隔离在受控环境中，不会影响宿主机。 ⠀ 为什么需要沙箱？ ⠀ 想象一下这个场景：有人给你的 Agent 发了一条消息："帮我整理一下文件"，但消息中嵌入了恶意指令，让 Agent 执行 rm rf / 或者读取 /etc/passwd。没有沙箱的话，这些命令会直接在你的机器上执行。 ⠀ 沙箱模式配置 ⠀ OpenClaw 使用 mode 字段控制沙箱行为，而非简单的 enabled 开关。最常用的模式是 "non main"，表示非主会话在 Docker 沙箱中运行，主会话保持正常执行： ⠀ ⠀ mode 值 说明 适用场景 "non main" 非主会话在 Docker 沙箱中运行 生产环境推荐默认值 "all" 所有会话都在沙箱中运行 高安全要求场景 "off" 禁用沙箱 仅限开发/调试 mode 值 mode 值 说明 说明 适用场景 适用场景 "non main" "non main" 非主会话在 Docker 沙箱中运行 非主会话在 Docker 沙箱中运行 生产环境推荐默认值 生产环境推荐默认值 "all" "all" 所有会话都在沙箱中运行 所有会话都在沙箱中运行 高安全要求场景 高安全要求场景 "off" "off" 禁用沙箱 禁用沙箱 仅限开发/调试 仅限开发/调试 ⠀ 工具 Allow 与 Deny ⠀ 沙箱内可用的工具通过 tools.allow/tools.deny 控制（注意：不是 toolAllowlist/toolDenylist）： ⠀ v2026.5.20+ 迁移注意：旧的 cat SKILL.md && printf ... && <skill wrapper allowlist 兼容路径已移除。Skill 文件必须通过 read tool 加载，自动允许的只能是真正的 skill executable。升级后如果原来的 allowlist 脚本失效，不要放宽成全局 allow；应改成按真实命令、真实工具和 owner 身份重新授权。 v2026.5.20+ 迁移注意：旧的 cat SKILL.md && printf ... && <skill wrapper allowlist 兼容路径已移除。Skill 文件必须通过 read tool 加载，自动允许的只能是真正的 skill executable。升级后如果原来的 allowlist 脚本失效，不要放宽成全局 allow；应改成按真实命令、真实工具和 owner 身份重新授权。 ⠀ ⠀ 按 Agent 配置不同的沙箱策略 ⠀ 不同的 Agent 可以覆盖默认的沙箱模式： ⠀ ⠀ 沙箱逃逸防护 ⠀ OpenClaw 的 Docker 沙箱支持以下安全加固选项（在 sandbox.docker 下配置）： ⠀ ⠀ • capDrop: ["ALL"] — 移除所有 Linux capabilities，最小权限原则 • readOnlyRoot: true — 根文件系统只读，防止恶意写入 • tmpfs — 挂载临时文件系统的路径列表，容器销毁后数据消失 ⠀ 注意：securityOpt、noSetuid 等字段在 OpenClaw 配置中不存在。如需额外的 Docker 安全选项，应在 docker compose.yml 或 Docker 运行命令中直接配置。 注意：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 认证 ⠀ ⠀ 方式二：密码认证 ⠀ ⠀ ⠀ 凭证存储 ⠀ Gateway 认证凭证存储在 /.openclaw/credentials 文件中。确保该文件权限正确： ⠀ ⠀ 认证要求： • Token 至少 32 个字符 • 使用密码学安全的随机数生成 • 不要使用可猜测的字符串（比如 password123、admin） • 不同环境（开发、测试、生产）使用不同的凭证 • gateway.bind 必须是 loopback 地址（127.0.0.1），除非通过 Tailscale（零配置 VPN 工具，让你安全地远程访问）等安全隧道暴露 ⠀ DM Pairing 配对系统（配对机制，新用户首次私聊 AI 时需要你手动批准） ⠀ 配对系统控制谁可以给你的 Agent 发私信（DM）。默认策略是 "pairing"：当未知发送者发来消息时，Agent 会回复一个配对码，你需要手动批准。 ⠀ dmPolicy 策略 ⠀ ⠀ 配对操作 ⠀ ⠀ 公开模式（谨慎使用） ⠀ 如果你确实需要让 Agent 接受所有人的消息，可以使用公开模式： ⠀ ⠀ 强烈建议：保持默认的 "pairing" 策略。公开模式意味着任何人都能控制你的 Agent，仅在受信任的封闭环境中使用。 强烈建议：保持默认的 "pairing" 策略。公开模式意味着任何人都能控制你的 Agent，仅在受信任的封闭环境中使用。 ⠀ 安全诊断 ⠀ 使用 openclaw doctor 检查配对系统和其他安全配置是否正确： ⠀ ⠀ openclaw doctor 会检查： • 配对系统是否启用 • Gateway 认证是否配置 • 沙箱是否启用 • 文件权限是否正确 • 其他安全配置项 ⠀ 用户访问控制 ⠀ OpenClaw 采用单一信任边界安全模型：每个 Gateway 实例对应一个受信任的操作者。它不是多租户 RBAC 系统，不支持在同一个 Gateway 上为不同用户分配不同权限角色。 ⠀ 访问控制通过以下机制实现： ⠀ • DM 配对系统 — 默认策略 pairing，未知发送者需要输入配对码，操作者审批后才能对话 • allowFrom 白名单 — 在 channels 中配置允许的发送者列表 • 多 Agent 隔离 — 不同用户路由到不同 Agent，每个 Agent 有独立的 workspace 和工具权限 ⠀ ⠀ 如果需要多用户隔离，应该为每个信任边界部署独立的 Gateway 实例（独立的 OS 用户/主机），而不是在一个 Gateway 上做角色分级。 如果需要多用户隔离，应该为每个信任边界部署独立的 Gateway 实例（独立的 OS 用户/主机），而不是在一个 Gateway 上做角色分级。 ⠀ 工具权限控制 ⠀ 工具的权限控制通过 sandbox（沙箱）和审批系统实现，而不是通过 tools.permissions 字段。tools 顶层字段用于配置工具本身的参数（如 tools.web.search.apiKey），不包含权限控制结构。 ⠀ 实际的工具权限控制方式： ⠀ 1. 沙箱隔离 — 限制 Agent 能做什么 ⠀ ⠀ 2. 审批系统 — 运行时控制工具调用 ⠀ ⠀ 3. Agent 级别的工具限制 ⠀ 通过 SOUL.md（Agent 人格文件）明确告诉 AI 哪些操作是禁止的： ⠀ ⠀ 文件访问权限 ⠀ 文件系统是最需要保护的资源之一。OpenClaw 通过沙箱隔离和操作系统级别的权限来保护文件系统，而不是通过配置文件中的路径规则。 ⠀ 实际的文件保护方式： ⠀ 1. 沙箱隔离（推荐） ⠀ 通过沙箱模式限制 Agent 的文件访问： ⠀ ⠀ 2. 操作系统权限 ⠀ 通过 Unix 文件权限限制 OpenClaw 进程的访问范围： ⠀ ⠀ 3. SOUL.md 行为约束 ⠀ 通过 Agent 人格文件明确禁止访问敏感路径： ⠀ ⠀ 这种多层防护（沙箱 + OS 权限 + AI 行为约束）比单一的配置文件规则更可靠。 网络安全 ⠀ TLS 1.3（v2026.2.1 强制） ⠀ 从 v2026.2.1 开始，OpenClaw 强制使用 TLS 1.3 作为最低标准。 ⠀ ⠀ 使用 Let's Encrypt 获取免费证书 ⠀ ⠀ 自签名证书（仅用于开发/测试） ⠀ ⠀ 自签名证书仅用于开发环境。生产环境请使用 Let's Encrypt 或其他 CA 签发的证书。 自签名证书仅用于开发环境。生产环境请使用 Let's Encrypt 或其他 CA 签发的证书。 ⠀ 绑定地址 ⠀ Gateway 默认绑定 127.0.0.1（仅本地访问）。gateway.bind 必须是 loopback 地址，除非你明确知道自己在做什么。 ⠀ ⠀ 如果需要远程访问，推荐使用 SSH 隧道、Tailscale 或 VPN，而不是直接暴露端口： ⠀ ⠀ Tailscale Serve/Funnel 的优势：Gateway 仍然绑定 127.0.0.1，Tailscale 在网络层处理加密和认证，无需手动配置 TLS 证书。Funnel 模式会自动提供公网 HTTPS 端点。 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： ⠀ ⠀ 2. 反向代理场景 ⠀ 如果 TLS 由反向代理（如 Nginx）终止，使用 trustedProxies 确保 OpenClaw 能正确获取客户端 IP： ⠀ ⠀ 注意区分： 上面的 trustedProxies 用于 IP 检测场景（告诉 Gateway 信任代理传来的 X Forwarded For）。如果你使用 trusted proxy 认证模式（gateway.auth.mode: "trusted proxy"），则 trustedProxies 不能填 loopback 地址。详见本文后面的"反向代理 Forwarded Headers 安全模型"章节。 注意区分： 上面的 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 认证路径的攻击。 ⠀ 配置要点： ⠀ ⠀ 安全检查清单： ⠀ • 反向代理必须覆盖（不是追加）来自客户端的转发头 • 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，在配置中明确拒绝这些工具： ⠀ ⠀ 插件白名单（Plugin Allowlist，v2026.4.5+） ⠀ 从 v2026.4.5 开始，OpenClaw 引入了插件级别的白名单机制： ⠀ • 插件白名单持久化：