“小龙虾”这个代号我在项目里用了大半年一开始纯属随手起的因为团队里讨论OpenClaw的时候总容易跟另一个内部项目搞混就叫顺口了。但没想到这个名字在社区里慢慢传开经常有人问“小龙虾是不是你们给OpenClaw起的官方中文名”我每次都解释一遍。今天干脆把这大半年的部署、使用、踩坑记录整理成一份完整文档从零开始把OpenClaw从安装到实战的全过程都写清楚包括安卓端Termux部署、Ollama本地模型对接、ROS2环境集成、Skill技能开发这些大家问得最多的问题。这套文档不挑基础纯小白也能照着一步步操作玩过智能体框架的可以跳过基础章节直接看3.2和第四章的排查记录。我先说结论OpenClaw这个框架最大的优势不是功能多而是它的接入层设计得非常干净不管你是想用云端API还是本地模型不管你想跑在PC上还是手机上也不管你要对接聊天、电商还是机器人硬件它都能用同一套核心逻辑跑起来。这也是我当初选它而不是自己造轮子的根本原因。1. 项目整体设计与思路拆解1.1 OpenClaw到底是什么先给新朋友说清楚OpenClaw是什么。它是一个开源的个人智能体框架核心做的事情是把大模型LLM跟外部工具、技能、执行环境连接起来让AI不只是一个聊天的窗口而是一个能真正调工具、读文件、跑流程、操作系统的“代理”。你可以理解成给大模型装了一副手脚。为什么叫“Claw”因为钳子。这个名字挺有意思的一只钳子夹住模型一只钳子夹住工具中间靠一套规则把两边做配对。OpenClaw的前身是另外一个个人助理项目作者在跑通了本地模型和云端模型的混合调度之后把整个框架重写开源了所以我接触到的这个版本天生就对“本地模型优先”这件事支持得特别到位。再说“小龙虾”的来历。因为我第一次在内网部署OpenClaw的时候给仓库起的别名就是crayfish后来同事们叫习惯了。如果你在外面看到有人说“小龙虾部署”基本就是指OpenClaw的部署只是大家图方便起了个花名。1.2 OpenClaw的架构分层要理解OpenClaw不要把它当成一个软件要把它当成一套“中间层”。它分三层第一层是对接层Adapter Layer。这一层解决的是“模型从哪来”的问题。OpenClaw不自己训练模型也不强迫你绑死某一家API而是做了一套统一的模型接入抽象。你可以在配置里声明用OpenAI的API也可以切换到本地的Ollama服务甚至可以在同一个会话里让简单任务走本地小模型、复杂任务走云端大模型。很多人担心OpenClaw是不是只能通过接入API的方式使用算力其实不是用Ollama部署本地模型是完全可行的后面3.2详细讲。第二层是技能层Skill Layer。这一层解决的是“模型能干什么”的问题。OpenClaw把一系列可执行动作封装成“技能”每个技能包含触发条件、参数定义、执行逻辑。比如“查询天气”“读取文件”“执行代码”“调用电商API下单”都是一个个技能。模型根据用户意图选择合适的技能然后把参数填进去框架负责把技能真正跑起来。第三层是运行层Runtime Layer。这一层解决的是“在哪里跑”的问题。OpenClaw的运行环境不挑食x86服务器可以跑ARM开发板可以跑安卓手机通过Termux也能跑而且支持跟ROS2机器人系统做集成被动通过Gazebo仿真环境做联调。这背后的原因在于运行层是基于跨平台框架写的依赖项不多核心代码对资源占用控制得比较狠。这三层各干各的活互不干扰。我刚开始折腾的时候一度想改技能层的东西结果发现完全碰不到对接层的代码这就是分层设计的好处。你不需要懂全部代码只需要找到自己想改的那一层就够了。这也是OpenClaw最有价值的地方它没有把“模型接入”“技能执行”“环境适配”搅成一锅粥而是把这三件事牢牢拆开插拔式使用。官方仓库里的文档叫OpenClaw Docs我这份文档叫“小龙虾文档”内容本质上是同一件事的两种记录方式。1.3 方案选型为什么选OpenClaw我自己不是没写过智能体框架早期用LangChain做过一个内部工具做了一半就放弃了。核心原因是LangChain的抽象层次太多出问题之后你想排查需要从回调、链、代理、记忆这些概念里一层层翻排查成本太高。我在OpenClaw上跑通第一个技能总共用了一个晚上而这个时间在LangChain里可能还没把Agent的依赖理清楚。选OpenClaw还有一个很现实的原因它把“记忆”和“上下文管理”做得很轻。很多智能体框架会把对话历史、向量记忆、长短期存储这些东西做成必选项还没干活就要先跑一个向量数据库项目复杂度一下子拉爆。OpenClaw把记忆做成可选项默认只做简单的会话上下文拼接如果你确实需要长期记忆再自己去接向量库。这个设计决策我非常认同因为80%的智能体应用场景根本用不到长期记忆硬加一个向量库纯粹是给自己找麻烦。从资源占用角度来说OpenClaw也占优势。我实测过一个空载的OpenClaw常驻内存大概在150MB到300MB左右这取决于你开了多少技能。对比其他主流智能体框架动不动上GB的常驻内存这已经算轻量级了。而且在树莓派上跑起来的时候OpenClaw不会像别的框架那样直接卡死虽然推理速度还是受算力限制但至少框架本身不会成为性能瓶颈。2. 核心细节解析与实操要点2.1 安装OpenClaw的两种主流方式OpenClaw的安装方式一直在演进从最早的源码手动编译到现在有了相对成熟的包管理器支持整体门槛已经降了很多。目前最推荐的方式有两个Docker部署和源码本地部署。Docker部署适合那些不想污染自己Python环境的人也适合快速试玩。一条命令就能把整个框架拉起来数据库、redis、主进程都封装在容器里。但这里有个注意点你要是打算用Ollama做本地模型不建议直接用Docker因为容器内的网络和Ollama服务互联需要额外配置容易踩坑。如果非要用Docker可以参考这样的做法先把Ollama安装在宿主机上监听0.0.0.0:11434然后Docker启动的时候加--networkhost参数这样容器直接共享宿主机网络访问localhost:11434就能连上Ollama避免Docker内网不通的尴尬。源码本地部署是我个人最推荐的方式尤其适合要写技能、改配置、深度定制的人。步骤很简单拉取仓库源码用Python 3.10以上的环境创建虚拟环境安装依赖。需要注意的一点是OpenClaw有些依赖编译需要系统库支持比如某些工具链需要libffi和libssl的dev版本装依赖前先把这些系统包补齐。部署这块没必要追求“看起来高级”我见过有人非要去折腾K8s部署OpenClaw用是能用但纯属给自己加负担。单机部署完全够用等真正有了多机或高可用需求再考虑容器编排那个阶段已经是另一个话题了。2.2 配置文件的正确打开方式OpenClaw的配置文件采用YAML格式核心配置集中在config目录下主要就三个文件一个是主配置config.yaml一个是技能配置skills.yaml还有一个是模型接入的models.yaml。新手上路最容易犯的错误是试图在一开始就理解所有字段其实不需要。你只需要关注几个核心字段第一个是agent.name这是给智能体取名字的影响日志输出和会话标识。第二个是model.default_provider和model.default_model这两个字段决定了智能体默认使用哪家模型服务。第三个是skill.enabled_skills列表这里声明哪些技能处于激活状态不在列表里的技能不会被加载。改配置之后不需要重新编译保存后重启服务即可生效。但有一个坑要提醒OpenClaw的配置解析对缩进很敏感YAML格式错一个空格启动的时候直接报错而且报错信息往往指向一个完全不相关的语法位置。如果你改了配置启动失败第一件事不是去看代码而是检查YAML缩进有没有对齐。2.3 技能开发的核心逻辑技能是OpenClaw最核心的扩展单元。一个技能本质上是一个Python模块里面定义几个关键方法定义技能元数据、接收参数并执行、返回执行结果。框架会把这个技能注册到能力列表里模型在生成回复的时候会根据技能名称和描述决定是否调用。写技能有个非常容易忽略的点技能描述要写清楚“什么时候该用这个技能”和“什么时候不该用这个技能”。这个描述会直接影响模型的选择效果。比如你写一个查天气的技能描述如果只写“查询天气”模型在用户问天气的时候可能会调用也可能不调用。但如果你把描述写成“当用户询问某个城市的当前天气或未来天气预报时使用需要城市名参数”模型命中率会明显提升。原因是LLM的工具选择很大程度依赖描述语义描述写得越具体越准确选错工具的概率就越低。另一个实操心得是技能的输入参数定义要尽量用类型注解并写清楚每个参数的含义。OpenClaw的技能参数传递是基于JSON Schema的模型会根据schema生成参数。如果你把一个参数定义为字符串类型模型传数字进来也能转成字符串不会报错。但如果你把一个参数定义为整型模型传了“今天”这种非数字内容框架会尝试转换失败然后报错。所以参数类型设置要跟实际业务相匹配别为了省事全用字符串。2.4 技能与上下文管理的协作细节OpenClaw的上下文管理机制很有意思它默认会把最近的N轮对话打包发送给模型但有一个细节是如果某个技能执行结果特别长比如读了一个大文件返回了10万字符框架会自动把这段结果压缩成摘要再放回对话上下文避免把上下文撑爆。这个机制在长文档处理场景下特别好用也解释了为什么OpenClaw在长文本场景下不容易出现约上下文长度报错因为它在源头就做了取舍。我一开始没搞清楚这个机制在写日志分析技能的时候日志文件有几万行技能执行后直接返回了全部内容模型立刻被撑爆报错说超出token限制。后来翻源码才发现框架里有个large_return_summary_threshold参数默认值是8000字符。超过了这个长度框架会用摘要模型把执行结果压缩。你完全可以调整这个阈值缩短到2000或者拉到50000取决于你的模型上下文窗口有多大。这个参数在哪里配非常重要我在3.3节配置实操里会有完整说明。3. 实操过程与核心环节实现3.1 源码部署OpenClaw的完整流程我用Ubuntu 22.04虚拟机作为演示环境Python版本3.11这是目前最稳的组合。先把系统依赖补齐sudo apt update sudo apt install -y build-essential libssl-dev libffi-dev python3-dev git curl然后是拉取源码和创建虚拟环境git clone https://github.com/OpenClaw-project/openclaw.git cd openclaw python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt这里有个关键提示依赖安装时间可能比较久因为里面有几个是源码编译安装的包比如某些加密库和网络库需要本地的编译器参与编译。在干净的机器上第一次装我实测大概是15到20分钟。如果你是在国内网络环境安装可能需要换pip源否则大概率会在下载依赖的超时问题上反复挣扎。改成清华源或者阿里源之后速度会明显提升。依赖装好之后先在源码目录下找到config目录里的config.example.yaml复制一份为config.yaml。第一次启动之前不要急着改太多配置先把默认配置启动一次确认框架能跑通再逐项调整。启动命令是python main.py第一次启动会创建日志目录和数据目录并输出初始化信息。如果你看到输出里出现了类似Agent initialized successfully的内容说明核心安装已经完成。这时你可以在命令行里跟它对话测试输入“你好”如果模型回你“你好我是你的智能助理”那就通了。3.2 用Ollama部署本地模型彻底摆脱API依赖这是大家问得最多的问题之一。OpenClaw对Ollama的接入做得非常顺滑完全不需要写复杂代码配置两步就能搞定。第一步是确保本地已经跑起来了Ollama服务并且已经拉取了你要用的模型比如用qwen2.5的7B版本或者llama3.1的8B版本看你机器的显存和内存情况。第二步是修改OpenClaw配置里的models.yaml把默认provider从openai改成ollama。我实际的配置长这样model: default_provider: ollama providers: ollama: base_url: http://localhost:11434 model: qwen2.5:7b这里有个很容易踩的坑OpenClaw要求Ollama的API路径base_url指向Ollama服务根地址千万不要在末尾加上/v1或者/api直接写http://localhost:11434就对了。因为OpenClaw自己会在内部拼接正确的API路径你多写一层路径就会导致请求404或者路由错误。另外一个性能相关的建议如果你用Ollama本地部署建议在模型参数里开启num_ctx设置。因为OpenClaw默认会发送较长上下文给模型而Ollama的默认上下文长度可能不够会出现“对话稍微长一点就报错”的情况。在Ollama的配置里设置num_ctx: 81928K上下文比较稳妥。这一步不做你在对话超过几轮之后就会遇到上下文被截断或者报错的问题。实际体验下来用7B级别的量化模型在消费级显卡上单轮响应时间大概在1到3秒完全够用。如果是日常聊天和简单任务处理本地模型跟API的差距并没有想象中那么大。只有在复杂推理、代码生成这些需要强模型能力的场景下本地小模型的短板才会暴露出来。3.3 核心配置实操Ollama、上下文与多技能协同配置实操不只是改YAML关键在于理解参数之间的关系。先列一个我实际在用、经过压力测试的配置模板你照着填可以直接跑起来agent: name: crayfish system_prompt: 你是小龙虾助手一个乐于助人的智能体。当需要工具时请直接使用工具不要回避。 model: default_provider: ollama providers: ollama: base_url: http://localhost:11434 model: qwen2.5:7b temperature: 0.7 max_tokens: 2048 context: max_rounds: 10 max_tokens: 8192 large_return_summary_threshold: 8000 skill: enabled_skills: - echo - file_reader - web_search - calculator auto_load: true这个模板里有几个参数值得展开讲。温度设为0.7是目前比较均衡的取值。如果做代码生成和数据分析类任务建议降到0.2以下减少幻觉如果做创意写作可以调到0.9以上。max_tokens是模型单次回复的最大输出长度2048对大多数任务够用。如果你要让模型生成大段代码或者长文调到4096以上会更从容。max_rounds是保留最近多少轮对话历史10轮是一个平衡点——既能让模型有足够上下文理解意图又不至于每轮都发送过多消息导致模型处理变慢。max_tokens和large_return_summary_threshold之间有关系8K的上下文窗口建议把摘要阈值设在8000这样即使技能返回了长篇内容框架也能在塞进模型之前先做摘要处理。如果你把模型换成32K上下文的专属版本可以把阈值调到20000以上尽量保留原始信息。多技能协同是OpenClaw的另一个亮点。当多个技能同时启用时框架支持模型在单轮响应中连续调用多个技能。比如用户说“帮我查一下北京的天气然后把结果存到文件里”OpenClaw会依次调用查询天气技能然后把结果写入文件技能。整个过程不需要人为干预。实测下来这种多步调用在qwen2.5和llama3.1上都能稳定实现前提是每个技能的描述写得足够清晰。3.4 安卓端部署Termux跑OpenClaw步骤详解手机部署OpenClaw是很多人的刚需毕竟不是所有人随时都能打开电脑。通过Termux在安卓手机上跑OpenClaw是完全可行的而且体验超出了很多人的预期。前提是你的手机内存至少6GB推荐8GB以上因为OpenClaw进程本身加系统占用内存太小会频繁被杀后台。Termux安装OpenClaw分几步。第一步准备Termux环境从F-Droid下载Termux不要用Google Play版本Play版旧且缺少维护。启动后先更新软件源。这里有个Termux特有的坑新版Termux默认没有存储权限需要先跑一次storage授权否则后面建目录都操作不了。然后安装必要依赖pkg update pkg install python python-pip git rust binutils为什么需要rust和binutils因为OpenClaw的一部分依赖涉及Python加密库和网络库的编译Termux环境下没有预编译轮子只能本地编译没有rust和C编译器直接失败。这一步是很多教程里没提的我也是折腾了两天才搞清楚。然后跟PC端一样创建虚拟环境拉源码装依赖git clone https://github.com/OpenClaw-project/openclaw.git cd openclaw python -m venv venv source venv/bin/activate pip install -r requirements.txt在手机上编译依赖的时间会比PC长不少实测大概40分钟到1小时取决于手机性能。装完之后配置文件跟PC一样只是模型接入这里有个特殊推荐手机端部署不建议跑本地大模型7B模型在手机上运行会非常吃力推理速度能慢到没法用。更好的做法是配置远程Ollama服务比如你家局域网里的PC或者一台云主机。手机端跑OpenClaw最大的价值在于你可以随时通过手机的聊天界面控制家里的设备、查信息、执行脚本。这就相当于把智能体装进了口袋而不是把大模型塞进手机。3.5 进阶玩法OpenClaw ROS2 Humble Gazebo环境集成这个玩法是我做仿真机器人项目时候整理的。OpenClaw和ROS2集成后可以让大模型控制机器人的行为成为机器人任务的智能体大脑。需要准备ROS2 Humble环境加Gazebo仿真环境然后把OpenClaw作为一个ROS2节点接入。集成方案的核心思路是OpenClaw作为决策节点接收自然语言指令输出对应的机器人控制指令经过ROS2话题传递到机器人端执行。具体操作步骤不少但核心只有三点一是用ros2的Python绑定库封装一个桥接层把OpenClaw的技能执行结果发布到ROS2的话题上。二是把OpenClaw的技能层注册到ROS2动作服务器让机器人执行过程可以被追踪和反馈。三是Gazebo仿真环境里设置好机器人的模型和传感器数据让OpenClaw能通过ROS2话题获取环境信息。这套集成的门槛比纯软件部署要高不少适合有ROS2基础的人尝试。没接触过ROS的可以先把前几步部署搞定这个进阶玩法不急。但如果你本身就在做机器人开发OpenClaw可以帮你省掉大量写固定对话脚本的工作直接让自然语言变成机器人动作序列。3.6 电商场景实践OpenClaw做智能客服与订单助手OpenClaw在电商场景的落地是最近社区讨论较热的方向。它解决的一个核心痛点是订单查询、物流跟踪、退换货处理这些重复性咨询花费了客服大量时间。把OpenClaw接入电商系统后台用技能去调用订单查询API、物流API、库存API一个智能客服的雏形就出来了。我做过一个最小可行版本用OpenClaw对接一个模拟电商API。需要写三个技能一个是查询订单状态一个是查询物流信息一个是生成订单摘要。每个技能内部调用对应的HTTP接口返回JSON数据再处理成自然语言回复。实际跑起来之后用户问“我618买的那个红色外套发货了吗”OpenClaw会调用订单查询技能匹配订单号和商品信息再调用物流API最后整合成一句回复。这个落地过程还有一个价值点OpenClaw与Ollama本地部署结合可以做到整个客服系统没有外部API调用数据全部内部流转。对于重视数据合规的中小商家这是很关键的卖点。不需要把客服对话内容传到第三方平台所有推理都在本地完成这对于涉及用户隐私和交易数据的场景是天然优势。4. 常见问题与排查技巧实录4.1 安装阶段五大典型报错与解法我整理一下这段时间收集到的最高频安装报错按出现频率排序。问题一pip安装依赖时编译报错。错误信息里往往含有gcc、error: command gcc failed的字样。原因是系统缺少编译依赖。解法是提前安装build-essential、libssl-dev、libffi-dev这些包。如果你用的是CentOS系对应包名是gcc-c、openssl-devel、libffi-devel。问题二Ollama连接失败报错Connection refused。这个90%是base_url写错或者Ollama服务没启动。先确认curl能访问你的base_url地址确认能通再看配置。还有一种是改了配置但没重启OpenClaw新配置根本没加载。问题三启动时提示YAML配置解析失败。几乎都是缩进问题。建议用带格式化校验的编辑器修改YAML看到对齐红线就知道哪里错了省掉脑内校验。问题四启动成功但对话无响应。这时候先看日志文件在logs目录下。如果日志里显示模型调用超时那十有八九是模型服务那边的问题。本地模型要确认显存占用是否已经打满API服务要确认网络是不是正常API key是不是过期。问题五Termux安装时报Python版本不支持。Termux官方源的Python版本可能较旧OpenClaw依赖Python 3.10这种情况下需要先把Python升级或者用proot-distro安装一个较新的Ubuntu环境再操作。proot-distro方案虽然慢一点但兼容性更好推荐遇到版本问题的朋友直接走这条路。4.2 运行时性能优化和内存控制跑OpenClaw最需要担心的不是功能问题而是内存。默认配置下OpenClaw空载内存占用不高但一旦加载多个技能并开启多轮会话内存会涨得很快。我在4GB内存的服务器上实测空载170MB开了4个技能之后到了260MB对话上下文长了之后最高冲到600MB。虽然不算离谱但如果你还想在同一个机器上跑Ollama的7B模型那内存就会很紧张。优化逻辑很明确。一是只启用你用得到的技能别把所有技能全部开起来。二是调低max_rounds减少历史消息堆积。三是控制大文件返回把摘要阈值调低。这三步可以显著降低内存峰值。另外有一个容易被忽视的内存问题Ollama的模型是常驻内存的。7B量化模型大概占4-6GB内存如果机器内存小于16GB跑起来会比较吃力系统会频繁使用swap导致卡顿。这种情况下强烈建议把模型量级别降低改用3B或1.5B的模型速度优先。4.3 技能不触发或调用错误怎么排查这是日常使用中出现频率最高的问题。技能不触发通常有两个原因。第一是技能描述跟用户意图的匹配度不够。描述太泛模型判断不出来该用哪个技能。第二是技能确实被调用了但模型生成的参数不符合要求技能执行时报错最终被框架当成“调用失败”处理。我的经验是先从日志里确认技能到底有没有被调用。OpenClaw会记录每次技能调用的日志包括选择了哪个技能、传了什么参数。看日志就能定位是在“选择技能”环节出了问题还是在“执行技能”环节出了问题。选择环节出问题就改描述执行环节出问题就改参数定义和容错逻辑。另外要养成一个习惯新写的技能先在配置里单独启用用一个简单任务测试通过再混入多个技能一起跑。否则多个技能同时启用时模型选错技能的概率会增加排查起来也麻烦。4.4 网络波动与模型响应异常的处理预案OpenClaw在使用外部API时最烦人的问题就是网络抖动导致的模型响应异常。我遇到过的情况主要有三类。第一类是请求超时模型那边响应太慢OpenClaw等不到结果直接报错。第二类是请求成功但是响应内容为空模型没有生成任何文本。第三类是模型服务偶发5xx错误导致会话中断。针对这三类问题OpenClaw内部提供了一些容错机制但默认参数不一定合理。建议手动调大请求超时时间把默认的60秒改成120秒给慢模型更多时间。同时开启自动重试机制的开关让OpenClaw在遇到5xx或超时的时候自动重试一次。重试次数不要超过两次否则真实故障场景下会反复卡住。本地Ollama部署虽然不受网络波动影响但也有自己的特殊问题如果Ollama在推理过程中出现显存不足进程会直接崩溃OpenClaw会收到Ollama返回的错误信息。这种问题只能从Ollama端解决要么换小模型要么减少并发请求。5. 避坑心得与扩展方向前面写了很多操作细节最后分享几个我在实际使用中总结的心得。第一个心得是关于密码和密钥的管理。OpenClaw配置里会存API key这类敏感信息如果你有把配置传到Git仓库的习惯一定要小心。我见过不止一个人把带密钥的config.yaml直接提交到GitHub结果过几天收到扫描机器人的告警邮件密钥已经泄露了。建议把密钥相关的部分单独提取出来用环境变量注入不要写死在配置文件里。第二个心得是日志的价值远超预期。OpenClaw的logs目录下有完整的运行日志每一次技能调用、每一次模型请求、每一次异常捕获都有记录。遇到任何奇怪问题先看日志而不是先猜原因。我在很长一段时间里都是“出问题看一眼日志”排查效率比盲目改配置高十倍不止。第三个心得是技能设计上要遵循单一职责原则。不要尝试写一个“超级技能”处理所有事情那样只会让技能描述难以写清楚模型也难以选择。宁可拆细一点一个技能只做一件事用多个技能编排完成复杂任务。这个思路不仅让模型选择更准确也让代码更容易维护。说到扩展方向OpenClaw的可能性还很大。我最近在尝试的是把OpenClaw跟本地的语音识别服务串起来做一个完全本地的语音助手。还有个思路是给OpenClaw加一个定时任务调度器让它能周期性执行巡检类技能把家庭智能化和办公自动化的能力进一步打通。这些方向都值得折腾核心逻辑不变OpenClaw做大脑大模型做推理技能做手脚剩下的就是你对场景的想象力。这套“小龙虾”文档可以说是把我这大半年跟OpenClaw的爱恨情仇都写下来了。从第一晚通宵部署成功时的兴奋到在Termux上编译失败时的抓狂再到ROS2环境跑通机器人仿真的成就感这些经历都融在这些文字里了。希望它能让你少走我走过的弯路尽快把OpenClaw跑起来用起来玩出你自己的花样。
