OpenClaw之所以能够轻松顺利地完成一些复杂任务，除了有合理且优秀的提示词外，还有另外一大功臣：丰富的工具箱。

一、工具总数

OpenClaw 共有 40+ 个工具，分为以下几个类别：

类别 数量 说明
核心工具 5 个 read, write, edit, exec, process
会话管理 7 个 sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, session_status, subagents
网络工具 4 个 web_search, web_fetch, browser, tavily
OpenClaw 核心 14 个 gateway, agents_list, cron, nodes, canvas, tts, message 等
媒体工具 3 个 image, image_generate, pdf
沙盒工具 3 个 sandboxed_read, sandboxed_write, sandboxed_edit
其他 5 个 apply_patch, host_workspace_edit, host_workspace_write,memory_search,memory_get

二、工具定义位置

外部依赖

import { codingTools, createReadTool, createWriteTool, createEditTool } 
from "@mariozechner/pi-coding-agent";

说明：基础工具（read, write, edit）来自外部库 @mariozechner/pi-coding-agent

三、工具定义结构

通用模式

function createXxxTool(options) {
    return {
        name: "xxx",           // 工具名称
        description: "...",    // 工具描述
        parameters: {          // 参数定义（JSON Schema）
            type: "object",
            properties: {...},
            required: [...]
        },
        execute: async (toolCallId, params, signal, onUpdate) => {
            // 执行逻辑
            return result;
        }
    };
}

示例：createExecTool

function createExecTool(defaults) {
    return {
        name: "exec",
        description: "Run shell commands (pty available for TTY-required CLIs)",
        parameters: {
            type: "object",
            properties: {
                command: { type: "string", description: "Command to execute" },
                background: { type: "boolean", description: "Run in background" },
                yieldMs: { type: "number", description: "Milliseconds to wait before backgrounding" },
                // ...
            },
            required: ["command"]
        },
        execute: async (toolCallId, params, signal, onUpdate) => {
            // 执行 shell 命令
            // 处理后台任务
            // 返回结果
        }
    };
}

四、完整工具列表

核心工具（5 个）

工具名 函数 说明
read createReadTool 读取文件内容
write createWriteTool 创建或覆盖文件
edit createEditTool 精确编辑文件
exec createExecTool 执行 shell 命令
process createProcessTool 管理后台进程

会话管理工具（7 个）

工具名 函数 说明
sessions_list createSessionsListTool 列出其他会话
sessions_history createSessionsHistoryTool 获取会话历史
sessions_send createSessionsSendTool 发送消息到其他会话
sessions_spawn createSessionsSpawnTool 创建子代理会话
sessions_yield createSessionsYieldTool 结束当前回合
session_status createSessionStatusTool 显示会话状态
subagents createSubagentsTool 管理子代理

OpenClaw 核心工具（14 个）

工具名 函数 说明
browser createBrowserTool 控制浏览器
canvas createCanvasTool Canvas 操作
nodes createNodesTool 节点管理
cron createCronTool 定时任务管理
message createMessageTool 发送消息
tts createTtsTool 语音合成
gateway createGatewayTool Gateway 管理
agents_list createAgentsListTool 列出可用代理
image createImageTool 图像分析
image_generate createImageGenerateTool 图像生成
pdf createPdfTool PDF 处理
web_search createWebSearchTool 网络搜索
web_fetch createWebFetchTool 网页抓取
apply_patch createApplyPatchTool 应用代码补丁

沙盒工具（3 个）

工具名 函数 说明
sandboxed_read createSandboxedReadTool 沙盒中读取文件
sandboxed_write createSandboxedWriteTool 沙盒中写入文件
sandboxed_edit createSandboxedEditTool 沙盒中编辑文件

五、工具创建流程

createOpenClawCodingTools 流程

function createOpenClawCodingTools(options) {
    // 1. 解析配置
    const sandbox = options?.sandbox;
    const policy = resolveEffectiveToolPolicy(options);
    
    // 2. 创建基础工具（read, write, edit）
    const base = codingTools.flatMap((tool) => {
        if (tool.name === 'read') {
            return [createOpenClawReadTool(createReadTool(workspaceRoot))];
        }
        // ...
    });
    
    // 3. 创建 exec 和 process 工具
    const execTool = createExecTool({...defaults, cwd: workspaceRoot});
    const processTool = createProcessTool({scopeKey});
    
    // 4. 创建 OpenClaw 核心工具
    const openClawTools = createOpenClawTools({
        agentSessionKey: options?.sessionKey,
        workspaceDir: workspaceRoot,
        // ...
    });
    
    // 5. 合并所有工具
    const tools = [
        ...base,
        execTool,
        processTool,
        ...openClawTools
    ];
    
    // 6. 应用策略管道
    const withHooks = applyToolPolicyPipeline({
        tools: tools,
        policy: policy,
        // ...
    });
    
    return withHooks;
}

createOpenClawTools 流程

function createOpenClawTools(options) {
    // 1. 创建媒体工具
    const imageTool = createImageTool({...});
    const imageGenerateTool = createImageGenerateTool({...});
    const pdfTool = createPdfTool({...});
    
    // 2. 创建网络工具
    const webSearchTool = createWebSearchTool({...});
    const webFetchTool = createWebFetchTool({...});
    
    // 3. 创建消息工具
    const messageTool = createMessageTool({...});
    
    // 4. 创建核心工具数组
    const tools = [
        createBrowserTool({...}),
        createCanvasTool({...}),
        createNodesTool({...}),
        createCronTool({...}),
        ...messageTool ? [messageTool] : [],
        createTtsTool({...}),
        ...imageGenerateTool ? [imageGenerateTool] : [],
        createGatewayTool({...}),
        createAgentsListTool({...}),
        createSessionsListTool({...}),
        createSessionsHistoryTool({...}),
        createSessionsSendTool({...}),
        createSessionsYieldTool({...}),
        createSessionsSpawnTool({...}),
        createSubagentsTool({...}),
        createSessionStatusTool({...}),
        ...webSearchTool ? [webSearchTool] : [],
        ...webFetchTool ? [webFetchTool] : [],
        ...imageTool ? [imageTool] : [],
        ...pdfTool ? [pdfTool] : []
    ];
    
    // 5. 添加插件工具
    const pluginTools = resolvePluginTools({...});
    
    return [...tools, ...pluginTools];
}

六、工具策略管道

applyToolPolicyPipeline

工具在返回前会经过策略管道处理：

const withHooks = applyToolPolicyPipeline({
    tools: tools,                          // 原始工具列表
    toolMeta: (tool) => getPluginToolMeta(tool),
    warn: logWarn,
    steps: [
        {
            policy: profilePolicy,
            label: "profile tools.allow"
        },
        {
            policy: globalPolicy,
            label: "global tools.allow"
        },
        {
            policy: sandboxToolPolicy,
            label: "sandbox tools.allow"
        },
        // ...
    ]
});

策略类型

策略 说明
profilePolicy 用户配置策略
globalPolicy 全局策略
agentPolicy 代理策略
groupPolicy 群组策略
sandboxToolPolicy 沙盒策略
subagentPolicy 子代理策略

七、工具执行流程

1. before_tool_call Hook

工具执行前会经过 before_tool_call Hook：

async function runBeforeToolCallHook(args) {
    // 1. 检测工具调用循环
    const loopResult = detectToolCallLoop(sessionState, toolName, params);
    if (loopResult.stuck) {
        return { blocked: true, reason: "Loop detected" };
    }
    
    // 2. 运行全局 Hook
    const hookResult = await hookRunner.runBeforeToolCall({...});
    if (hookResult?.block) {
        return { blocked: true, reason: hookResult.blockReason };
    }
    
    return { blocked: false, params };
}

2. 工具执行

const execute = async (toolCallId, params, signal, onUpdate) => {
    // 1. 运行 before_tool_call Hook
    const outcome = await runBeforeToolCallHook({toolName, params, toolCallId, ctx});
    if (outcome.blocked) throw new Error(outcome.reason);
    
    // 2. 执行工具
    const result = await execute(toolCallId, outcome.params, signal, onUpdate);
    
    // 3. 记录结果
    await recordLoopOutcome({...});
    
    return result;
};

八、工具命名规范

命名模式

模式 示例 说明
createXxxTool createExecTool 工具创建函数
xxx exec 工具名称（小写）
XxxTool ExecTool 工具类名（大写）

工具名称规则

  1. 小写：exec, read, write
  2. 下划线分隔：web_search, apply_patch
  3. 简洁明了：反映工具功能

九、工具参数定义

JSON Schema 格式

parameters: {
    type: "object",
    properties: {
        command: {
            type: "string",
            description: "Command to execute"
        },
        background: {
            type: "boolean",
            description: "Run in background",
            default: false
        },
        timeout: {
            type: "number",
            description: "Timeout in seconds"
        }
    },
    required: ["command"]
}

十、总结

工具架构特点

  1. 模块化：每个工具独立定义
  2. 可组合：通过 createOpenClawCodingTools 组合
  3. 可扩展：支持插件工具
  4. 有策略：通过策略管道控制工具访问
  5. 有监控：before_tool_call Hook 检测循环

工具数量统计

类别 数量
核心工具 5
会话管理 7
OpenClaw 核心 14
沙盒工具 3
媒体工具 3
网络工具 4
其他 5
总计 40+
# 数据库 # 人工智能 # 机器学习 # 开源软件 # python
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

【电脑自动化助手】 OpenClaw 一键部署教程（包含安装包）

avatar 龙虾开发者社区
cover

OpenClaw 上下文瘦身：3 个实验

avatar 龙虾开发者社区
cover

OpenClaw 网关密钥轮换实战：如何安全实现多模型厂商路由与熔断

avatar 龙虾开发者社区