第9章安全第一：权限与沙箱

🎯 本章目标：学完这章，你能建立安全意识，知道”怎么放开能力但不翻车”

⏱️ 预计时间：20分钟

📋 前置要求：已完成第8章（配置文件）

本章你将学会什么

为什么Agent更需要最小权限
工具权限配置（allow/deny/profile策略）
执行审批配置（高风险动作的二次确认）
沙箱模式（session/agent/shared）
凭证管理最佳实践
成本控制策略

9.1 为什么Agent更需要最小权限

9.1.1 一个假设场景

假设你给了Agent这些能力：

读写文件
执行任意命令
发送邮件
访问数据库

然后你让它”帮我清理一下旧文件”。

可能的结果：

✅ 正常情况：删除了/tmp下的临时文件
❌ 异常情况：误删了重要数据
❌ 最坏情况：被恶意提示词诱导，执行了危险操作

9.1.2 最小权限原则

只给Agent完成当前任务所需的最小权限。

就像你不会给实习生root密码一样，也不要给Agent不必要的权限。

9.2 工具权限配置

9.2.1 先知道“在哪儿配”

先把位置记住：
工具权限统一配在 ~/.openclaw/openclaw.json。

你可以用命令改（更稳）：

# 看当前工具档位
openclaw config get tools.profile

# 改成最保守的最小档
openclaw config set tools.profile "minimal"

如果你本机执行 openclaw config 报 unknown command 'config'，就手动编辑 ~/.openclaw/openclaw.json，效果一样。

9.2.2 三种配置方式（小白常用）

方式一：profile 预设（先用这个）

{
  "tools": {
    "profile": "minimal"
  }
}

方式二：allow 白名单（只放你明确要用的）

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

方式三：deny 黑名单（在已有能力上再加保险）

{
  "tools": {
    "profile": "coding",
    "deny": ["group:runtime"]
  }
}

再给你一个“全局+单个Agent覆盖”的真实例子：

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging" }
      }
    ]
  }
}

9.2.3 profile详解

profile	包含的工具	适用场景
minimal	仅 `session_status`	最保守，先跑通再放权
messaging	`group:messaging` + 会话基础工具	消息收发型机器人
coding	`group:fs`、`group:runtime`、`group:sessions`、`group:memory`、`image`	开发助手
full	不限制（等同未设置）	仅限你已做完隔离与审批

9.2.4 常见工具清单（按工具组记就行）

group:fs：read / write / edit / apply_patch
group:runtime：exec / process / bash
group:web：web_search / web_fetch
group:messaging：message
group:sessions：sessions_list / sessions_history / sessions_send / sessions_spawn / session_status
group:automation：cron / gateway

你只要记一条：
新手默认 minimal 或 messaging，确认稳定后再升到 coding。

9.3 执行审批：高风险动作的二次确认

9.3.1 配置审批策略

这块很多人会误会，我先说结论：

执行审批主要管的是 主机上的命令执行（host=gateway 或 host=node）。
审批策略存放在：~/.openclaw/exec-approvals.json（不是 openclaw.json）。

工作原理：

Agent 发起高风险 exec
系统生成审批请求
你在控制台/聊天里批准或拒绝
通过后再执行，不通过就拦截

9.3.2 审批命令

# 查看当前审批快照
openclaw approvals get

# 更新审批策略（从 JSON 文件加载）
openclaw approvals set ./approvals.json

# 编辑每个 Agent 的执行放行清单
openclaw approvals allowlist

9.3.3 审批通知

如果你已接入聊天渠道，还可以在聊天里直接处理审批：

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

9.4 沙箱配置

9.4.1 什么是沙箱

**沙箱（Sandbox）**是一个隔离的执行环境，限制Agent能访问的资源。

类比：

普通环境 = 实习生可以在整栋楼里走动
沙箱环境 = 实习生只能在自己的工位上工作

9.4.2 先分清 mode 和 scope

官方是两层概念，不是一个 type 能说完：

mode：什么时候启用沙箱（off / non-main / all）
scope：沙箱按谁隔离（session / agent / shared）

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

mode 解释：

off：关闭沙箱
non-main：只给“非主会话”开沙箱（常用）
all：所有会话都走沙箱（最严格）

scope 解释：

session（推荐）：
每个对话session有独立的临时目录
适合多用户和高隔离场景
agent：
每个Agent有独立的工作目录
适合一个Agent长期任务
shared：
所有沙箱会话共享一个环境
协作方便，但隔离最弱

9.4.3 沙箱路径配置

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "scope": "session",
        "workspaceAccess": "rw",
        "docker": {
          "binds": ["/Users/you/projects:/workspace/projects:rw"]
        }
      }
    }
  }
}

小白建议：先用 mode=non-main + scope=session + workspaceAccess=none，跑稳了再逐步放开。

9.5 凭证管理

9.5.1 API Key存储

不要：

把Key直接写在配置文件里（如果配置文件会提交到Git）
把Key截图发到群里
把Key保存在不加密的地方

9.5.2 使用环境变量

# 设置环境变量
export KIMI_API_KEY="sk-xxx"
export MINIMAX_API_KEY="xxx"

在配置文件中引用

{
  "models": {
    "primary": {
      "provider": "kimi",
      "apiKey": "${KIMI_API_KEY}"
    }
  }
}

9.5.3 使用系统密钥管理器

macOS（Keychain）：

# 存储Key
security add-generic-password -s "openclaw-kimi" -a "user" -w "sk-xxx"

# 在配置中引用（需要配合脚本）

Linux（secret-tool）：

# 存储Key
secret-tool store --label="OpenClaw KIMI" provider kimi key apikey

# 读取
secret-tool lookup provider kimi key apikey

9.6 成本控制

这一节给你最不容易翻车的“三层控费法”：

9.6.1 第一层：先在模型厂商后台设月度预算

别等超额了才补救。
KIMI / MiniMax / GLM 都有自己的套餐与用量页面，先把预算和告警阈值设好。

9.6.2 第二层：用工具权限限制“高成本动作”

默认用 minimal 或 messaging
真要开发时再切 coding
不需要跑命令就长期 deny: ["group:runtime"]

这一步会直接减少无效调用、错误重试和连锁成本。

9.6.3 第三层：每周做一次“配置体检”

每周固定检查三件事：

当前 tools.profile 是不是比实际需求更大；
有没有忘记关掉高风险工具；
是否出现“反复失败重试”的任务模式（这种最烧钱）。

本章小结

安全配置的核心原则：

最小权限 —— 只给必要的工具
审批确认 —— 高风险操作要二次确认
沙箱隔离 —— 限制Agent能访问的资源
凭证保护 —— 用环境变量或密钥管理器
分层控费 —— 预算、权限、巡检三层兜底

下一步：第10章，了解OpenClaw的Tools全景。

动手试试

检查你当前的tools配置
把profile改成minimal，测试功能变化
配置一个需要审批的操作
尝试使用环境变量存储API Key
到模型厂商后台设置月度预算和提醒阈值

第9章 安全第一：权限与沙箱