## 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"
}
}
```
### 密钥管理最佳实践
| 做法 | 推荐 |
|------|------|
| 使用环境变量或 SecretRef | ✅ |
| 密钥文件权限设为 600 | ✅ |
| 定期轮换 API Key | ✅ |
| 在 .gitignore 中排除密钥文件 | ✅ |
| 在代码中硬编码密钥 | ❌ |
| 在日志中输出密钥 | ❌ |
| 在 AGENTS.md 中写入密钥 | ❌ |
## 形式化验证简介
OpenClaw 使用 **TLA+** 形式化验证来确保核心协议的正确性。
### 什么是形式化验证
形式化验证是用数学方法证明系统设计的正确性，而不仅仅依赖测试。TLA+ 是一种规范语言，可以描述系统的所有可能状态，并验证关键属性是否始终成立。
### OpenClaw 验证了什么
OpenClaw 使用 TLA+ 验证了以下关键属性：
- **消息顺序**：消息按正确顺序处理，不会乱序
- **会话一致性**：会话状态在并发操作下保持一致
- **故障恢复**：Gateway 重启后能正确恢复状态
### 对用户的意义
形式化验证意味着 OpenClaw 的核心逻辑经过了数学级别的正确性保证，而不仅仅是"测试通过了"。这在处理并发、分布式场景时尤其重要。
> 💡 形式化验证是 OpenClaw 区别于其他 AI Gateway 的重要特性之一。
## 安全检查清单
部署 OpenClaw 到生产环境前，对照以下清单检查：
- [ ] Gateway 已启用认证（Token 或密码）
- [ ] 认证 Token 至少 32 字符
- [ ] 渠道配置了白名单或配对
- [ ] 工具权限已按需配置（非 allow: *）
- [ ] 不受信任的技能在沙箱中运行
- [ ] API Key 通过环境变量或 SecretRef 管理
- [ ] secrets.json 文件权限为 600
- [ ] .gitignore 排除了所有密钥文件
- [ ] Gateway 不直接暴露到公网（使用反向代理）
- [ ] 已配置 SSL/TLS 证书
## 小结
- OpenClaw 的安全模型分为 5 层，层层防护
- Gateway 认证是第一道防线，生产环境必须启用
- 工具权限控制防止智能体越权操作
- 沙箱隔离保护宿主系统安全
- 密钥管理使用 SecretRef 或环境变量，永远不要硬编码
- 形式化验证提供数学级别的正确性保证
#安全最佳实践 #认证配置 #权限控制 #密钥管理 #龙虾技能库