必须实现带类型注解和规范文档字符串的python函数，并通过register_tool在模块顶层显式注册，否则工具不可见且调用报toolnotfound错误；注册须在agent加载前完成，验证可通过api、ui或repl检查。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在OpenClaw中新增一个可被工作流调用的自定义工具，必须实现符合其运行时契约的Python函数，并通过register_tool显式注册，否则工具不会出现在工具列表中且调用时会报ToolNotFound错误。
定义工具函数并满足签名约束
第一步：编写函数，函数名任意，但参数必须全部标注类型注解，且仅接受位置或关键字参数（不支持*args或**kwargs）；返回值也需标注类型，推荐使用str或dict等JSON可序列化类型。
第二步：在函数文档字符串中用@desc开头写明工具用途，用@param逐行说明每个参数含义——OpenClaw解析器依赖此格式提取元数据，缺失或格式错误将导致工具在UI中无描述、参数不可配。
这一步操作起来很简单，直接把文件拖进去就行。但若漏掉@desc，工具虽能注册成功，却会在前端显示为空白卡片，无法被用户识别。
使用register_tool完成注册
调用from openclaw import register_tool→在模块顶层（非函数内、非类内）执行register_tool(your_function_name)。
【必须在Python解释器启动后、Agent首次加载前完成注册】。常见错误是把register_tool放在某个API路由函数里，导致每次HTTP请求才注册一次——此时工作流初始化时该工具尚未存在，直接抛异常。
注册语句不能写在if __name__ == '__main__':块内，否则以模块方式导入时不会执行。
验证工具是否生效
方法一：启动OpenClaw服务后，访问/api/v1/tools接口，检查返回JSON中是否存在你注册的工具名及对应description字段。
方法二：在Web UI的工作流编辑页，点击「添加工具节点」，搜索你的函数名——若出现且参数表单自动渲染出带提示的输入框，说明注册与元数据解析均成功。
方法三：在Python REPL中执行from openclaw.runtime import get_all_tools→get_all_tools()，确认返回字典包含你的函数对象键。
