[← 第 13 章](/openclaw-tutorial/13-%E6%95%99%E7%A8%8B%E8%87%AA%E5%8A%A8%E6%9B%B4%E6%96%B0%E4%B8%8E%E4%BB%93%E5%BA%93%E7%BB%B4%E6%8A%A4.html) · [📑 目录](/openclaw-tutorial/) · [📋 大纲](/openclaw-tutorial/OUTLINE.html) · [第 15 章 →](/openclaw-tutorial/15-Memory%20%E8%AE%B0%E5%BF%86%E7%B3%BB%E7%BB%9F%E6%B7%B1%E5%85%A5.html)

第 14 章:安全与权限管理

difficulty time chapter

难度: ⭐⭐⭐ 进阶 预计阅读: 22 分钟 前置章节: 第 2 章第 6 章

安全是生产级 Agent 系统的生命线。本章系统讲解 OpenClaw 的安全模型,包括设备认证、凭证管理、执行审批、Skill 沙箱隔离、网络安全策略和审计日志。你将学会如何在保障安全的前提下,为 Agent 提供恰当的权限范围,实现”最小权限、纵深防御”的安全架构。

📑 本章目录


14.1 OpenClaw 安全模型概述

OpenClaw 采用纵深防御(Defense in Depth)策略,在设备、凭证、执行、网络、审计五个层面构建安全屏障。

安全分层架构

┌─────────────────────────────────────────────────┐
│                 审计日志层                        │
│  config-audit.jsonl · 操作记录 · 异常监控        │
├─────────────────────────────────────────────────┤
│                 网络安全层                        │
│  TLS 加密 · IP 白名单 · 速率限制                  │
├─────────────────────────────────────────────────┤
│                 执行控制层                        │
│  exec-approvals · 沙箱隔离 · 权限声明            │
├─────────────────────────────────────────────────┤
│                 凭证管理层                        │
│  加密存储 · 隔离访问 · Vault 集成                 │
├─────────────────────────────────────────────────┤
│                 设备认证层                        │
│  设备指纹 · 配对验证 · Token 刷新                 │
└─────────────────────────────────────────────────┘

设备认证机制

每个 OpenClaw 实例在首次启动时会生成唯一的设备标识,存储于 ~/.openclaw/identity/ 目录。

# 查看当前设备身份信息
cat ~/.openclaw/identity/device.json
{
  "deviceId": "d-a3f8c1e2-7b94-4d6f-9e21-5c8a3f7b2d10",
  "createdAt": "2026-02-28T10:00:00Z",
  "fingerprint": "sha256:9f86d0...a3dcb",
  "version": "0.8.2"
}

设备认证文件包含认证令牌:

# 查看设备认证状态
cat ~/.openclaw/identity/device-auth.json
{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expiresAt": "2026-06-28T10:00:00Z",
  "scope": ["agent", "message", "skill"],
  "refreshToken": "rt_8f3a2b..."
}

[!WARNING] device-auth.json 包含认证令牌,切勿将其提交到版本控制系统或分享给他人。泄露该文件相当于泄露设备的全部权限。

凭证隔离原则

凭证隔离原则

OpenClaw 通过目录隔离和访问控制确保不同服务的凭证互不影响:

隔离维度 说明 示例
文件级隔离 每个服务独立凭证文件 feishu-pairing.json, github-copilot.token.json
权限级隔离 不同 Skill 只能访问声明的凭证 Skill A 不能读取 Skill B 的 Token
环境级隔离 生产 / 测试环境凭证分离 credentials/prod/ vs credentials/dev/
时间级隔离 令牌自动过期,定期轮换 Token TTL 配置

权限分级体系

OpenClaw 将权限分为四个等级:

Level 0 ─ 只读(read-only)
  └─ 读取文件、查看配置、浏览日志

Level 1 ─ 受限写入(restricted-write)
  └─ 写入 workspace/、memory/ 目录

Level 2 ─ 命令执行(command-exec)
  └─ 执行 Skill 脚本、CLI 命令

Level 3 ─ 系统管理(system-admin)
  └─ 修改系统配置、管理凭证、安装 Skill

[!NOTE] 默认情况下,Agent 运行在 Level 2 权限。提升到 Level 3 需要在 exec-approvals.json 中显式配置。


14.2 Credential 管理

凭证(Credential)是 OpenClaw 与外部服务交互的安全通行证,涵盖 API Key、OAuth Token、Webhook Secret 等。OpenClaw 提供了统一的凭证管理机制,确保所有敏感凭据以最小权限原则存储和访问,避免明文泄漏风险。

凭证目录结构

所有凭证文件集中存储在 ~/.openclaw/credentials/ 目录下:

# 查看凭证目录
ls -la ~/.openclaw/credentials/
total 24
drwx------ 2 root root 4096 Mar  6 10:00 .
-rw------- 1 root root  256 Mar  1 08:00 feishu-default-allowFrom.json
-rw------- 1 root root  384 Mar  1 08:00 feishu-pairing.json
-rw------- 1 root root  512 Mar  2 14:00 github-copilot.token.json

[!TIP] 注意文件权限为 600(仅所有者可读写),目录权限为 700(仅所有者可访问)。这是 OpenClaw 安装时自动设置的安全默认值。

添加凭证

添加凭证

# 方式 1:通过 CLI 命令添加凭证
openclaw credential add github-token \
  --type token \
  --value "ghp_xxxxxxxxxxxxxxxxxxxx" \
  --expires "2026-12-31"

# 方式 2:通过 JSON 文件手动添加
cat > ~/.openclaw/credentials/my-api-key.json << 'EOF'
{
  "type": "api-key",
  "service": "my-custom-service",
  "key": "sk-xxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-03-06T10:00:00Z",
  "expiresAt": "2026-09-06T10:00:00Z",
  "scope": ["read", "write"],
  "notes": "用于自定义 API 集成"
}
EOF

# 设置正确的文件权限
chmod 600 ~/.openclaw/credentials/my-api-key.json

更新与删除凭证

更新与删除凭证

# 更新凭证(会自动备份旧文件)
openclaw credential update github-token \
  --value "ghp_new_token_value" \
  --expires "2027-06-30"

# 删除凭证
openclaw credential remove my-api-key

# 列出所有凭证(不显示实际值)
openclaw credential list
NAME                    TYPE      SERVICE     EXPIRES        STATUS
github-token            token     github      2026-12-31     ✅ 有效
feishu-pairing          pairing   feishu      —              ✅ 有效
my-api-key              api-key   custom      2026-09-06     ✅ 有效
old-service-key         api-key   legacy      2026-01-01     ❌ 已过期

加密存储机制

加密存储机制

为了防止凭证在磁盘上以明文形式被窃取,OpenClaw 内置了基于 AES-256-GCM 的加密存储机制。加密后的凭证文件即使被拷贝到其他设备,也无法在缺少设备指纹的情况下解密,从而实现凭证与设备的强绑定。

OpenClaw 支持对凭证文件进行 AES-256 加密存储:

# 启用凭证加密
openclaw credential encrypt --all

# 仅加密指定凭证
openclaw credential encrypt github-token

# 查看加密状态
openclaw credential status
{
  "encryption": {
    "enabled": true,
    "algorithm": "AES-256-GCM",
    "keyDerivation": "PBKDF2",
    "encryptedFiles": 3,
    "plaintextFiles": 0
  }
}

[!WARNING] 启用加密后,加密密钥派生自设备指纹。如果迁移设备,需要先导出凭证再在新设备上导入: ```bash

旧设备:导出

OpenClaw credential export –output credentials-backup.enc

新设备:导入

OpenClaw credential import –input credentials-backup.enc ```bash

凭证管理命令速查

凭证管理命令速查

命令 功能 示例
openclaw credential add 添加凭证 openclaw credential add my-key --type token --value sk-abc123
openclaw credential update 更新凭证 openclaw credential update my-key --value sk-def456
openclaw credential remove 删除凭证 openclaw credential remove my-key
openclaw credential list 列出凭证 openclaw credential list --format table
openclaw credential encrypt 加密凭证 openclaw credential encrypt --all
openclaw credential export 导出凭证 openclaw credential export --output backup.enc
openclaw credential import 导入凭证 openclaw credential import --input backup.enc

14.3 执行审批机制

执行审批是 OpenClaw 安全模型的核心环节。Agent 执行命令前,系统会检查 exec-approvals.json 决定是否允许执行。

exec-approvals.json 配置详解

# 查看当前审批配置
cat ~/.openclaw/exec-approvals.json
{
  "version": "1.0",
  "defaultPolicy": "prompt",
  "rules": [
    {
      "id": "allow-read-commands",
      "pattern": "^(cat|ls|head|tail|grep|find|wc|echo|pwd|whoami)\\b",
      "action": "allow",
      "description": "允许常见的只读命令"
    },
    {
      "id": "allow-git-readonly",
      "pattern": "^git\\s+(status|log|diff|branch|remote|show)",
      "action": "allow",
      "description": "允许 Git 只读操作"
    },
    {
      "id": "deny-destructive",
      "pattern": "^(rm\\s+-rf|mkfs|dd\\s+if=|shutdown|reboot)",

      "action": "deny",
      "description": "禁止危险的系统命令"
    },
    {
      "id": "prompt-git-write",
      "pattern": "^git\\s+(push|merge|rebase|reset)",
      "action": "prompt",
      "description": "Git 写操作需要人工确认"
    },
    {
      "id": "allow-openclaw-commands",
      "pattern": "^openclaw\\s+",
      "action": "allow",
      "description": "允许 OpenClaw 自身命令"
    }
  ],
  "auditLog": true,
  "maxPendingApprovals": 5,
  "approvalTimeoutSeconds": 300
}

配置字段说明:

字段 类型 说明
version string 配置版本号
defaultPolicy string 未匹配任何规则时的默认策略:allow / deny / prompt
rules array 审批规则列表,按顺序匹配
rules[].pattern string 正则表达式,匹配命令内容
rules[].action string 匹配后的动作:allow(放行)、deny(拒绝)、prompt(人工确认)
auditLog boolean 是否记录审计日志
maxPendingApprovals number 最大排队等待审批数
approvalTimeoutSeconds number 审批超时(秒),超时自动拒绝

自动审批模式

自动审批模式

对于信任度高的环境,可以配置自动审批模式:

{
  "defaultPolicy": "allow",
  "rules": [
    {
      "id": "deny-destructive",
      "pattern": "^(rm\\s+-rf\\s+/|mkfs|dd\\s+if=|shutdown|reboot)",
      "action": "deny",
      "description": "只拦截极端危险命令"
    }
  ]
}

[!WARNING] 自动审批模式(defaultPolicy: "allow")仅建议在完全受控的开发环境中使用。生产环境请使用 "prompt""deny" 作为默认策略。

交互式审批

当命令匹配 "prompt" 策略时,Agent 会暂停执行并通过消息通道通知用户:

🔒 执行审批请求
━━━━━━━━━━━━━━━━━━━━━━━
命令:git push origin main
匹配规则:prompt-git-write
风险评估:中
━━━━━━━━━━━━━━━━━━━━━━━
请回复 ✅ 批准 或 ❌ 拒绝
超时时间:5 分钟

审批策略对比

策略 安全级别 适用场景 用户干预
deny 为默认 ⭐⭐⭐⭐⭐ 生产环境、金融系统 几乎所有命令需审批
prompt 为默认 ⭐⭐⭐⭐ 标准生产环境 仅白名单命令自动执行
allow + 黑名单 ⭐⭐ 开发/测试环境 仅极端危险命令被拦截
allow 无规则 临时调试(不推荐) 无任何限制

14.4 Skill 权限声明与沙箱隔离

_meta.json 权限字段

每个 Skill 目录下的 _meta.json 文件声明了该 Skill 所需的权限:

{
  "name": "web-search-skill",
  "version": "1.2.0",
  "author": "zxk",
  "permissions": {
    "network": {
      "outbound": ["api.tavily.com", "api.duckduckgo.com"],
      "inbound": false
    },
    "filesystem": {
      "read": ["~/.openclaw/workspace/memory/"],
      "write": ["~/.openclaw/workspace/memory/"]
    },
    "commands": {
      "allowed": ["curl", "wget", "python3"],
      "denied": ["rm", "sudo", "chmod"]
    },
    "credentials": ["tavily-api-key"],
    "sandbox": "standard"

  },
  "description": "Web 搜索能力封装"
}

权限字段详解:

字段 说明 可选值
permissions.network.outbound 允许访问的外部域名列表 域名数组或 true/false
permissions.network.inbound 是否允许接收外部请求 true/false
permissions.filesystem.read 允许读取的目录 路径数组
permissions.filesystem.write 允许写入的目录 路径数组
permissions.commands.allowed 允许执行的命令列表 命令名数组
permissions.commands.denied 明确禁止的命令列表 命令名数组
permissions.credentials 需要访问的凭证名称 凭证名数组
permissions.sandbox 沙箱模式 "none", "standard", "strict"

沙箱模式

OpenClaw 提供三种沙箱隔离级别:

┌────────────────────────────────────────────────────────┐
│  Strict(严格模式)                                      │
│  ├─ 独立文件系统命名空间                                 │
│  ├─ 网络访问受限于白名单                                 │
│  ├─ 禁止访问宿主系统信息                                 │
│  └─ 超时自动终止(默认 60s)                              │
├────────────────────────────────────────────────────────┤
│  Standard(标准模式)—— 默认                              │
│  ├─ 限制文件系统访问范围                                 │
│  ├─ 允许声明的网络访问                                   │
│  ├─ 命令执行受 exec-approvals 控制                       │
│  └─ 超时自动终止(默认 300s)                             │
├────────────────────────────────────────────────────────┤
│  None(无沙箱)                                          │
│  ├─ 不限制文件系统访问                                   │
│  ├─ 不限制网络访问                                       │
│  ├─ 命令执行仍受 exec-approvals 控制                     │
│  └─ 仅建议用于受信任的自有 Skill                          │
└────────────────────────────────────────────────────────┘
# 查看某个 Skill 的权限声明
cat ~/.openclaw/workspace/skills/web-search/_meta.json | python3 -m json.tool

# 验证 Skill 权限是否合规(如果有 openclaw skill audit 命令)
openclaw skill audit web-search

权限声明最佳实践

权限声明最佳实践

原则 说明 示例
最小权限 只声明实际需要的权限 不要 "outbound": true,应列出具体域名
明确边界 denied 明确禁止危险命令 "denied": ["rm", "sudo"]
分离职责 不同功能拆分为不同 Skill 搜索和写入分别封装
凭证最小化 每个 Skill 只访问自己的凭证 不要共享 credentials 引用
标准沙箱 默认使用 "standard" 模式 只有内部工具使用 "none"

[!TIP] 在开发新 Skill 时,建议先使用 "strict" 模式,逐步放宽必需权限,而非从 "none" 开始逐步收紧。


14.5 网络安全

TLS 配置

OpenClaw 的所有外部通信默认使用 TLS 加密:

// openclaw.json 中的 TLS 配置段
{
  "security": {
    "tls": {
      "enabled": true,
      "minVersion": "1.2",
      "cipherSuites": [
        "TLS_AES_256_GCM_SHA384",
        "TLS_CHACHA20_POLY1305_SHA256",
        "TLS_AES_128_GCM_SHA256"
      ],
      "certificatePath": "/etc/openclaw/certs/server.crt",
      "keyPath": "/etc/openclaw/certs/server.key"
    }
  }
}
# 检查当前 TLS 配置
openclaw config get security.tls

# 验证证书有效性
openssl x509 -in /etc/openclaw/certs/server.crt -noout -dates

IP 白名单

IP 白名单

限制只有特定 IP 地址可以连接到 OpenClaw 的服务端口:

{
  "security": {
    "network": {
      "allowedIPs": [
        "127.0.0.1",
        "10.0.0.0/8",
        "192.168.1.0/24"
      ],
      "denyByDefault": true
    }
  }
}

速率限制

防止 API 滥用和暴力攻击:

{
  "security": {
    "rateLimit": {
      "enabled": true,
      "windowMs": 60000,
      "maxRequests": 100,
      "message": "请求过于频繁,请稍后重试",
      "perIP": true,
      "whitelist": ["127.0.0.1"]
    }
  }
}
参数 说明 推荐值
windowMs 时间窗口(毫秒) 60000(1 分钟)
maxRequests 窗口期内最大请求数 100
perIP 是否按 IP 独立计数 true
whitelist 不受限制的 IP 列表 仅 localhost

14.6 敏感信息保护

环境变量管理

将敏感信息存储在环境变量中,避免硬编码:

# 在 Skill 脚本中引用环境变量(推荐)
#!/bin/bash
API_KEY="${TAVILY_API_KEY:?环境变量 TAVILY_API_KEY 未设置}"
curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.tavily.com/search" \
  -d '{"query": "OpenClaw tutorial"}'
# 配置 Skill 运行时环境变量
# 在 _meta.json 中声明需要的环境变量
cat > ~/.openclaw/workspace/skills/my-skill/_meta.json << 'EOF'
{
  "name": "my-skill",
  "env": {
    "required": ["API_KEY", "API_SECRET"],
    "optional": ["DEBUG_MODE"]
  },
  "permissions": {
    "sandbox": "standard"
  }
}
EOF

Vault 集成

Vault 集成

对于企业级部署,OpenClaw 支持与 HashiCorp Vault 集成:

// openclaw.json 中的 Vault 配置
{
  "security": {
    "vault": {
      "enabled": true,
      "address": "https://vault.example.com:8200",
      "authMethod": "token",
      "secretPath": "secret/data/openclaw",
      "tokenEnvVar": "VAULT_TOKEN",
      "cacheTTL": 3600
    }
  }
}
# 验证 Vault 连接
export VAULT_TOKEN="hvs.xxxxxxxxxxxxxxxx"
export VAULT_ADDR="https://vault.example.com:8200"

# 测试连接
vault status

# 读取 OpenClaw 的 Secret
vault kv get secret/data/openclaw

在 Skill 中引用 Vault Secret:

# Skill 配置中使用 Vault 引用
env:
  API_KEY: "vault:secret/data/openclaw#api_key"
  DB_PASSWORD: "vault:secret/data/openclaw#db_password"

敏感信息防泄漏检查

敏感信息防泄漏检查

# 扫描工作空间中的潜在敏感信息
grep -rn --include='*.md' --include='*.json' --include='*.yaml' \
  -E '(password|secret|token|api.?key)\s*[:=]\s*["\x27][^"\x27]{8,}' \
  ~/.openclaw/workspace/

# 检查 Git 历史中是否有敏感信息泄漏
git log --all --diff-filter=A --name-only --pretty=format: \
  | sort -u | grep -iE '(secret|credential|token|key)'

# 使用 .gitignore 排除敏感文件
cat ~/.openclaw/.gitignore
# .gitignore 安全相关条目
credentials/
identity/
*.token.json
*.secret.json
exec-approvals.json

[!NOTE] OpenClaw 默认的 .gitignore 已包含凭证和认证目录的排除规则。安装新 Skill 时需确认其 .gitignore 规则是否完善。


14.7 安全审计日志

config-audit.jsonl 格式解读

OpenClaw 将所有安全相关事件记录到 ~/.openclaw/logs/config-audit.jsonl,采用 JSONL(每行一个 JSON 对象)格式:

# 查看最近的审计日志
tail -5 ~/.openclaw/logs/config-audit.jsonl | python3 -m json.tool

日志条目示例:

{
  "timestamp": "2026-03-06T14:30:22.456Z",
  "eventType": "command.execute",
  "level": "info",
  "actor": "agent-main",
  "action": "exec",
  "command": "git status",
  "matchedRule": "allow-git-readonly",
  "result": "allowed",
  "duration": 234,
  "sessionId": "sess-a1b2c3d4"
}

{
  "timestamp": "2026-03-06T14:31:05.789Z",
  "eventType": "command.execute",
  "level": "warn",
  "actor": "agent-main",
  "action": "exec",
  "command": "rm -rf /tmp/old-data",
  "matchedRule": "deny-destructive",
  "result": "denied",
  "reason": "匹配到危险命令拦截规则",
  "sessionId": "sess-a1b2c3d4"
}

{
  "timestamp": "2026-03-06T14:32:00.123Z",
  "eventType": "credential.access",
  "level": "info",
  "actor": "skill:web-search",
  "action": "read",
  "credential": "tavily-api-key",
  "result": "allowed",
  "sessionId": "sess-a1b2c3d4"
}

日志查询与分析

日志查询与分析

# 查询所有被拒绝的命令执行
grep '"result":"denied"' ~/.openclaw/logs/config-audit.jsonl | \
  python3 -m json.tool

# 按事件类型统计
cat ~/.openclaw/logs/config-audit.jsonl | \
  python3 -c "
import json, sys
from collections import Counter
events = Counter()
for line in sys.stdin:
    try:
        obj = json.loads(line)
        events[obj.get('eventType', 'unknown')] += 1
    except: pass
for k, v in events.most_common():
    print(f'{v:>6}  {k}')
"

# 筛选特定时间范围的日志
grep '"2026-03-06T14' ~/.openclaw/logs/config-audit.jsonl | wc -l

# 查找凭证访问记录
grep '"credential.access"' ~/.openclaw/logs/config-audit.jsonl | \
  python3 -c "
import json, sys
for line in sys.stdin:
    obj = json.loads(line)
    print(f\"{obj['timestamp']}  {obj['actor']:20s}  {obj['credential']}\")
"

告警规则配置

告警规则配置

可以在配置中设置安全告警,当特定事件触发时自动通知:

{
  "security": {
    "alerts": {
      "enabled": true,
      "channel": "feishu-default",
      "rules": [
        {
          "name": "异常拒绝",
          "condition": "denied_count > 10 in 5m",
          "severity": "high",
          "message": "⚠️ 5 分钟内命令被拒绝超过 10 次"
        },
        {
          "name": "凭证访问异常",
          "condition": "credential.access from unknown_actor",
          "severity": "critical",
          "message": "🚨 未知来源尝试访问凭证"
        },
        {

          "name": "非工作时间操作",
          "condition": "command.execute outside 08:00-22:00",
          "severity": "medium",
          "message": "📌 非工作时间有命令执行"
        }
      ]
    }
  }
}

进阶:安全架构原理

OpenClaw 的安全模型基于多层防护架构:

安全层 机制 作用
命令执行 exec-approvals.json 按命令模式分级审批(allow/prompt/deny)
文件访问 沙箱隔离 限制 Agent 文件系统访问范围
API 调用 credentials 管理 Token 加密存储,按需授权
审计追踪 config-audit.jsonl 记录所有安全相关操作

这种纵深防御策略确保即使单层被绕过,其他层仍能提供保护。



进阶:安全架构原理

OpenClaw 安全模型基于多层防护架构:

安全层 机制 作用
命令执行 exec-approvals.json 按模式分级审批
文件访问 沙箱隔离 限制文件系统访问
API 调用 credentials 管理 Token 加密存储
审计追踪 config-audit.jsonl 记录安全操作


实操练习

以下练习帮助你掌握 OpenClaw 安全管理的核心技能。请按顺序完成。

练习 1:审查当前安全配置

目标:了解当前环境的安全状态。

# 步骤 1:查看设备身份信息
cat ~/.openclaw/identity/device.json

# 步骤 2:列出所有凭证文件及权限
ls -la ~/.openclaw/credentials/

# 步骤 3:查看执行审批配置
cat ~/.openclaw/exec-approvals.json | python3 -m json.tool

# 步骤 4:检查审计日志最后 10 条记录
tail -10 ~/.openclaw/logs/config-audit.jsonl | python3 -m json.tool

# 步骤 5:确认文件权限是否满足安全要求
stat -c '%a %n' ~/.openclaw/credentials/* ~/.openclaw/identity/*

练习 2:配置自定义审批规则

练习 2:配置自定义审批规则

目标:为特定场景创建安全审批规则。

# 步骤 1:备份当前配置
cp ~/.openclaw/exec-approvals.json ~/.openclaw/exec-approvals.json.bak

# 步骤 2:添加自定义规则 — 允许 Python 脚本执行,但限制 pip 安装
cat ~/.openclaw/exec-approvals.json | python3 -c "
import json, sys
config = json.load(sys.stdin)
config['rules'].insert(-1, {
    'id': 'allow-python-exec',
    'pattern': '^python3?\\\\s+',
    'action': 'allow',
    'description': '允许执行 Python 脚本'
})
config['rules'].insert(-1, {
    'id': 'prompt-pip-install',
    'pattern': '^pip3?\\\\s+install',
    'action': 'prompt',
    'description': 'pip 安装需要人工确认'
})
print(json.dumps(config, indent=2, ensure_ascii=False))
" > /tmp/exec-approvals-new.json

# 步骤 3:验证 JSON 格式正确后替换
python3 -c "import json; json.load(open('/tmp/exec-approvals-new.json')); print('✅ JSON 格式正确')"
cp /tmp/exec-approvals-new.json ~/.openclaw/exec-approvals.json

# 步骤 4:验证新规则生效
cat ~/.openclaw/exec-approvals.json | python3 -m json.tool

练习 3:Skill 权限声明练习

练习 3:Skill 权限声明练习

目标:为一个模拟 Skill 编写权限声明。

# 步骤 1:创建练习 Skill 目录
mkdir -p ~/.openclaw/workspace/skills/security-demo

# 步骤 2:编写 _meta.json
cat > ~/.openclaw/workspace/skills/security-demo/_meta.json << 'EOF'
{
  "name": "security-demo",
  "version": "1.0.0",
  "permissions": {
    "network": {
      "outbound": ["httpbin.org"],
      "inbound": false
    },
    "filesystem": {
      "read": ["~/.openclaw/workspace/memory/"],
      "write": []
    },
    "commands": {
      "allowed": ["curl", "echo"],
      "denied": ["rm", "sudo", "chmod", "chown"]
    },
    "credentials": [],
    "sandbox": "strict"

  }
}
EOF

# 步骤 3:编写 SKILL.md
cat > ~/.openclaw/workspace/skills/security-demo/SKILL.md << 'EOF'
# security-demo

安全演示 Skill,用于验证权限隔离。

## 功能
- 发起 HTTP 请求到 httpbin.org(仅测试用途)
- 读取 memory 目录中的文件

## 权限
- 网络:仅允许访问 httpbin.org
- 文件系统:仅允许读取 memory/
- 沙箱模式:strict
EOF

# 步骤 4:审计权限声明
openclaw skill audit security-demo

练习 4:审计日志分析

练习 4:审计日志分析

目标:从审计日志中提取安全洞察。

# 步骤 1:统计各事件类型数量
cat ~/.openclaw/logs/config-audit.jsonl | \
  python3 -c "
import json, sys
from collections import Counter
c = Counter()
for line in sys.stdin:
    try:
        c[json.loads(line).get('eventType','?')] += 1
    except: pass
for k,v in c.most_common(10):
    print(f'{v:>6}  {k}')
"

# 步骤 2:找出所有被拒绝的操作
grep '"denied"' ~/.openclaw/logs/config-audit.jsonl | \
  python3 -c "
import json, sys
for line in sys.stdin:
    try:
        obj = json.loads(line)
        t = obj.get('timestamp','')
        cmd = obj.get('command','N/A')
        reason = obj.get('reason','')
        print(f'{t}  CMD: {cmd}  REASON: {reason}')
    except: pass
"

# 步骤 3:生成安全摘要报告
echo "=== 安全审计摘要 ==="
echo "日志总条数: $(wc -l < ~/.openclaw/logs/config-audit.jsonl)"
echo "拒绝操作数: $(grep -c '"denied"' ~/.openclaw/logs/config-audit.jsonl)"
echo "凭证访问数: $(grep -c 'credential.access' ~/.openclaw/logs/config-audit.jsonl)"
echo "最后活动时间: $(tail -1 ~/.openclaw/logs/config-audit.jsonl | python3 -c 'import json,sys;print(json.loads(sys.stdin.read()).get(\"timestamp\",\"N/A\"))')"

常见问题 (FAQ)

Q1:忘记了凭证加密密码怎么办?

A:凭证加密密钥派生自设备指纹,无需手动输入密码。如果设备身份文件损坏,可以:

# 1. 检查设备身份文件是否完整
cat ~/.openclaw/identity/device.json

# 2. 如果损坏,需要重新初始化并重新添加所有凭证
openclaw init --reset-identity

# 3. 重新添加凭证
openclaw credential add github-token --type token --value "ghp_xxx"

Q2:exec-approvals.json 格式错误导致 Agent 无法执行命令?

Q2:exec-approvals.json 格式错误导致 Agent 无法执行命令?

A:恢复备份文件:

# 使用备份恢复
cp ~/.openclaw/exec-approvals.json.bak ~/.openclaw/exec-approvals.json

# 或使用默认安全配置
openclaw config reset exec-approvals

Q3:如何限制 Agent 只能操作特定目录?

Q3:如何限制 Agent 只能操作特定目录?

A:结合 exec-approvals 和 Skill 权限:

{
  "rules": [
    {
      "id": "restrict-workspace",
      "pattern": "^(cat|ls|head|tail)\\s+(?!(/root/.openclaw/workspace|~/.openclaw/workspace))",
      "action": "deny",
      "description": "只允许操作 workspace 目录"
    }
  ]
}

参考来源

来源 链接 说明
OpenClaw 官方文档 https://docs.OpenClaw.ai 官方安装与配置手册
OpenClaw GitHub https://github.com/OpenClaw/OpenClaw 源码与 Issue 追踪
ClawHub 平台 https://hub.OpenClaw.ai Skills 市场与文档

Troubleshooting

问题 1:凭证解密失败,提示 decryption error: invalid key

症状:迁移设备后运行 openclaw credential list 或 Agent 调用凭证时报解密错误,表明当前设备指纹与加密时使用的不匹配。

解决方案

# 方式 1:在旧设备上导出凭证(推荐迁移前操作)
openclaw credential export --output credentials-backup.enc

# 在新设备上导入
openclaw credential import --input credentials-backup.enc

# 方式 2:如果旧设备已不可用,手动重新添加凭证
openclaw credential add github-token   --type token   --value "ghp_your_new_token"

# 重新启用加密
openclaw credential encrypt --all

问题 2:执行命令时提示 Permission denied by exec-approvals

症状:Agent 尝试执行命令时被拒绝,日志显示 exec-approvals 策略阻止了该操作。

解决方案

# 查看当前审批配置
cat ~/.openclaw/exec-approvals.json | python3 -m json.tool

# 检查被拒绝的命令是否匹配了 deny 规则
grep -n "deny" ~/.openclaw/exec-approvals.json

# 如需允许特定命令,添加到 allow 列表
# 编辑 exec-approvals.json,在 allow 数组中增加对应的命令模式
openclaw config edit exec-approvals

# 验证配置生效
openclaw doctor --check permissions

问题 3:凭证文件权限异常,Skill 无法读取凭证

症状:Agent 运行时报错 credential file permission error,通常是凭证文件的 Unix 权限被意外修改。

解决方案

# 检查凭证目录和文件权限
ls -la ~/.openclaw/credentials/

# 修复权限:目录 700,文件 600
chmod 700 ~/.openclaw/credentials/
chmod 600 ~/.openclaw/credentials/*.json

# 验证修复结果
openclaw credential status

本章小结


[← 上一章:教程自动更新与仓库维护](/openclaw-tutorial/13-%E6%95%99%E7%A8%8B%E8%87%AA%E5%8A%A8%E6%9B%B4%E6%96%B0%E4%B8%8E%E4%BB%93%E5%BA%93%E7%BB%B4%E6%8A%A4.html) · [📑 返回目录](/openclaw-tutorial/) · [下一章:Memory 记忆系统深入 →](/openclaw-tutorial/15-Memory%20%E8%AE%B0%E5%BF%86%E7%B3%BB%E7%BB%9F%E6%B7%B1%E5%85%A5.html)