养虾这件事说透了就三件事看水、喂食、防病。可这三件事放到几个塘面上靠两条腿跑根本跑不过来。我去年底开始搞一套不用我天天蹲塘边的监控方案定位是用智能体来调度摄像头和传感器最终选了OpenClaw。Claw这个名字挺对我的胃口——它就像一个伸向虾塘的爪子既能抓数据也能抓问题。这个系列我打算从零到一记录整个过程这一篇是第一篇先把基础配置和Tool设置说清楚再把配置期遇到的一堆杂碎问题集中整理出来。如果你也想用智能体框架做农业环境监控或者正在纠结怎么把自己的工具挂给大模型这篇的内容应该能用上。1. 为什么让OpenClaw来“看”虾塘1.1 传统阈值告警在真实塘口根本不够用最早我想得很简单买几个水质传感器设好阈值超过就告警。水温高于29度提醒我开增氧机溶氧低于4mg/L提醒我加氧这套逻辑用脚本就能跑。但真正下塘之后发现不对劲。中午太阳暴晒表层水温能短暂冲到30度可底层的虾根本没事半夜溶氧跳水有时候是因为水生物耗氧有时候是因为天气闷热有时候纯粹是传感器探头被藻类糊住了。单一阈值产生大量误报我一个晚上爬起来看三四回最后直接把告警关了。这个经历让我意识到养虾监控需要的不是“单点报警器”而是一个能把多个数据放在一起综合判断的系统。水温、溶氧、pH、天气、摄像头画面这些数据分开看都只是数字合起来看才能反映塘口的真实状态。1.2 OpenClaw的底座定位车间主任加机器的组合OpenClaw本质上是一个智能体运行时。我习惯把它的结构理解成一个流水线车间大模型是车间主任Tool是车间里的机器。车间主任自己不会搬砖但懂调度——它会看当前的数据决定先调用哪个工具、拿到结果之后下一步做什么最后把结论推给你。这个定位很关键。写传统脚本每一条分支逻辑都要人肉想清楚而塘口的异常情况是无穷无尽的用OpenClaw这类框架实际开发量集中在“写好车间里的机器”和“配置好车间主任的权限”而不是写几百行越来越复杂的if else。调度逻辑由模型动态生成遇到意外场景至少有个模型帮你兜底判断。我之所以选OpenClaw而不是自己另写一套任务编排系统就是看中它把“感知、决策、行动”这三层天然分开了。感知层是我的传感器和摄像头决策层是模型行动层是通知和控制设备。后续想加一个投喂机、加一个流量计都只需要在行动层加一个工具。1.3 这套模式适合谁、不适合谁说实话如果只是想做一个温度过高报警器别用OpenClaw一个脚本加上钉钉机器人就够了。杀鸡不用牛刀。但如果你手里有多个传感器、多个摄像头希望系统能够根据综合情况自己决定动作比如“水温高但溶氧正常时先观察水温高且溶氧下跌时才开增氧机”那这套框架的价值就体现出来了。对我来说养虾的塘口不是标准化车间变量太多值得上智能体但如果你只是实验室里一个固定水族箱脚本反而是更稳的选择。2. 基础环境配置先让运行时能站住脚2.1 运行环境与依赖安装OpenClaw是Python生态里的项目官方推荐在Linux环境跑。我用了一台闲置的小主机ARM架构的开发板也可以只要能稳定运行Python 3.10以上版本就行。不建议把主力部署放在Windows上后面接摄像头、串口传感器的时候Linux的驱动和权限处理会省心很多。我建议每个项目单独建虚拟环境别和系统Python混在一起mkdir -p openclaw-shrimp cd openclaw-shrimp python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install openclaw如果是直接拉源码运行就按仓库说明安装依赖。这里最容易踩的坑是依赖冲突OpenClaw会带一批pydantic、httpx、fastapi之类的库如果这台机器上还跑着其他Python项目很容易出现版本对不上。装完之后先验证一下版本python -c import openclaw; print(openclaw.version)能正常输出版本就说明基础安装成功。我当时在这一步卡了快一个小时原因是之前为了跑图像识别装过一个旧版pydanticOpenClaw启动的时候一直报格式错误后来把虚拟环境里的依赖清空重新装了一遍才解决。2.2 目录结构和配置文件拆解跑这种长期项目目录建得清爽能省掉后面很多麻烦。我的建议结构是openclaw-shrimp/ ├── config.yml ├── tools/ ├── logs/ ├── data/ └── scripts/config.yml放主配置tools目录放自定义工具OpenClaw启动时会自动扫描这个目录logs和data分别放日志和运行数据。先建好空目录避免启动时报权限错误mkdir -p logs data主配置文件我整理了一套比较顺手的写法核心内容大概是这样的project: name: shrimp-farm workspace: ./data timezone: Asia/Shanghai model: api_key_env: MODEL_API_KEY model_name: chat-model-v2 temperature: 0.2 max_tokens: 2000 runtime: web_host: 127.0.0.1 web_port: 8230 session_timeout_hours: 72 logging: level: INFO file: ./logs/run.log有几个细节值得单独说。timezone一定要显式配置我最初没写结果日志时间和手机通知时间差了几个小时排查问题的时候对不上时间线非常难受。model的温度我调得比较低因为监控场景要的是稳定输出不需要太多创造性。max_tokens控制在2000以内避免模型一次性输出太长的内容拖慢响应。api_key我建议通过环境变量注入别直接写进配置文件。我习惯在启动前手动加载一个.env文件export MODEL_API_KEY你的密钥 openclaw start --config config.yml2.3 首次启动要走完的验证清单配置写完第一次启动务必按清单确认一遍别急着接工具。第一步确认启动日志里没有任何ERROR级别的输出。第一次启动会初始化数据目录和状态存储正常情况下会看到类似“initialized workspace”的信息。第二步访问Web管理界面。我配置里用的是127.0.0.1:8230浏览器打开确认页面能正常渲染。如果出现端口被占改runtime.web_port或者找出占用进程。第三步在界面上发一条最简单的消息不需要调用任何工具就问问系统“当前状态正常吗”。这一步是验证模型链路通不通。如果这条消息都没回复说明模型提供商配置有问题检查api_key和model_name是否匹配。我当时在第三步发现了问题模型平台给的模型标识和我填的不一致误把版本名当成了模型名系统一直报无效请求。这个检查清单看起来笨但能确认底座是好的后面挂工具时出了错至少能排除“是不是模型本身没接通”这个可能性。3. Tool设置给模型一双能用的“手”3.1 Tool在智能体里的真实身份OpenClaw里Tool的定义本质上就是一段被注册进运行时的函数。你可以把它理解成一个带说明书的接口。系统每轮对话前会把当前可用的工具列表发给模型模型根据工具的名称和描述决定要不要调用、以什么参数调用。这里有个很多人容易搞反的点工具文档写得越清楚模型调用越准确。工具不是写给自己看的是写给模型看的。函数名、参数名、返回结构都必须让模型一眼看懂。我写工具时固定了三个原则函数名用动作加对象比如read_water_tempdocstring里明确写出参数含义和返回结构返回数据统一用dict格式并且带ok字段。这套规范后面帮我省了很多调参时间。3.2 第一个工具读水温水下传感器一般通过串口或MODBUS协议读取工具代码里封装好通信细节暴露给模型的是一个高层的语义接口。示例逻辑如下from openclaw import tool tool def read_water_temp(sensor_id: str) - dict: 读取指定传感器的当前水温。 Args: sensor_id: 传感器编号例如 pond1、pond2。 Returns: dict: 包含 temperature(摄氏度)、unit、ok 三个字段。 # 这里写实际的串口读取逻辑 temp query_sensor(sensor_id) return {temperature: temp, unit: celsius, ok: True}注意docstring里的Args和Returns模型是靠这段文本来理解工具的。返回结构一定要稳定宁可字段多一点也别让模型猜。ok字段尤为重要它告诉模型这次读取是否成功——如果传感器没接好ok为False模型就可以选择换一个工具或直接提示人工介入而不是拿着一个错误的温度值继续往下推理。实际开发时传感器的串口号和通讯参数不要硬编码进工具函数而是放到配置里。这样换设备、换塘口只需要改配置不用改代码。3.3 第二个工具摄像头抓图与图像分析摄像头是养虾场景里信息量最大的传感器。虾的状态、饵料剩余情况、水面异常都要靠图像判断。抓图工具我用OpenCV实现支持本地USB摄像头和RTSP网络流。核心逻辑是先拉一帧画面保存到data目录然后返回图片路径。加了ROI裁剪参数之后可以只拍饵料台区域减少水面上无关画面的干扰import cv2 from openclaw import tool tool def capture_image(camera_id: str, roi: str full) - dict: 从指定摄像头抓取一帧画面并保存。 Args: camera_id: 摄像头编号如 cam1。 roi: 裁剪区域支持 full 或 roi1饵料台区域。 Returns: dict: 包含 image_path、captured_at、ok 字段。 cap cv2.VideoCapture(camera_id) ret, frame cap.read() if not ret: return {image_path: , captured_at: , ok: False} path fdata/{camera_id}_{int(time.time())}.jpg cv2.imwrite(path, frame) cap.release() return {image_path: path, captured_at: time.time(), ok: True}这里有个小技巧如果模型后端支持视觉能力可以让工具直接返回图片路径模型会自动读取如果不支持视觉就单独接一个图像摘要工具把画面描述成文字再交给模型推理。我当时就是用“抓图工具加图像描述工具”组合的方式绕开了模型不支持图片的问题。3.4 权限设计能读的工具开全能控的工具要问人给模型开放的工具越多不可控性越大。我的原则非常简单只读工具全部放开风险工具必须人工确认。水温、溶氧、摄像头、pH这些传感器只读工具随便模型调用看错了也不会造成损坏。但开增氧机、启动投喂机这类控制类工具我设置了confirm模式——模型可以请求执行但真正动作前必须有人点一下确认键。原因是模型推理存在概率性它可能把当前场景误判成缺氧然后自动开机。增氧机开一次的电费是小问题但如果判断失误频繁启停对设备寿命和虾的应激反应影响不小。宁可每次通知我一声我点一下确认也别让模型一个人拍板。工具拆得细也很重要。读溶氧是一个工具开增氧机是另一个工具不要让模型拿到一个“调节水质”的大工具。工具越原子化权限边界越清晰误操作的概率越低。3.5 工具调试验收的快速方法工具写完别急着接完整流程。我习惯先在会话里直接发指令“读取pond1水温”然后观察两步日志里有没有出现“tool called”记录以及传给工具的参数是否合理。如果模型回答“我没有这个工具”先看启动日志里加载的工具列表。很多工具没生效是因为tools目录路径写错了或者函数没有加装饰器标记。我看工具列表时会重点核对函数名函数名大小写不一致也会导致模型找不到对应工具。如果模型调用了工具但参数传得很离谱比如把塘口号写成一个不存在的编号那多半是docstring写得不够清楚。把参数取值范围和示例直接写进描述里这比任何调参都管用。4. 配置期的杂碎问题每条都值得记一笔4.1 摄像头取流失败症状是抓图工具返回ok: False或者日志里出现超时错误。我遇到的情况是RTSP地址里带用户名和密码URL拼接格式不对导致摄像头直接拒连。先用通用视频工具拉流测试一遍确认地址本身没问题再放到OpenCV里读取。第二个坑是cap.read()偶尔返回空帧。摄像头刚启动或者网络抖动时首帧经常读不到。解决方法是加一个重试循环连续读五次直到成功为止。长期摄像头的进程也会有内存泄漏我后来写了定时重启抓图进程的脚本每天一次内存能稳很多。4.2 模型对虾的识别描述不稳定一开始让模型直接描述整张池塘画面它一会儿说看到五十只虾一会儿说看到一百多只完全没法用。后来把ROI裁剪到固定的投喂区并且拍了一张空塘图片作为基线让模型对照“多了什么、少了什么”准确率明显提升。水面反光和飘动的浮游植物最容易干扰判断。尽量让摄像头固定机位、顺光拍摄减少环境变量。这套东西本质上是“控制变量”画面越稳定模型越容易做对比。4.3 长时间运行内存持续上涨OpenClaw会把对话历史存在会话里跑的越久占的内存和token越多。我最初让会话一直不清理第三天系统响应就开始明显变慢。后来把session_timeout_hours调短并加了定时清理逻辑对监控类任务来说它不需要像聊天助手那样记住几个月前的对话。还有一个小经验日志文件也会越来越大。logging配置里加rotating策略按天切割保存最近七天的日志既方便排查又不占磁盘。4.4 配置修改不生效这个问题排查了我不少时间。改完config.yml重启之后发现模型还是按旧配置跑。后来确认是端口被暂存等机制问题配置文件解析缓存导致。解决办法是修改配置之后必须完整重启进程并确认启动日志里读取的是新配置路径。这类问题整理了一下可以做个参考问题表现最可能的原因解决方向摄像头抓图返回ok: False流地址拼接错误或网络抖动单独拉流验证地址加读取重试模型对图像描述不稳定视角不固定、画面干扰多裁剪ROI加空塘基线对照长期运行响应越来越慢会话历史过长、日志过大调短session_timeout日志按天切割改配置后行为没变化缓存了旧配置未完整重启完整重启并核对启动日志工具列表里找不到某工具tools目录路径错误或装饰器漏写核对扫描路径和注册语法5. 把第一个流程跑通后的体会和下一步5.1 从“能跑”到“能用”的差别OpenClaw配置完、挂上三五个工具之后系统已经能跑了但离“能用”还有一段距离。我第一个跑通的自动化流程是定时巡检每半小时抓一次饵料台画面让模型描述虾的活跃度如果连续三次发现饵料没动静就push一条通知到手机。这个流程能跑通核心不是模型有多聪明而是前面拆得细、描述写得清、权限边界画得明。模型只不过是在一个清晰的工具集里面做决策先读摄像头再决定要不要发告警。我个人的经验是先把环境跑通再挂一个纯读工具确认调用链路没有问题最后才加控制类工具。顺序就是“能读再能控能控再自动化”跳步很容易出问题。5.2 后续想在这个系列里聊的内容接着我会把“投喂异常检测”这个流程补完整——目前能识别到饵料剩余但还没有把温度、溶氧、虾的活动度合在一起做成一个综合状态评分。等这个评分模型跑起来我再写第02篇。这一篇记录的基础配置和Tool设置算是整个项目的底座。那些“杂碎问题”看着不起眼实际配置的时候每条都能磨掉你半晚上。把它们写出来是希望看完这篇的朋友可以直接绕开这些坑把时间花在真正有价值的事情上。