概念

Tools 是 Agent 的「手腳」— 讓 AI 能實際執行動作，而不只是說話。

OpenClaw 內建的核心工具：

工具	功能
`exec`	執行 shell 命令
`read`	讀取檔案
`write`	寫入檔案
`edit`	編輯檔案
`browser`	控制瀏覽器
`message`	發送訊息到其他 channel
`cron`	管理排程任務

Exec Tool（最常用）

// Agent 呼叫 exec
{
  "tool": "exec",
  "command": "git status",
  "workdir": "/Users/me/project",
  "timeout": 30
}

// 背景執行 + 輪詢
{
  "tool": "exec",
  "command": "npm run build",
  "yieldMs": 1000,      // 1秒後背景化
  "background": false
}

// 然後用 process tool 追蹤
{
  "tool": "process",
  "action": "poll",
  "sessionId": "<session-id>"
}

核心代碼

1. Tool 執行流程

async function executeTool(toolName, args) {
  // 1. 檢查權限
  if (!isToolAllowed(toolName, session.toolPolicy)) {
    throw new Error(`Tool ${toolName} is not allowed`);
  }
  
  // 2. 找到 tool handler
  const handler = tools[toolName];
  if (!handler) {
    throw new Error(`Unknown tool: ${toolName}`);
  }
  
  // 3. 執行並串流結果
  const result = await handler.execute(args, {
    workspace: session.workspace,
    timeout: args.timeout || 1800
  });
  
  // 4. 清理結果（截斷太長的輸出）
  return sanitizeResult(result, { maxLength: 50000 });
}

2. Tool Policy（權限控制）

// openclaw.json
{
  "tools": {
    "allow": ["exec", "read", "write", "edit", "browser"],
    "deny": ["message"],  // 禁止發訊息
    
    "exec": {
      "host": "sandbox",        // 在 sandbox 執行
      "security": "allowlist",  // 只允許白名單指令
      "timeout": 1800           // 30 分鐘超時
    }
  }
}

三種 exec 模式：

sandbox：在隔離容器執行（最安全）
gateway：在 host 執行，需要 approval
node：在遠端節點執行

3. Browser Tool

// 開啟網頁
{
  "tool": "browser",
  "action": "open",
  "url": "https://example.com"
}

// 截圖
{
  "tool": "browser",
  "action": "screenshot",
  "targetId": "<tab-id>"
}

// 點擊元素
{
  "tool": "browser",
  "action": "act",
  "request": {
    "kind": "click",
    "ref": "button[type=submit]"
  }
}

// 取得頁面結構（給 AI 看）
{
  "tool": "browser",
  "action": "snapshot"
}

4. Message Tool

// 發送訊息到其他 channel
{
  "tool": "message",
  "action": "send",
  "channel": "telegram",
  "target": "9876543210",
  "message": "Hello from OpenClaw!"
}

// 發送到 WhatsApp
{
  "tool": "message",
  "action": "send",
  "channel": "whatsapp",
  "target": "+1234567890",
  "message": "任務完成！"
}

Tool Result 處理

// 工具結果會被清理後回給 LLM
function sanitizeResult(result, options) {
  // 1. 截斷太長的輸出
  if (result.length > options.maxLength) {
    result = result.slice(0, options.maxLength) + '\n... (truncated)';
  }
  
  // 2. 圖片轉成 base64 或 URL
  if (result.type === 'image') {
    return { type: 'image', data: toBase64(result.data) };
  }
  
  return result;
}

💡 關鍵洞察

Tools 是 Agent 的能力邊界
- 沒有 exec，agent 不能跑命令
- 沒有 browser，agent 不能看網頁
- Tool policy 控制「agent 能做什麼」
Exec 是最強大也最危險的
- 可以跑任何 shell 命令
- 所以有 sandbox/allowlist 機制
- 生產環境務必設定 approval
Browser Tool 是「眼睛」
- Snapshot 讓 AI 理解頁面結構
- 不需要看圖，用 accessibility tree
- 比截圖更有效率
Message Tool 是「嘴巴」
- 讓 agent 主動發訊息
- 跨 channel 通知
- Cron + Message = 自動報告

🔗 核心檔案

Exec 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/tools/exec.md
Browser 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/tools/browser.md
Tool 列表：/opt/homebrew/lib/node_modules/openclaw/docs/tools/

明天： Plugin 架構（Telegram/WhatsApp 如何整合）

Day 4: Tool 系統（exec, browser, message 等）