“龙虾智能体”这个词我第一次听的时候也愣了一下。明明是写代码怎么突然跑到海鲜市场去了后来在 OpenClaw 的社区里泡了一阵子才明白这个开源智能体框架的吉祥物就是一只举着大钳子的龙虾社区也就习惯把基于它写出来的智能体程序叫做龙虾智能体。名字是有点俏皮但框架本身一点不花哨。我最近拿它带着几个刚入门智能体开发的朋友做练习发现这个框架对新手非常友好依赖少、逻辑直、调试路径短比动不动就上多智能体编排的大型框架合适得多。这篇文章就带你跑通第一个 Hello World 版的 OpenClaw 龙虾智能体程序。我不讲虚的直接给可复制的代码把环境怎么搭、代码怎么拆、运行背后发生了什么全给你讲清楚。你不需要事先懂大模型原理只要会一点 Python 基础跟着抄就能跑起来。跑通了以后你再看更复杂的智能体项目思路会清晰很多。1. OpenClaw 到底是个什么一只龙虾的自我修养先把这个框架的定位说清楚。OpenClaw 是一个面向智能体应用开发的开源框架它把大语言模型推理、工具调用、任务流程编排这几个能力封装成了一个最小可用的运行环境。你可以把它理解为一套脚手架模型是龙虾的大脑工具是龙虾的钳子而 OpenClaw 本身是连接这两者的神经系统。它解决的问题很实际。裸用模型聊天你只能一问一答模型没法访问外部数据也没法操作任何真实功能。传统编程方式自己写一个循环来处理模型返回的“工具调用意图”又很麻烦。OpenClaw 把中间这一层逻辑标准化了你只需要定义好智能体的角色、配置好模型入口、挂上几个工具函数一个能自主决策、调用工具、迭代解决问题的智能体就成型了。这个框架适合谁来用我理解有三类人。第一类是刚接触智能体开发的新手想找一个简单案例快速建立全局认知第二类是在产品原型阶段需要快速验证“智能体工具”方案的开发者第三类是教学场景里带学生入门 AI 应用开发的老师。如果你属于这三类OpenClaw 的路子就特别对味。1.1 为什么是 OpenClaw 而不是其他框架我前前后后试过不少智能体框架有的强调图形化编排有的主打多智能体协作功能听起来很猛但新手一旦开始实际写代码就很容易陷进去一大堆概念堆在面前还没跑通 Hello World 就先被“对话记忆”“任务分解”这些名词淹没了。OpenClaw 的开箱体验明显不同。它的最小工作流只有四步接收用户输入组装上下文交给模型推理然后根据推理结果执行工具或返回回复。你不需要理解复杂的图结构也不需要提前规划智能体之间的通信协议。这种简化不是功能上的妥协而是把“智能体”这个概念还原到了它最本质的形态一个能调用工具的循环决策器。另外它的依赖管理非常克制。安装包体积小不强制你装一堆可视化组件和中间件对国内开发环境下常见的网络限制也做了兼容具体安装方式见下一节。这几年智能体框架更新得很快但 OpenClaw 的核心接口一直很稳定这也是我敢把它推荐给新手的原因之一。1.2 龙虾智能体的三层结构如果你把 OpenClaw 跑起来之后观察它的行为会很容易总结出一个三层结构感知层负责接收外部输入把用户的自然语言指令、系统提示词、历史对话记录拼装成一个标准化的上下文对象。这个环节决定了智能体“能看到什么”。思考层是模型的推理过程。模型基于当前的上下文输出两种可能性之一要么直接返回一条自然语言回复要么生成一个调用工具的指令。OpenClaw 会解析这个指令提取工具名和参数。行动层在框架内部完成根据解析出来的工具名去执行对应函数然后把执行结果返回到模型中让模型决定下一步怎么做。这个循环会一直持续直到智能体认为任务完成。你可以用龙虾来类比这套结构触角是感知层神经节是思考层钳子是行动层。一只龙虾如果只有大脑没有钳子那它就是个聊天盒子只有钳子没有大脑那它就是个被动的函数库。OpenClaw 的价值就是帮我们把三层有机地串起来。2. 环境准备与 Hello World 最小代码现在进入正题。这部分我尽量压缩概念先给你一套能跑的代码跑起来之后再逐渐解释细节。2.1 环境要求与安装OpenClaw 要求 Python 3.9 或以上版本。我建议你装 3.10 或 3.11这两个版本对现代类型注解和异步生态的支持更成熟。用 Debian/Ubuntu 的话 Python 版本通常会比较老可以用python3 --version确认一下。创建虚拟环境是必须养成的习惯不然过几个月你项目多了依赖冲突会逼疯你。在项目目录下执行:mkdir openclaw-hello cd openclaw-hello python3 -m venv venv source venv/bin/activateWindows 环境下激活命令是venv\Scripts\activate。虚拟环境激活后命令行开头会出现(venv)看到这个就对了。然后安装框架本体pip install openclaw如果下载速度慢或者超时可以临时切到国内镜像源pip install openclaw -i https://mirrors.cloud.tencent.com/pypi/simple安装完成后验证一下python -c from openclaw import Agent; print(ok)能打印出 ok说明基础环境没问题。2.2 最小 Hello World 代码下面这份代码是我实测过的精简版把它存成一个文件命名为hello_lobster.py。# hello_lobster.py from openclaw import Agent agent Agent( name小钳, system_prompt( 你是一只名叫小钳的龙虾智能体。 不管用户说什么你都要先热情地说你好呀 然后在回复末尾加上——钳子挥舞.gif。 保持简短不要超过两句话。 ), modelyour_model_provider, api_keyyour_api_key, ) if __name__ __main__: result agent.run(今天天气怎么样) print(result)这份代码直接把Agent对象从框架里导入创建时传入了四个关键参数name是智能体的名字会在日志里出现system_prompt是系统提示词定义了这只龙虾的性格和行为边界model和api_key是模型服务的接入信息。model参数怎么填这个等你看到下一小节就明白了。如果你用的是云端的模型服务就填服务商提供的模型标识字符串如果是本地私有化部署的模型通常填本地服务暴露出来的模型名。关键在于这个参数对应的服务必须兼容标准的对话接口格式OpenClaw 才能正常对接。2.3 第一次运行你会看到什么把代码中的model和api_key换成你能用的模型服务信息然后执行python hello_lobster.py正常的话你会看到终端输出一段文本大致长这样你好呀天气的问题我可不太擅长但我建议你看看窗外——毕竟我这钳子举起来也挡不住雨呀。 ——钳子挥舞.gif输出的内容取决于你配置的模型和提示词但这次跑通的意义远远超过这一句话本身。它证明了完整的链路是通的代码 → OpenClaw 框架 → 模型服务 → 生成回复 → 回到程序输出。这一条链路打通之后后面所有复杂功能都是在这条链路上做扩展。如果你用的是带图形界面的编辑器我建议你顺便跑一下交互式模式。把代码改成agent.chat()程序就会进入一个命令行对话循环可以连续输入多轮消息。这个模式对调试特别方便改提示词、调参数的时候不用反复执行脚本。3. 运行机制拆解龙虾是怎么“钳”住请求的代码跑通了接下来有必要把背后的机制弄清楚。这一节可能会打破一些新手对大模型的浪漫想象智能体其实并不是“真的理解”一句话它是一套工程上的循环决策系统。3.1 一个请求从进入到返回的完整路径当你调用agent.run(今天天气怎么样)时OpenClaw 内部发生了一系列标准动作。第一步框架构造上下文对象。它把系统提示词、用户输入、当前时间等元信息组装成一套模型容易理解的文本模板。系统提示词会被放在最前面相当于给模型划定人格和边界。第二步框架调用模型接口把上下文发送给模型服务等待返回。这一步在网络上有延迟通常几百毫秒到几秒不等取决于模型服务的负载。第三步是判断。模型返回的结果有两种可能一种是一段普通文本这种情况下 OpenClaw 直接把文本作为最终答案返回另一种是一段结构化的工具调用指令OpenClaw 会解析这段指令提取出工具名和参数。第四步如果上一步提取了工具调用意图框架就去注册表里找到对应的工具函数并执行。执行结果会被重新塞回对话上下文再提交给模型让模型基于工具结果生成最终回复。这个过程像一条循环管道。新手最容易误解的地方在于很多人觉得智能体应该像一个巨大的程序输入问句直接输出答案其实真实情况是一个可以多次迭代的循环。3.2 为什么智能体“知道”该用什么工具这个问题的答案不在模型本身而在工具的描述信息。你在用 OpenClaw 定义工具时不仅要写 Python 函数还要提供一个描述文本。这个描述文本连同函数签名会被转换成模型能读懂的 schema在每一轮对话时提交给模型。模型通过阅读这些描述从你注册的工具列表里挑选一个最符合当前用户意图的选项。它并不真的“理解”工具背后的代码而是做了个决策哪个工具的说明和参数和用户的问题最匹配。比如你有一个计算字符串长度的工具描述写着“输入文本返回文本字数”模型收到“帮我统计这句话有多少个字”时就会大概率选择这个工具并生成正确的参数。如果你的描述写得含糊模型就会犹豫甚至选错工具。这就是为什么下一节里我反复强调工具描述要具体。3.3 模型配置的三种姿势我认识不少朋友在这一步卡住把代码复制了过去却不知道model和api_key填什么。这里给你梳理三种常见配置方式。第一种是云端托管服务的兼容接口。这种方式最省事你只需要注册一个账号拿一串 API Key填上服务商提供的模型标识即可。有的服务商要求填 Base URLOpenClaw 也提供了对应的配置项。第二种是本地私有化部署的模型服务。你本地起一个兼容标准接口的服务监听某个端口然后把model填成服务暴露的模型名称api_key可以填一个占位符。这种方式的好处是数据不出网、没有按量计费适合学习阶段反复测试。第三种是环境变量方式。把敏感信息放在代码里既不安全也不利于协作万一你有一天把代码分享出去API Key 就泄露了。推荐的做法是放在环境变量里import os api_key os.environ.get(OPENCLAW_API_KEY, ) model os.environ.get(OPENCLAW_MODEL, )然后在运行前导出变量。这样代码是干净的密钥留在本地环境分享代码时不怕泄露。4. 给 Hello World 加点料让龙虾学会使用工具光会打招呼的机器人没什么实际价值。智能体的核心能力在于“行动”也就是调用工具去改变一些什么。这一节我带你把上一节的代码升级成一个带工具的版本。4.1 定义第一个工具函数在 OpenClaw 里定义一个工具非常简单。你只需要用装饰器标出一个普通 Python 函数并配上名称和描述信息。# tools/text_tool.py from openclaw import Tool Tool( nameget_word_count, description统计一段中文文本的字数返回整数结果。当用户询问文本有多少个字、多长、多少字符时使用。 ) def get_word_count(text: str) - int: Return the character count. return len(text)这里我特意把 description 写得很啰嗦——不是废话而是给模型提供了足够的情境线索。模型在做工具选择的时候不是看你的函数内部实现而是看名字和描述。描述里多写几个典型的触发场景命中率会直线上升。函数签名也要谨慎。参数名text清晰类型标注str明确返回类型int也准确。OpenClaw 会把类型信息转成模型能识别的参数结构如果类型不对模型生成的参数类型可能没法匹配。4.2 注册工具并跑一个完整任务有了工具函数接下来要把它挂到智能体上。修改我们的主程序# hello_lobster_with_tool.py from openclaw import Agent from tools.text_tool import get_word_count agent Agent( name小钳, system_prompt你是一只名叫小钳的龙虾智能体会使用工具来回答用户的统计类问题。回答要简洁。, modelyour_model_provider, api_keyyour_api_key, tools[get_word_count], ) if __name__ __main__: result agent.run(帮我统计一下这句话有多少个字今天的龙虾真的是太新鲜了) print(result)注意tools参数接收的是一个列表把工具对象传进去就行。能挂多个工具框架会自动组织。运行这段代码你会看到类似这样的输出“今天的龙虾真的是太新鲜了”这句话一共有12个字。从代码逻辑上看你好像只是多传了一个列表但在框架内部发生了一次完整的工具调用循环模型判断用户意图需要统计字数生成工具调用指令框架执行函数拿到结果后再次调用模型生成最终回答。4.3 工具描述写不好会怎样这是我在实际踩坑中记忆最深的一个点。第一次写工具描述的时候我图省事写了一句“计算文本长度”结果模型遇到任何和文本相关的请求都倾向于调用这个工具。用户问“这句话用英文怎么说”它也会去调用字数统计答非所问。后来我总结出了几条经验。描述要写触发条件说明什么场景下用、什么场景下不用。描述要给参数示例比如“text 是要统计的原始字符串不能为空”。描述不要太短但也别写成小作文。模型对描述过长也会失去注意力。函数内部不需要太智能。工具函数尽量做到单一功能判断题“是否应该调用某个工具”是模型的事不要替它做决定。还有一个细节是参数默认值。如果某个参数可以缺省就给它设默认值这能降低模型生成参数的难度。如果参数是必填的描述里最好说明“用户未提供时获取失败要如何兜底”。5. 经常踩的坑与排查速查最后分享一些我带着别人跑这个项目时最常见的报错和排查思路。这些东西官方文档不会写得特别细但对新手来说非常救命。5.1 安装阶段版本和依赖冲突现象pip install openclaw报了依赖冲突或者安装完后from openclaw import Agent报 ModuleNotFoundError。常见原因有两个。一是你的环境中同时存在多个 Python 版本pip 装到了别的版本里。排查方法很简单使用python -m pip install openclaw来强制让当前 Python 环境解释器对应的 pip 来安装。二是历史项目里的某些库和 OpenClaw 的依赖有版本冲突。这种情况不要试图手动去改版本号直接创建一个全新的虚拟环境重来十分钟能解决的事没必要花一小时纠缠。5.2 配置阶段Key 填错、地址访问不通现象程序运行后报连接错误、超时、401 鉴权失败。这类问题九成出在配置上。先用一个最小请求验证模型服务本身是否可用不要直接跑完整智能体代码。如果你用的是云端模型服务检查 key 是否复制完整、有没有多余的空格Base URL 末尾有没有多余的斜杠模型标识是否拼写正确。如果你用的是本地服务重点检查服务是否在监听预期的端口。很多新手起了一个模型服务在 8080 端口却把 URL 写成了 9090那自然是连不上的。用浏览器访问一下那个 URL确认能返回响应再回来跑代码。5.3 调试技巧打开日志和逐步验证OpenClaw 支持调试日志我建议新手一开始就开着跑。设置环境变量再运行export OPENCLAW_DEBUG1 python hello_lobster.py打开日志之后你会看到模型请求的完整上下文、工具调用的触发过程、工具执行的返回值。智能体“卡住”的时候日志能直接告诉你卡在哪一步是模型没生成工具调用指令还是工具执行报错还是工具结果没正确回传给模型。另一个笨办法但极其有效的调试方式是分步验证。先测试工具函数本身能不能跑通直接调用get_word_count(你好)看返回值。再测试模型服务能不能通用agent.run(你好)单轮对话。每个环节都验证过了最后再拼装完整任务。这样排查效率最高也更不容易在一堆报错信息里迷失方向。这几年智能体开发的热度一直很高框架换来换去但底层的思路变化并不大。OpenClaw 的 Hello World 虽然简单却是理解后续所有复杂机制的好起点。把这条链路吃透了后面无论换更复杂的框架还是自己去封装一套智能体系统都会有扎实的底气。我个人始终觉得学智能体开发第一步不是去追逐那些花哨的多智能体框架而是亲手把一个最小循环跑通体会到“模型→工具→反馈→再生成”的节奏。那种感觉比看多少篇架构解析都来得实在。
“龙虾智能体”这个词我第一次听的时候也愣了一下。明明是写代码怎么突然跑到海鲜市场去了后来在 OpenClaw 的社区里泡了一阵子才明白这个开源智能体框架的吉祥物就是一只举着大钳子的龙虾社区也就习惯把基于它写出来的智能体程序叫做龙虾智能体。名字是有点俏皮但框架本身一点不花哨。我最近拿它带着几个刚入门智能体开发的朋友做练习发现这个框架对新手非常友好依赖少、逻辑直、调试路径短比动不动就上多智能体编排的大型框架合适得多。这篇文章就带你跑通第一个 Hello World 版的 OpenClaw 龙虾智能体程序。我不讲虚的直接给可复制的代码把环境怎么搭、代码怎么拆、运行背后发生了什么全给你讲清楚。你不需要事先懂大模型原理只要会一点 Python 基础跟着抄就能跑起来。跑通了以后你再看更复杂的智能体项目思路会清晰很多。1. OpenClaw 到底是个什么一只龙虾的自我修养先把这个框架的定位说清楚。OpenClaw 是一个面向智能体应用开发的开源框架它把大语言模型推理、工具调用、任务流程编排这几个能力封装成了一个最小可用的运行环境。你可以把它理解为一套脚手架模型是龙虾的大脑工具是龙虾的钳子而 OpenClaw 本身是连接这两者的神经系统。它解决的问题很实际。裸用模型聊天你只能一问一答模型没法访问外部数据也没法操作任何真实功能。传统编程方式自己写一个循环来处理模型返回的“工具调用意图”又很麻烦。OpenClaw 把中间这一层逻辑标准化了你只需要定义好智能体的角色、配置好模型入口、挂上几个工具函数一个能自主决策、调用工具、迭代解决问题的智能体就成型了。这个框架适合谁来用我理解有三类人。第一类是刚接触智能体开发的新手想找一个简单案例快速建立全局认知第二类是在产品原型阶段需要快速验证“智能体工具”方案的开发者第三类是教学场景里带学生入门 AI 应用开发的老师。如果你属于这三类OpenClaw 的路子就特别对味。1.1 为什么是 OpenClaw 而不是其他框架我前前后后试过不少智能体框架有的强调图形化编排有的主打多智能体协作功能听起来很猛但新手一旦开始实际写代码就很容易陷进去一大堆概念堆在面前还没跑通 Hello World 就先被“对话记忆”“任务分解”这些名词淹没了。OpenClaw 的开箱体验明显不同。它的最小工作流只有四步接收用户输入组装上下文交给模型推理然后根据推理结果执行工具或返回回复。你不需要理解复杂的图结构也不需要提前规划智能体之间的通信协议。这种简化不是功能上的妥协而是把“智能体”这个概念还原到了它最本质的形态一个能调用工具的循环决策器。另外它的依赖管理非常克制。安装包体积小不强制你装一堆可视化组件和中间件对国内开发环境下常见的网络限制也做了兼容具体安装方式见下一节。这几年智能体框架更新得很快但 OpenClaw 的核心接口一直很稳定这也是我敢把它推荐给新手的原因之一。1.2 龙虾智能体的三层结构如果你把 OpenClaw 跑起来之后观察它的行为会很容易总结出一个三层结构感知层负责接收外部输入把用户的自然语言指令、系统提示词、历史对话记录拼装成一个标准化的上下文对象。这个环节决定了智能体“能看到什么”。思考层是模型的推理过程。模型基于当前的上下文输出两种可能性之一要么直接返回一条自然语言回复要么生成一个调用工具的指令。OpenClaw 会解析这个指令提取工具名和参数。行动层在框架内部完成根据解析出来的工具名去执行对应函数然后把执行结果返回到模型中让模型决定下一步怎么做。这个循环会一直持续直到智能体认为任务完成。你可以用龙虾来类比这套结构触角是感知层神经节是思考层钳子是行动层。一只龙虾如果只有大脑没有钳子那它就是个聊天盒子只有钳子没有大脑那它就是个被动的函数库。OpenClaw 的价值就是帮我们把三层有机地串起来。2. 环境准备与 Hello World 最小代码现在进入正题。这部分我尽量压缩概念先给你一套能跑的代码跑起来之后再逐渐解释细节。2.1 环境要求与安装OpenClaw 要求 Python 3.9 或以上版本。我建议你装 3.10 或 3.11这两个版本对现代类型注解和异步生态的支持更成熟。用 Debian/Ubuntu 的话 Python 版本通常会比较老可以用python3 --version确认一下。创建虚拟环境是必须养成的习惯不然过几个月你项目多了依赖冲突会逼疯你。在项目目录下执行:mkdir openclaw-hello cd openclaw-hello python3 -m venv venv source venv/bin/activateWindows 环境下激活命令是venv\Scripts\activate。虚拟环境激活后命令行开头会出现(venv)看到这个就对了。然后安装框架本体pip install openclaw如果下载速度慢或者超时可以临时切到国内镜像源pip install openclaw -i https://mirrors.cloud.tencent.com/pypi/simple安装完成后验证一下python -c from openclaw import Agent; print(ok)能打印出 ok说明基础环境没问题。2.2 最小 Hello World 代码下面这份代码是我实测过的精简版把它存成一个文件命名为hello_lobster.py。# hello_lobster.py from openclaw import Agent agent Agent( name小钳, system_prompt( 你是一只名叫小钳的龙虾智能体。 不管用户说什么你都要先热情地说你好呀 然后在回复末尾加上——钳子挥舞.gif。 保持简短不要超过两句话。 ), modelyour_model_provider, api_keyyour_api_key, ) if __name__ __main__: result agent.run(今天天气怎么样) print(result)这份代码直接把Agent对象从框架里导入创建时传入了四个关键参数name是智能体的名字会在日志里出现system_prompt是系统提示词定义了这只龙虾的性格和行为边界model和api_key是模型服务的接入信息。model参数怎么填这个等你看到下一小节就明白了。如果你用的是云端的模型服务就填服务商提供的模型标识字符串如果是本地私有化部署的模型通常填本地服务暴露出来的模型名。关键在于这个参数对应的服务必须兼容标准的对话接口格式OpenClaw 才能正常对接。2.3 第一次运行你会看到什么把代码中的model和api_key换成你能用的模型服务信息然后执行python hello_lobster.py正常的话你会看到终端输出一段文本大致长这样你好呀天气的问题我可不太擅长但我建议你看看窗外——毕竟我这钳子举起来也挡不住雨呀。 ——钳子挥舞.gif输出的内容取决于你配置的模型和提示词但这次跑通的意义远远超过这一句话本身。它证明了完整的链路是通的代码 → OpenClaw 框架 → 模型服务 → 生成回复 → 回到程序输出。这一条链路打通之后后面所有复杂功能都是在这条链路上做扩展。如果你用的是带图形界面的编辑器我建议你顺便跑一下交互式模式。把代码改成agent.chat()程序就会进入一个命令行对话循环可以连续输入多轮消息。这个模式对调试特别方便改提示词、调参数的时候不用反复执行脚本。3. 运行机制拆解龙虾是怎么“钳”住请求的代码跑通了接下来有必要把背后的机制弄清楚。这一节可能会打破一些新手对大模型的浪漫想象智能体其实并不是“真的理解”一句话它是一套工程上的循环决策系统。3.1 一个请求从进入到返回的完整路径当你调用agent.run(今天天气怎么样)时OpenClaw 内部发生了一系列标准动作。第一步框架构造上下文对象。它把系统提示词、用户输入、当前时间等元信息组装成一套模型容易理解的文本模板。系统提示词会被放在最前面相当于给模型划定人格和边界。第二步框架调用模型接口把上下文发送给模型服务等待返回。这一步在网络上有延迟通常几百毫秒到几秒不等取决于模型服务的负载。第三步是判断。模型返回的结果有两种可能一种是一段普通文本这种情况下 OpenClaw 直接把文本作为最终答案返回另一种是一段结构化的工具调用指令OpenClaw 会解析这段指令提取出工具名和参数。第四步如果上一步提取了工具调用意图框架就去注册表里找到对应的工具函数并执行。执行结果会被重新塞回对话上下文再提交给模型让模型基于工具结果生成最终回复。这个过程像一条循环管道。新手最容易误解的地方在于很多人觉得智能体应该像一个巨大的程序输入问句直接输出答案其实真实情况是一个可以多次迭代的循环。3.2 为什么智能体“知道”该用什么工具这个问题的答案不在模型本身而在工具的描述信息。你在用 OpenClaw 定义工具时不仅要写 Python 函数还要提供一个描述文本。这个描述文本连同函数签名会被转换成模型能读懂的 schema在每一轮对话时提交给模型。模型通过阅读这些描述从你注册的工具列表里挑选一个最符合当前用户意图的选项。它并不真的“理解”工具背后的代码而是做了个决策哪个工具的说明和参数和用户的问题最匹配。比如你有一个计算字符串长度的工具描述写着“输入文本返回文本字数”模型收到“帮我统计这句话有多少个字”时就会大概率选择这个工具并生成正确的参数。如果你的描述写得含糊模型就会犹豫甚至选错工具。这就是为什么下一节里我反复强调工具描述要具体。3.3 模型配置的三种姿势我认识不少朋友在这一步卡住把代码复制了过去却不知道model和api_key填什么。这里给你梳理三种常见配置方式。第一种是云端托管服务的兼容接口。这种方式最省事你只需要注册一个账号拿一串 API Key填上服务商提供的模型标识即可。有的服务商要求填 Base URLOpenClaw 也提供了对应的配置项。第二种是本地私有化部署的模型服务。你本地起一个兼容标准接口的服务监听某个端口然后把model填成服务暴露的模型名称api_key可以填一个占位符。这种方式的好处是数据不出网、没有按量计费适合学习阶段反复测试。第三种是环境变量方式。把敏感信息放在代码里既不安全也不利于协作万一你有一天把代码分享出去API Key 就泄露了。推荐的做法是放在环境变量里import os api_key os.environ.get(OPENCLAW_API_KEY, ) model os.environ.get(OPENCLAW_MODEL, )然后在运行前导出变量。这样代码是干净的密钥留在本地环境分享代码时不怕泄露。4. 给 Hello World 加点料让龙虾学会使用工具光会打招呼的机器人没什么实际价值。智能体的核心能力在于“行动”也就是调用工具去改变一些什么。这一节我带你把上一节的代码升级成一个带工具的版本。4.1 定义第一个工具函数在 OpenClaw 里定义一个工具非常简单。你只需要用装饰器标出一个普通 Python 函数并配上名称和描述信息。# tools/text_tool.py from openclaw import Tool Tool( nameget_word_count, description统计一段中文文本的字数返回整数结果。当用户询问文本有多少个字、多长、多少字符时使用。 ) def get_word_count(text: str) - int: Return the character count. return len(text)这里我特意把 description 写得很啰嗦——不是废话而是给模型提供了足够的情境线索。模型在做工具选择的时候不是看你的函数内部实现而是看名字和描述。描述里多写几个典型的触发场景命中率会直线上升。函数签名也要谨慎。参数名text清晰类型标注str明确返回类型int也准确。OpenClaw 会把类型信息转成模型能识别的参数结构如果类型不对模型生成的参数类型可能没法匹配。4.2 注册工具并跑一个完整任务有了工具函数接下来要把它挂到智能体上。修改我们的主程序# hello_lobster_with_tool.py from openclaw import Agent from tools.text_tool import get_word_count agent Agent( name小钳, system_prompt你是一只名叫小钳的龙虾智能体会使用工具来回答用户的统计类问题。回答要简洁。, modelyour_model_provider, api_keyyour_api_key, tools[get_word_count], ) if __name__ __main__: result agent.run(帮我统计一下这句话有多少个字今天的龙虾真的是太新鲜了) print(result)注意tools参数接收的是一个列表把工具对象传进去就行。能挂多个工具框架会自动组织。运行这段代码你会看到类似这样的输出“今天的龙虾真的是太新鲜了”这句话一共有12个字。从代码逻辑上看你好像只是多传了一个列表但在框架内部发生了一次完整的工具调用循环模型判断用户意图需要统计字数生成工具调用指令框架执行函数拿到结果后再次调用模型生成最终回答。4.3 工具描述写不好会怎样这是我在实际踩坑中记忆最深的一个点。第一次写工具描述的时候我图省事写了一句“计算文本长度”结果模型遇到任何和文本相关的请求都倾向于调用这个工具。用户问“这句话用英文怎么说”它也会去调用字数统计答非所问。后来我总结出了几条经验。描述要写触发条件说明什么场景下用、什么场景下不用。描述要给参数示例比如“text 是要统计的原始字符串不能为空”。描述不要太短但也别写成小作文。模型对描述过长也会失去注意力。函数内部不需要太智能。工具函数尽量做到单一功能判断题“是否应该调用某个工具”是模型的事不要替它做决定。还有一个细节是参数默认值。如果某个参数可以缺省就给它设默认值这能降低模型生成参数的难度。如果参数是必填的描述里最好说明“用户未提供时获取失败要如何兜底”。5. 经常踩的坑与排查速查最后分享一些我带着别人跑这个项目时最常见的报错和排查思路。这些东西官方文档不会写得特别细但对新手来说非常救命。5.1 安装阶段版本和依赖冲突现象pip install openclaw报了依赖冲突或者安装完后from openclaw import Agent报 ModuleNotFoundError。常见原因有两个。一是你的环境中同时存在多个 Python 版本pip 装到了别的版本里。排查方法很简单使用python -m pip install openclaw来强制让当前 Python 环境解释器对应的 pip 来安装。二是历史项目里的某些库和 OpenClaw 的依赖有版本冲突。这种情况不要试图手动去改版本号直接创建一个全新的虚拟环境重来十分钟能解决的事没必要花一小时纠缠。5.2 配置阶段Key 填错、地址访问不通现象程序运行后报连接错误、超时、401 鉴权失败。这类问题九成出在配置上。先用一个最小请求验证模型服务本身是否可用不要直接跑完整智能体代码。如果你用的是云端模型服务检查 key 是否复制完整、有没有多余的空格Base URL 末尾有没有多余的斜杠模型标识是否拼写正确。如果你用的是本地服务重点检查服务是否在监听预期的端口。很多新手起了一个模型服务在 8080 端口却把 URL 写成了 9090那自然是连不上的。用浏览器访问一下那个 URL确认能返回响应再回来跑代码。5.3 调试技巧打开日志和逐步验证OpenClaw 支持调试日志我建议新手一开始就开着跑。设置环境变量再运行export OPENCLAW_DEBUG1 python hello_lobster.py打开日志之后你会看到模型请求的完整上下文、工具调用的触发过程、工具执行的返回值。智能体“卡住”的时候日志能直接告诉你卡在哪一步是模型没生成工具调用指令还是工具执行报错还是工具结果没正确回传给模型。另一个笨办法但极其有效的调试方式是分步验证。先测试工具函数本身能不能跑通直接调用get_word_count(你好)看返回值。再测试模型服务能不能通用agent.run(你好)单轮对话。每个环节都验证过了最后再拼装完整任务。这样排查效率最高也更不容易在一堆报错信息里迷失方向。这几年智能体开发的热度一直很高框架换来换去但底层的思路变化并不大。OpenClaw 的 Hello World 虽然简单却是理解后续所有复杂机制的好起点。把这条链路吃透了后面无论换更复杂的框架还是自己去封装一套智能体系统都会有扎实的底气。我个人始终觉得学智能体开发第一步不是去追逐那些花哨的多智能体框架而是亲手把一个最小循环跑通体会到“模型→工具→反馈→再生成”的节奏。那种感觉比看多少篇架构解析都来得实在。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
