概念

Security 是 OpenClaw 的「護欄」— 限制 agent 能做什麼、不能做什麼。

三層防護：

Tool Policy — 允許/禁止特定工具
Exec Sandbox — 隔離執行環境
SSRF Protection — 防止內網攻擊

Tool Policy

// openclaw.json
{
  "tools": {
    "allow": ["exec", "read", "write", "edit", "browser"],
    "deny": ["message"],  // 禁止發訊息
    
    // Per-agent 覆寫
    "agents": {
      "dev-agent": {
        "allow": ["exec", "read", "write", "edit"],
        "deny": ["browser"]  // elizabeth 不能用 browser
      }
    }
  }
}

優先順序： agent-specific > global > default

Exec 安全模式

模式	說明
`sandbox`	在隔離容器執行（預設）
`gateway`	在 host 執行，需要 approval
`full`	完全信任，無限制

{
  "tools": {
    "exec": {
      "host": "sandbox",        // 預設在 sandbox
      "security": "allowlist",  // 只允許白名單指令
      "ask": "on-miss"          // 不在白名單時問 approval
    }
  }
}

Exec Approval 機制

// 當 security=allowlist 且指令不在白名單
async function handleExecApproval(command) {
  // 1. 檢查白名單
  if (isAllowlisted(command)) {
    return execute(command);
  }
  
  // 2. 請求 approval
  const approval = await requestApproval({
    command,
    timeout: 60000  // 60 秒等待
  });
  
  if (approval.denied) {
    throw new Error('Exec denied by user');
  }
  
  // 3. 可選：加入白名單
  if (approval.remember) {
    addToAllowlist(command);
  }
  
  return execute(command);
}

Approval 儲存： ~/.openclaw/exec-approvals.json

SSRF Protection

// 防止 agent 存取內網資源
const BLOCKED_HOSTS = [
  'localhost',
  '127.0.0.1',
  '::1',
  '169.254.*',    // Link-local
  '10.*',         // Private
  '172.16-31.*',  // Private
  '192.168.*'     // Private
];

function validateUrl(url) {
  const host = new URL(url).hostname;
  
  for (const pattern of BLOCKED_HOSTS) {
    if (matches(host, pattern)) {
      throw new Error(`SSRF blocked: ${host}`);
    }
  }
  
  return url;
}

適用於： web_fetch, browser.open, exec with curl

DM Scope 安全

// ⚠️ 不安全（多人共用 context）
{
  "session": {
    "dmScope": "main"
  }
}

// ✅ 安全（每人獨立 context）
{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

設定驗證

# 安全審計
openclaw security audit

# 輸出範例
✅ Tool policy configured
✅ Exec sandbox enabled
⚠️ dmScope is 'main' - consider 'per-channel-peer' for multi-user
✅ SSRF protection active

核心代碼

Tool Policy 檢查

function isToolAllowed(toolName, session) {
  const policy = getToolPolicy(session.agentId);
  
  // 1. 明確禁止
  if (policy.deny.includes(toolName)) {
    return false;
  }
  
  // 2. 明確允許
  if (policy.allow.includes(toolName)) {
    return true;
  }
  
  // 3. 預設行為
  return policy.defaultAllow;
}

Sandbox 執行

async function execInSandbox(command) {
  // 使用 Docker/podman 執行
  const result = await docker.exec({
    image: 'openclaw-sandbox',
    command: ['sh', '-c', command],
    timeout: 1800,
    network: 'none',    // 無網路
    readOnly: true,     // 唯讀檔案系統
    workdir: '/workspace'
  });
  
  return result;
}

💡 關鍵洞察

預設不信任
- Sandbox 預設開啟
- 新工具預設禁用
- 需要明確允許
Allowlist > Denylist
- 明確列出「可以做什麼」
- 而不是「不能做什麼」
- 更安全，更可控
Approval 是最後防線
- 不確定的指令問用戶
- 可以記住選擇
- 適合新指令驗證
SSRF 保護內網
- Agent 不能存取 localhost
- 不能存取私有 IP
- 防止內網探測

安全建議

場景	建議設定
生產環境	`sandbox` + `allowlist`
開發環境	`gateway` + `allowlist`
多人使用	`dmScope: per-channel-peer`
敏感工具	明確 `deny`

🔗 核心檔案

Security 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/security/
Exec Approvals：/opt/homebrew/lib/node_modules/openclaw/docs/tools/exec-approvals.md
Sandbox：/opt/homebrew/lib/node_modules/openclaw/docs/gateway/sandboxing.md

明天： Provider 系統（OpenAI, Anthropic, Google）

Day 14: Security（sandbox, tool policies, SSRF protection）