OpenClaw 安全模型概述
OpenClaw 作为自托管的 AI Gateway，安全是核心设计原则之一。安全模型分为多个层次： ``
┌─────────────────────────────────┐
│ 第 1 层：Gateway 认证 │ ← 谁能访问 Gateway
├─────────────────────────────────┤
│ 第 2 层：渠道安全 │ ← 谁能通过渠道对话
├─────────────────────────────────┤
│ 第 3 层：工具权限控制 │ ← 智能体能用什么工具
├─────────────────────────────────┤
│ 第 4 层：沙箱隔离 │ ← 代码在哪里执行
├─────────────────────────────────┤
│ 第 5 层：密钥管理 │ ← 敏感信息如何存储
└─────────────────────────────────┘
`
每一层都是独立的安全屏障，即使某一层被突破，其他层仍然提供保护。
Gateway 认证
Gateway 是 OpenClaw 的核心入口，保护 Gateway 的访问权限是第一道防线。
认证方式
OpenClaw 支持三种 Gateway 认证方式：
#### 1. Token 认证（推荐）
使用随机生成的 Token 进行认证：
`json
{
"gateway": {
"auth": {
"type": "token",
"token": "your-secret-token-here"
}
}
}
`
生成安全的随机 Token：
`bash
openssl rand -hex 32
`
#### 2. 密码认证
使用用户名和密码：
`json
{
"gateway": {
"auth": {
"type": "password",
"username": "admin",
"password": "your-strong-password"
}
}
}
`
> ⚠️ 密码认证适合个人使用，生产环境建议使用 Token 认证。
#### 3. 可信代理认证
当 Gateway 在反向代理（如 Nginx）后面时，可以信任代理的认证：
`json
{
"gateway": {
"auth": {
"type": "trusted-proxy",
"trustedProxies": ["127.0.0.1", "10.0.0.0/8"]
}
}
}
`
> ⚠️ 只在你完全控制代理服务器时使用此方式。错误配置可能导致未授权访问。
认证最佳实践
- 生产环境必须启用认证，不要裸跑 Gateway
- Token 至少 32 字符，使用随机生成
- 定期轮换 Token（建议每 90 天）
- 不要在代码仓库中提交认证信息
渠道安全
渠道是用户与智能体交互的入口，需要控制谁能通过渠道对话。
配对机制（Pairing）
某些渠道（如 WhatsApp）使用配对机制——只有通过配对流程的设备才能与智能体通信：
`bash
WhatsApp 配对
openclaw channels login whatsapp
扫描二维码完成配对
`
配对后，只有配对的手机号码才能与智能体对话。
白名单（Allowlist）
限制只有特定用户才能与智能体交互：
`json
{
"channels": {
"telegram": {
"allowlist": [
"123456789",
"987654321"
]
}
}
}
`
不在白名单中的用户发送消息会被忽略。
群组安全
在群组中，智能体默认只响应被 @ 提及的消息：
`json
{
"channels": {
"telegram": {
"groupBehavior": "mention-only"
}
}
}
`
| 模式 | 说明 |
|------|------|
| mention-only | 只响应 @ 提及（推荐） |
| all | 响应所有消息 |
| none | 在群组中不响应 |
工具权限控制
工具权限控制决定智能体能使用哪些工具，是防止智能体"越权操作"的关键。
Allow / Deny 列表
明确允许或禁止特定工具：
`json
{
"tools": {
"allow": [
"web_search",
"read",
"write"
],
"deny": [
"exec",
"browser"
]
}
}
`
- allow：白名单模式，只允许列出的工具
- deny：黑名单模式，禁止列出的工具
- 两者同时存在时，deny 优先
工具分组
使用预定义的工具组简化配置：
`json
{
"tools": {
"allow": [
"group:fs",
"group:web"
],
"deny": [
"group:runtime"
]
}
}
`
| 工具组 | 包含的工具 | 风险等级 |
|--------|-----------|---------|
| group:fs | read、write、list | 中 |
| group:web | web_search、web_fetch | 低 |
| group:runtime | exec、process | 高 |
| group:browser | browser 系列 | 中 |
工具配置文件（tools.profile）
为不同场景创建工具配置文件：
`json
{
"tools": {
"profiles": {
"safe": {
"allow": ["web_search", "read"],
"deny": ["exec", "browser", "write"]
},
"developer": {
"allow": ["*"],
"deny": []
},
"readonly": {
"allow": ["read", "web_search"],
"deny": ["write", "exec", "browser"]
}
},
"activeProfile": "safe"
}
}
`
沙箱隔离
沙箱通过 Docker 容器隔离智能体的代码执行环境，防止恶意代码影响宿主系统。
启用沙箱
`json
{
"sandbox": {
"mode": "docker"
}
}
`
沙箱提供的隔离
| 隔离维度 | 说明 |
|----------|------|
| 文件系统 | 只能访问挂载的目录 |
| 网络 | 可配置网络访问限制 |
| 进程 | 容器内进程与宿主隔离 |
| 资源 | CPU 和内存限制 |
何时该用沙箱
- ✅ 运行不受信任的第三方技能
- ✅ 执行用户提供的代码
- ✅ 处理来自公开渠道的请求
- ❌ 纯文本对话（无需沙箱）
- ❌ 只使用 web_search 等安全工具
> 📖 详细配置请参考《沙箱隔离专题教程》。
第三方技能安全审查
安装第三方技能前，务必进行安全审查。
安全扫描等级
龙虾技能库为每个技能提供安全扫描结果：
| 等级 | 含义 | 建议 |
|------|------|------|
| 🟢 Pass | 未发现安全问题 | 可以放心安装 |
| 🟡 Warning | 存在潜在风险 | 仔细阅读扫描报告 |
| 🔴 Fail | 发现安全问题 | 不建议安装 |
| ⚪ Unknown | 未扫描 | 谨慎使用 |
审查要点
安装技能前检查以下内容：
1. requires.bins — 技能需要哪些系统命令
`yaml
SKILL.md frontmatter
requires:
bins:
- docker
- git
`
如果一个"天气查询"技能要求 docker 和 ssh 权限，这就很可疑。
2. 工具权限 — 技能请求使用哪些工具
`yaml
requires:
tools:
- exec
- write
`
3. 环境变量 — 技能需要哪些敏感信息
`yaml
requires:
env:
- GITHUB_TOKEN
- DATABASE_URL
`
安装时限制权限
安装技能时可以限制其权限：
`bash
clawhub install some-skill --allow-tools web_search,read
`
密钥管理
环境变量
最基本的密钥管理方式——通过环境变量传递：
`bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
`
Secrets 配置
在 openclaw.json 中使用 secrets 引用：
`json
{
"providers": {
"openai": {
"apiKey": {
"$ref": "secrets.OPENAI_API_KEY"
}
}
}
}
`
Secrets 存储在 ~/.openclaw/secrets.json（权限应设为 600）：
`json
{
"OPENAI_API_KEY": "sk-...",
"ANTHROPIC_API_KEY": "sk-ant-..."
}
`
`bash
设置文件权限（仅所有者可读写）
chmod 600 ~/.openclaw/secrets.json
`
SecretRef 机制
SecretRef 允许在配置中引用密钥而不暴露明文：
`json
{
"apiKey": {
"type": "SecretRef",
"name": "OPENAI_API_KEY"
}
}
``