OpenClaw函数参数：龙虾智能体位置参数与关键字参数配置实战

1. OpenClaw 函数参数到底在解决什么问题如果你正在用 OpenClaw 写龙虾智能体的工具函数大概率会遇到一个很具体的困惑函数定义好了模型也识别到了但调用时要么参数对不上号要么必填项被漏掉要么模型把参数塞进了错误的位置。这类问题的根源基本都落在函数参数的声明方式上。OpenClaw 里的函数参数分为两大类位置参数和关键字参数。位置参数靠顺序匹配关键字参数靠名字匹配。听起来像 Python 基础但在智能体场景下它们直接决定了模型能不能正确理解你的工具签名以及调用时会不会报参数缺失或类型错误。我见过不少开发者把工具函数写成def search(query, limit10, offset0)结果模型调用时传了{limit: 5, query: 天气}顺序一乱就出问题。这篇内容面向需要为 OpenClaw 龙虾智能体定义工具函数入参的开发者交付一套可以直接复制的参数配置骨架包含位置参数与关键字参数的完整示例、调用验证动作以及参数传递过程中最常见的报错排查路径。你不需要先读完整个 OpenClaw 文档跟着下面的步骤就能把参数定义和调用测试跑通。核心检索词先明确OpenClaw 函数参数、位置参数、关键字参数这三者是本篇的主线。适合谁适合已经能创建基础智能体、准备给智能体挂载自定义工具函数的开发者。如果你还没拿到 API Key第 2 节会先把这个前置动作补齐。2. TaoToken 前置拿到 API Key 与接入地址OpenClaw 的智能体在调用模型能力时需要一个可用的 API 入口。这里我用 TaoToken 作为接入层它的 API 地址是https://taotoken.net/api控制台和密钥管理在官网完成。整个前置动作只有两步注册账号、创建 API Key。注册入口走官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册完成后进入控制台。控制台地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在控制台左侧找到 API Keys 菜单点击创建新密钥。密钥只显示一次复制后存到环境变量里不要硬编码进代码。创建密钥的直达链接是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。拿到密钥后在终端里设置环境变量export TAOTOKEN_API_KEYsk-你的密钥Windows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的密钥这一步做完OpenClaw 的模型调用通道就通了。接下来定义函数参数时模型才能正常解析你的工具签名。如果你只是想先验证模型对话是否正常可以走模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条测试消息确认密钥有效再继续。注意API Key 属于敏感凭证不要提交到 Git 仓库也不要在日志里打印完整密钥。建议用.env文件配合python-dotenv加载。3. 可复制的函数参数配置骨架这一节是全文的核心。我会先给出位置参数的定义方式再给出关键字参数的定义方式最后给出两者混用的推荐写法。所有代码都可以直接复制到你的 OpenClaw 项目里。3.1 位置参数的定义与调用位置参数在 OpenClaw 工具函数里按声明顺序匹配。定义时直接写参数名调用时按顺序传值。下面是一个查询天气的工具函数import openclaw from openclaw.tools import tool tool def get_weather(city: str, unit: str celsius) - dict: 查询指定城市的天气。 Args: city: 城市名称必填 unit: 温度单位可选 celsius 或 fahrenheit # 实际调用外部天气接口 return { city: city, unit: unit, temperature: 26, condition: 晴 } agent openclaw.Agent( name天气助手, api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api ) agent.register_tool(get_weather)这里city是位置参数unit带默认值。模型调用时会生成类似{city: 杭州, unit: celsius}的参数对象。位置参数的关键在于声明顺序即匹配顺序模型必须按顺序提供值否则会触发参数缺失。调用测试result agent.run(get_weather, city杭州) print(result)输出应该是包含城市、温度、天气状况的字典。如果模型返回TypeError: get_weather() missing 1 required positional argument: city说明参数名没对上检查工具注册时的签名解析。3.2 关键字参数的定义与调用关键字参数通过参数名匹配顺序无关。在 OpenClaw 里用*分隔符可以把后面的参数强制为关键字参数tool def search_products(*, keyword: str, category: str all, limit: int 10) - list: 按关键词搜索商品。 Args: keyword: 搜索关键词必填 category: 商品分类默认 all limit: 返回数量默认 10 return [ {id: i, name: f{keyword}-商品{i}, category: category} for i in range(1, limit 1) ]*后面的keyword、category、limit都只能通过关键字传递。模型调用时必须写成{keyword: 耳机, limit: 5}不能写成{耳机, 5}。这种写法在智能体场景下更安全因为模型生成的参数是 JSON 对象天然就是关键字形式。调用测试result agent.run(search_products, keyword耳机, limit3) print(result)预期输出是 3 条商品记录。如果模型传了{keyword: 耳机, limit: 3}注意limit是字符串需要在函数内部做类型转换或者用 Pydantic 做参数校验。3.3 位置参数与关键字参数混用的推荐写法实际项目里我建议把必填参数放前面作为位置参数可选参数放后面作为关键字参数中间用*隔开tool def create_order(order_id: str, *, user_id: str, quantity: int 1, remark: str ) - dict: 创建订单。 Args: order_id: 订单编号必填位置参数 user_id: 用户 ID必填关键字参数 quantity: 数量默认 1 remark: 备注默认空 return { order_id: order_id, user_id: user_id, quantity: quantity, remark: remark, status: created }这种写法的好处是order_id作为位置参数保证必填user_id作为关键字参数强制模型显式传名避免顺序错乱。参数对照表如下参数名类型是否必填传递方式默认值order_idstr是位置无user_idstr是关键字无quantityint否关键字1remarkstr否关键字提示OpenClaw 在解析工具签名时会读取类型注解和默认值。类型注解越完整模型生成的参数越准确。建议所有参数都写类型注解。4. 验证请求与成功结果参数定义完成后必须做一次完整的调用验证。验证分三步检查工具注册、发起调用、核对返回。第一步检查工具是否注册成功print(agent.list_tools())输出应该包含get_weather、search_products、create_order三个工具名。如果某个工具没出现检查tool装饰器是否生效以及register_tool是否调用。第二步发起一次带参数的调用response agent.run( create_order, order_idORD-20240101-001, user_idU-10086, quantity2, remark加急 ) print(response)第三步核对返回结构。成功结果应该类似{ order_id: ORD-20240101-001, user_id: U-10086, quantity: 2, remark: 加急, status: created }如果返回里quantity是字符串2而不是整数2说明模型生成的参数类型不对需要在函数签名里加 Pydantic 模型做强制校验from pydantic import BaseModel, Field class OrderParams(BaseModel): order_id: str Field(..., description订单编号) user_id: str Field(..., description用户 ID) quantity: int Field(1, ge1, description数量) remark: str Field(, description备注) tool def create_order(params: OrderParams) - dict: return params.model_dump()用 Pydantic 之后参数校验在进入函数体之前就完成了类型错误会直接抛出清晰的报错信息而不是在函数内部静默失败。5. 本篇常见错误排查参数配置过程中报错集中在四类。下面按报错信息逐一排查。5.1 TypeError: missing required positional argument完整报错TypeError: get_weather() missing 1 required positional argument: city原因模型调用时没有提供city参数或者参数名拼写不一致。检查工具函数的参数名和模型生成的 JSON key 是否完全一致。OpenClaw 对参数名大小写敏感City和city会被视为两个不同的参数。解决在函数签名里给必填参数加Field(..., description...)让模型明确知道这个参数必填。同时检查tool装饰器是否保留了原始签名。5.2 TypeError: got an unexpected keyword argument完整报错TypeError: search_products() got an unexpected keyword argument key_word原因模型生成的参数名和函数定义不一致比如把keyword写成了key_word。这种情况在模型对工具描述理解不充分时容易出现。解决在工具函数的 docstring 里把参数名写清楚并在tool装饰器里显式声明参数 schematool( namesearch_products, parameters{ keyword: {type: string, description: 搜索关键词}, limit: {type: integer, description: 返回数量} } ) def search_products(*, keyword: str, limit: int 10) - list: ...5.3 参数类型不匹配报错ValidationError: value is not a valid integer原因模型把数字参数生成为字符串比如{limit: 5}。JSON 里字符串和数字是不同类型Pydantic 校验会拦截。解决用 Pydantic 模型做参数校验或者在函数内部做显式转换def search_products(*, keyword: str, limit: int 10) - list: limit int(limit) ...5.4 工具未被模型识别现象调用时提示Tool xxx not found。原因工具注册顺序问题或者tool装饰器在register_tool之后才应用。确保装饰器在函数定义时立即生效注册时传入的是装饰后的函数对象。排查清单报错关键词可能原因检查动作missing required必填参数未传核对参数名与 JSON keyunexpected keyword参数名拼写不一致检查 docstring 与 schemaValidationError类型不匹配加 Pydantic 校验Tool not found注册失败检查装饰器与注册顺序如果排查过程中需要确认模型本身是否正常可以走模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条简单消息排除密钥或网络问题。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有完整的参数 schema 说明。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔写几个工具函数上面的配置骨架够用了。但如果你在做一个长期迭代的龙虾智能体项目工具函数会越来越多参数管理会变成一件需要系统化处理的事。这时候建议把参数定义抽成独立的 schema 文件用 Pydantic 统一管理工具函数只负责业务逻辑。对于需要持续编码、频繁调试 Agent 的场景Coding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite提供了更适合长期开发的接入方式。它的优势在于参数配置和模型调用可以分开管理工具函数的签名变更不会影响模型通道的稳定性。ClaudeCode 相关的接入配置在https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite如果你用 ClaudeCode 作为编码环境可以参考这个入口的配置说明。API 基础地址始终是https://taotoken.net/api所有工具函数的模型调用都走这个地址。最后给一个实用技巧在 OpenClaw 项目里建一个tools/目录每个工具函数一个文件参数 schema 用 Pydantic 模型定义在文件顶部。这样模型解析签名时读取的是结构化 schema比纯 docstring 解析准确得多。我试过把 20 多个工具函数按这个方式组织参数报错率明显下降。