OpenClaw Tools 深度解析：20+ 工具 × 3 层防护，让你的小龙虾安全地"动手动脚"

// 传统方式（危险）：通过 shell 调用
// 容易被注入攻击
exec(`git commit -m "${message}"`)

// OpenClaw 方式（安全）：类型化工具调用
{
  "tool": "exec",
  "params": {
    "command": "git commit -m {{message}}",
    "security": "allowlist"
  }
}

// 给智能体配置 coding profile
{
  tools: {
    profile: "coding",
    deny: ["gateway", "cron"],  // 禁止网关和定时任务
  }
}

// 1. 检查/启动浏览器
browser → status / start

// 2. 获取页面快照（关键！）
snapshot (ai 或 aria)

// 3. 执行 UI 操作
act (click/type/press)

// 4. 可选：视觉确认
screenshot

// 错误方式（脆弱）
{ "tool": "browser", "action": "click", "x": 100, "y": 200 }

// 正确方式（稳定）
// 1. 先获取快照
{ "tool": "browser", "action": "snapshot", "mode": "ai" }
// 返回：<button ref="12">提交</button>

// 2. 用 ref 点击
{ "tool": "browser", "action": "click", "ref": "12" }

{
  browser: {
    enabled: true,
    defaultProfile: "openclaw",
    profiles: {
      openclaw: { 
        cdpPort: 18800,    // 独立端口
        color: "#FF4500"   // 橙色标识，一眼识别
      },
      work: { 
        cdpPort: 18801,
        color: "#0066CC" 
      },
    },
  }
}

// AI 快照示例
{
  "tool": "browser",
  "action": "snapshot",
  "mode": "ai"
}

// 返回结果（简化版）
/*
[1] <input ref="1" type="text" placeholder="搜索">
[2] <button ref="2">搜索</button>
[3] <div ref="3">热门推荐</div>
...
*/

1. 工具策略（allow/deny）
   ↓
2. 执行目标（sandbox/gateway/node）
   ↓
3. 安全模式（deny/allowlist/full）
   ↓
4. 审批配置（ask: off/on-miss/always）

{
  defaults: {
    security: "allowlist",
    ask: "on-miss",         // 不在白名单时询问
    askFallback: "deny",    // 无法询问时拒绝
  },
  agents: {
    main: {
      allowlist: [
        { pattern: "~/Projects/**/bin/rg" },  // 允许特定目录的 rg
        { pattern: "~/.local/bin/*" },         // 允许 ~/.local/bin 下所有命令
      ],
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: {
        enabled: true,           // 启用沙箱
        image: "node:20",        // 使用 Node 20 镜像
        workdir: "/workspace",   // 工作目录
      },
    },
  },
}

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],              // 全局禁止运行时工具
    byProvider: {
      "google-antigravity": { 
        profile: "minimal"                // 特定模型用最小权限
      },
    },
  },
}

{
  tools: {
    loopDetection: {
      enabled: true,
      warningThreshold: 10,    // 10 次重复时警告
      criticalThreshold: 20,   // 20 次时阻止
    },
  },
}

# 这些环境变量会被拒绝
export PATH=/malicious/path:$PATH
export LD_LIBRARY_PATH=/malicious/lib

# SKILL.md 示例

## 使用 browser 工具的正确方式

1. 先用 snapshot 获取元素引用
2. 用 ref 而不是坐标点击
3. 复杂操作前先截图确认

## 环境变量

- OPENAI_API_KEY: 用于 web_search
- GITHUB_TOKEN: 用于仓库操作

# 安装一个 skill
openclaw skill install github-pr-reviewer

# 查看已安装的 skills
openclaw skill list

// openclaw.plugin.json
{
  name: "my-custom-tools",
  tools: [
    {
      name: "slack_notify",
      description: "发送 Slack 通知",
      params: {
        channel: "string",
        message: "string"
      }
    }
  ]
}

{
  tools: {
    groups: {
      "custom:devops": ["exec", "web_fetch", "message"]
    }
  }
}

// 代码助手配置
{
  tools: {
    profile: "coding",
    deny: ["gateway", "cron", "group:nodes"]  // 禁止网关和设备控制
  }
}

// 推荐：明确允许什么
{
  exec: {
    security: "allowlist",
    allowlist: ["npm", "git", "rg"]
  }
}

// 不推荐：猜测可能危险的命令
{
  exec: {
    security: "full",
    deny: ["rm", "sudo", "chmod"]  // 永远猜不全
  }
}

{
  defaults: {
    ask: "on-miss",  // 不在白名单时询问
  }
}

// 1. 总是先获取快照
await browser.snapshot({ mode: "ai" })

// 2. 用 ref 而非坐标
await browser.click({ ref: "12" })

// 3. 关键操作后截图确认
await browser.screenshot()

{
  "tool": "sessions_spawn",
  "prompt": "帮我分析这个网页的内容，总结要点",
  "context": {
    "url": "https://example.com/article"
  }
}