一、整体安全架构：五层纵深防御体系

OpenClaw 采用分层安全模型，从入口到数据层层设防，单一层面被突破也不会全盘失守，是自托管网关的核心安全基石。

plaintext

第一层：Gateway 访问认证 → 管控谁能接入核心网关
第二层：聊天渠道准入 → 管控谁能发起对话交互
第三层：工具权限管控 → 管控AI可执行的操作能力
第四层：运行沙箱隔离 → 管控代码/脚本执行环境
第五层：敏感密钥保护 → 管控API Key、令牌等隐私数据

二、第一层防护：Gateway 网关认证（入口第一道锁）

网关是整个服务的流量入口，生产环境严禁裸奔，必须开启认证。

2.1 三种认证模式选型与配置

1. Token 认证（生产环境首选）

安全性最高，推荐所有公网 / 服务器部署使用。

json

{
  "gateway": {
    "auth": {
      "type": "token",
      "token": "你的32位随机密钥"
    }
  }
}

生成高强度随机 Token（Linux/macOS 终端执行）：

bash

运行

openssl rand -hex 32

2. 账号密码认证（仅个人本地使用）

适合单机自用、内网环境，不建议对外暴露。

json

{
  "gateway": {
    "auth": {
      "type": "password",
      "username": "admin",
      "password": "高强度复杂密码"
    }
  }
}

3. 可信代理认证（搭配 Nginx 反向代理使用）

网关部署在代理后端时启用，仅信任指定 IP 段，务必严格限制代理 IP。

json

{
  "gateway": {
    "auth": {
      "type": "trusted-proxy",
      "trustedProxies": ["127.0.0.1", "192.168.1.0/24"]
    }
  }
}

2.2 网关安全硬性规范

1. 公网环境强制开启认证，禁止无认证对外发布；
2. Token 长度不低于 32 位，使用随机字符，不使用弱口令、语义单词；
3. 定期轮换令牌，建议每 90 天更新一次 Token / 密码；
4. 配置文件、脚本、代码仓库绝对不要明文提交认证密钥；
5. 网关不直接暴露公网，前端搭配反向代理 + SSL 证书。

三、第二层防护：聊天渠道安全（交互入口管控）

针对 Telegram、WhatsApp、微信、QQ 等对接渠道，拦截非法用户、管控群聊行为。

3.1 设备配对机制（WhatsApp 等专用）

依赖二维码配对登录，仅已绑定设备 / 手机号可通信，天然形成第一道门槛：

bash

运行

openclaw channels login whatsapp

提示：不随意分享登录二维码，避免他人盗用会话。

3.2 用户白名单（核心防骚扰 / 防入侵）

仅允许指定 ID / 手机号接入，黑名单用户直接拒收消息，所有通用渠道均支持。

json

{
  "channels": {
    "telegram": {
      "allowlist": ["123456789", "987654321"]
    }
  }
}

3.3 群组消息行为管控

限制群聊触发规则，防止机器人被恶意刷屏、滥用：

json

{
  "channels": {
    "telegram": {
      "groupBehavior": "mention-only"
    }
  }
}

表格

配置值	效果	适用场景
mention-only	仅被 @才回复（推荐）	绝大多数群聊
all	响应群内全部消息	内部专属小群
none	群聊完全不响应	禁止群聊交互

四、第三层防护：工具权限控制（限制 AI 操作能力）

管控智能体可调用的系统工具，杜绝执行高危命令、读写敏感文件，防止越权操作。

4.1 黑白名单基础配置

deny 黑名单优先级高于 allow 白名单，二选一或组合使用。

json

{
  "tools": {
    "allow": ["web_search", "read"],
    "deny": ["exec", "browser", "write"]
  }
}

• allow：白名单模式，仅放行列表内工具（推荐，最小权限原则）
• deny：黑名单模式，禁用指定高危工具

4.2 预定义工具组（简化批量配置）

官方内置分组，按风险等级归类，快速批量授权 / 禁用：

json

{
  "tools": {
    "allow": ["group:fs", "group:web"],
    "deny": ["group:runtime"]
  }
}

表格

工具分组	包含能力	风险等级
group:fs	文件读取、列表查看	中风险
group:web	网页搜索、内容拉取	低风险
group:runtime	命令执行、进程管理	高风险（生产建议禁用）
group:browser	浏览器自动化	中风险

4.3 多场景工具配置方案（Profile 配置文件）

预设多套权限模板，按需快速切换安全策略：

json

{
  "tools": {
    "profiles": {
      "safe": {
        "allow": ["web_search", "read"],
        "deny": ["exec", "browser", "write"]
      },
      "readonly": {
        "allow": ["read", "web_search"],
        "deny": ["write", "exec"]
      },
      "developer": {
        "allow": ["*"],
        "deny": []
      }
    },
    "activeProfile": "safe"
  }
}

建议：对外服务默认使用 safe 安全模板，开发调试临时切换权限。

五、第四层防护：沙箱隔离（代码执行环境隔离）

通过 Docker 容器实现环境隔离，用户代码、第三方脚本仅在沙箱内运行，杜绝污染宿主机。

5.1 启用沙箱

json

{
  "sandbox": {
    "mode": "docker"
  }
}

5.2 沙箱隔离能力

• 文件系统：仅允许访问指定挂载目录，无法读取宿主机隐私文件
• 网络：可限制外网 / 内网访问权限
• 进程：容器进程与宿主机完全隔离，互不干扰
• 资源：限制 CPU、内存占用，防止资源耗尽攻击

5.3 沙箱使用场景建议

✅ 必须开启沙箱：公开渠道接入、运行第三方技能、执行用户自定义代码

❌ 可关闭沙箱：纯文字问答、仅使用网页搜索 / 文件读取等低风险工具

六、第五层防护：密钥与敏感信息管理

统一管理 API Key、令牌、数据库地址等核心密钥，杜绝明文泄露。

6.1 主流密钥存放方式

方式 1：系统环境变量（简易方案）

bash

运行

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

方式 2：Secrets 独立密钥文件（推荐）

1. 密钥统一存放在 ~/.openclaw/secrets.json

json

{
  "OPENAI_API_KEY": "sk-xxx",
  "FEISHU_SECRET": "xxx"
}

1. 严格设置文件权限（仅所有者可读可写）

bash

运行

chmod 600 ~/.openclaw/secrets.json

1. 配置文件通过引用调用密钥，不出现明文

json

{
  "providers": {
    "openai": {
      "apiKey": { "$ref": "secrets.OPENAI_API_KEY" }
    }
  }
}

方式 3：SecretRef 标准引用机制

专用密钥引用格式，全程隐藏明文：

json

{
  "apiKey": {
    "type": "SecretRef",
    "name": "OPENAI_API_KEY"
  }
}

6.2 密钥管理铁律

✅ 推荐做法

• 统一使用环境变量 / Secrets 引用
• 密钥文件权限固定为 600
• 定期轮换 API Key、机器人令牌
• 代码仓库配置 .gitignore 排除密钥文件

❌ 严禁做法

• 配置文件、文档、注释中硬编码密钥
• 日志输出、聊天记录打印密钥内容
• 将密钥写入 SOUL.md、AGENTS.md 等会话文件

七、第三方技能安全审查

安装外部技能前做安全核验，避免引入恶意脚本、越权工具。

7.1 技能安全等级识别

平台内置安全扫描评级，快速判断风险：

• 🟢 Pass：无安全问题，可直接安装
• 🟡 Warning：存在潜在风险，仔细核对权限后使用
• 🔴 Fail：高危问题，禁止安装
• ⚪ Unknown：未扫描，谨慎评估后再使用

7.2 三大核心审查要点

查看技能 SKILL.md 配置，检查依赖与权限：

1. 系统依赖（requires.bins） 非运维类技能却要求 ssh、docker 等高危命令，判定可疑。
2. 工具权限（requires.tools） 普通查询技能申请 exec、write 执行 / 写入权限，判定可疑。
3. 环境变量（requires.env） 索要数据库地址、全局令牌等敏感字段，提高警惕。

7.3 安装时临时限制权限

安装技能时手动收紧权限，最小化风险：

bash

运行

clawhub install 技能名 --allow-tools web_search,read

八、附加保障：形式化验证

OpenClaw 核心逻辑基于 TLA+ 形式化验证，用数学逻辑证明系统稳定性：

1. 保证消息有序处理，不会乱序、丢失
2. 高并发下会话状态稳定，不会错乱
3. 网关重启、异常宕机后可正常恢复状态

区别于普通测试，该特性从底层规避并发、分布式场景下的隐性安全漏洞。

九、生产环境上线安全检查清单

正式对外部署前，逐项核对，确保无安全短板：

• Gateway 已启用 Token / 代理认证，未裸跑公网
• 认证密钥长度达标，使用随机强密钥
• 聊天渠道已配置白名单 / 设备配对，限制访问人群
• 群组行为设为 mention-only，防止滥用
• 工具权限使用白名单，未全开 allow: *
• 执行代码 / 第三方技能已开启 Docker 沙箱
• 所有 API 密钥使用 Secrets / 环境变量，无明文硬编码
• secrets.json 权限为 600，已加入忽略列表
• 网关前端部署反向代理，配置 SSL/TLS 加密
• 定期密钥轮换、日志审计机制已规划

十、总结

1. 五层纵深防御各司其职：网关认证锁入口、渠道管控拦访客、工具权限限能力、沙箱隔离护系统、密钥管理防泄露；
2. 全程遵循最小权限原则，能禁用的高危功能一律关闭；
3. 密钥、认证令牌拒绝明文存储，做好权限与隔离；
4. 第三方技能先审查再安装，公开场景务必启用沙箱；
5. 上线前对照检查清单核验，长期使用定期轮换密钥、审计日志。

严格落地以上规范，可让 OpenClaw 无论是个人自用、内网部署还是公网对外服务，都具备企业级安全防护能力。