简介这套资源面向需要在OpenClaw环境中操作MySQL数据库的开发者提供了一套从零实现增删改查技能的可参考方案。由于官方ClawHub没有现成的数据库增删改查技能作者基于技能模板使用Python完成了数据操作功能的开发覆盖数据插入、查询、更新与删除四个核心动作也给出了数据库连接信息配置与函数封装的完整写法。压缩包内共3个文件大小约3KB分别是Python脚本、Markdown说明文档和HTML展示页面脚本实现数据库连接与增删改查逻辑文档介绍开发步骤、异常处理及安全建议HTML页面用于查看技能调用效果。目前已有164人学习浏览。该方案还考虑了SQL注入防范、健壮性测试和框架规范适配等问题结构简洁适合技术人员快速理解OpenClaw技能开发流程并用于自身项目中的MySQL数据管理。1. OpenClaw技能让对话里的“查一下订单表”变成真实SQL很多人在OpenClaw里配好了模型、接好了渠道结果发现它只会聊天不会干活。真正让OpenClaw从“聊天机器人”变成“数字员工”的是技能Skill机制——它把自然语言里的意图翻译成一段确定的脚本或SQL去执行。本文要解决的就是把这个机制落到MySQL上让OpenClaw通过技能直接对数据库做增删改查而不是让模型即兴编SQL。这套方案的适用人群很明确已经在用OpenClaw做助手或自动化、手里有一台MySQL本地或远程都行、不想每次操作数据库都手工开客户端的人。读完你会得到一份可直接抄的Skill配置含连接参数、语句模板、权限边界和排错清单。OpenClaw的部署方式Docker、Windows Hub安装或Linux裸装不影响技能本身的写法差异只在于技能目录放哪、环境变量怎么注入。先说结论这个方向值得做性价比很高但坑不在“技能怎么写”而在“MySQL连接串怎么传”“会话锁怎么破”“返回结果怎么截断”。下面按“机制→最小配置→五个操作→参数与权限→避坑→验证进阶”的顺序展开。2. 技能机制与落地路径先把“技能”拆成看得见摸得着的文件2.1 OpenClaw技能的三层结构Action、Command与RoutineOpenClaw的技能不是一段散装prompt而是一组按约定存放的文件。社区里最常见的目录结构是skills/下按技能名建子目录每个目录里放SKILL.md作为技能说明配一个或多个可执行脚本Python、Bash、SQL文件都行必要时加params.json或config.yaml描述入参。按我的使用习惯把技能分成三类Action类单次动作比如“查一下今天的订单数”对应一个读SQL。Command类带参数的命令比如“给用户ID为1024的用户加500积分”需要传参进SQL。Routine类多步骤流程比如“每天凌晨同步远程表到本地”需要写脚本串多个SQL。理解这个分层很重要因为增删改查四个操作对应不同类型的技能设计。SELECT适合做ActionINSERT/UPDATE/DELETE必须做Command要有参数校验多表联动的场景才需要Routine。把技能都堆成“一句话一段SQL”是新手最常见的翻车点——模型没有能力替你判断参数合法性它只会按技能描述里的示例去填值。2.2 技能文件里到底写什么SKILL.md是给模型看的“说明书”SKILL.md是OpenClaw决定“什么时候调用这个技能”的依据。模型会读这个文件里的描述、参数说明和示例然后决定要不要触发。写得越具体误触发的概率越低。我一般这样写SKILL.md的骨架--- name: mysql_query description: 对MySQL数据库执行SELECT查询。仅用于读取操作禁止写操作。 params: sql: type: string description: 完整的SELECT语句必须带WHERE条件禁止SELECT *。 --- 你是一个MySQL查询执行器。用户给出查询意图后你将意图改写为SQL并调用下方脚本执行。这个文件看起来简单但有两个细节直接影响成功率一是params里声明了sql这个入参模型会尽量按照你给的参数名去填充二是在描述里写死“仅用于SELECT禁止写操作”能大幅降低模型在查询技能里顺手执行UPDATE的概率。如果技能描述写得模糊比如只说“操作MySQL数据库”模型可能会在同一个技能里既跑SELECT又跑DELETE这在生产环境是灾难。2.3 最小可跑的技能目录从零搭一个MySQL查询技能假设OpenClaw已经装好无论Docker还是Windows Hub方式技能默认目录一般在~/.openclaw/skills/。如果没有这个目录先手动建一个然后在里面建mysql_query子目录mkdir -p ~/.openclaw/skills/mysql_query cd ~/.openclaw/skills/mysql_query touch SKILL.md touch query.pyquery.py是真正的执行脚本用Python的mysql-connector-python库连接数据库。最小可跑版本如下import os import sys import json import mysql.connector def run(sql: str) - str: conn mysql.connector.connect( hostos.getenv(MYSQL_HOST, 127.0.0.1), portint(os.getenv(MYSQL_PORT, 3306)), useros.getenv(MYSQL_USER, root), passwordos.getenv(MYSQL_PASSWORD, ), databaseos.getenv(MYSQL_DATABASE, test), charsetutf8mb4 ) cursor conn.cursor(dictionaryTrue) try: cursor.execute(sql) rows cursor.fetchmany(100) return json.dumps(rows, ensure_asciiFalse, defaultstr) finally: cursor.close() conn.close() if __name__ __main__: # OpenClaw传入参数的格式通常是JSON字符串 args json.loads(sys.argv[1]) print(run(args[sql]))这段代码的逻辑不复杂从环境变量读连接信息允许脚本不硬编码数据库地址执行SQL后最多取100行转成JSON返回给OpenClaw。这里有两个参数要特别说明charsetutf8mb4是必须的否则中文会乱码fetchmany(100)是保护措施防止模型写出一条不带LIMIT的查询把结果集拉爆导致OpenClaw输出被截断后面避坑章节会细说。环境变量怎么注入如果OpenClaw跑在Docker里在docker-compose.yml里加environment段如果是本机裸装在启动OpenClaw的终端里export即可。还有一点mysql-connector-python需要预先装好用pip install mysql-connector-python就行。千万不要用默认的mysqlclient它在Windows上编译经常出问题这在Windows Hub安装OpenClaw的场景里是个隐藏坑。3. 把增删改查拆成四个独立技能从“模型自由发挥”到“模板驱动”3.1 为什么必须拆成独立技能而不是一个通用执行器有人会问一个mysql_query技能传任何SQL进去不就行了吗为什么还要拆因为OpenClaw的模型在自由生成SQL时翻车率远超想象——它可能忘掉WHERE条件直接UPDATE全表也可能把MySQL的IFNULL写成SQLite的IFNULL这个函数两边都有但它会写成IIF。把每个操作拆成独立技能本质是把“模型自由发挥”变成“模板驱动”。模型只负责填参数不负责造语句。拆法按操作类型分四个技能mysql_select、mysql_insert、mysql_update、mysql_delete。每个技能都有独立的SKILL.md和脚本这样模型在意图识别时就能根据用户说的是“查”还是“删”来精准触发。3.2 SELECT技能必须带WHERE禁止裸奔查询SELECT技能的脚本和上面的query.py几乎一样但SKILL.md里要强调几条铁律。这是我最常用的写法--- name: mysql_select description: 在MySQL数据库中执行SELECT查询返回JSON数组。适合查订单、用户、日志等只读场景。禁止执行INSERT/UPDATE/DELETE。 params: table: type: string description: 要查询的表名 columns: type: string description: 要查询的列多个列用英文逗号分隔默认 * condition: type: string description: WHERE条件必须提供不允许为空; 示例 id 1024 limit: type: integer description: 返回行数上限默认50最大200 ---脚本侧要把参数拼成SQL而不是让模型写整条SQL。这是我的做法def build_sql(args): table args[table] columns args.get(columns, *) condition args.get(condition, ) limit min(int(args.get(limit, 50)), 200) sql fSELECT {columns} FROM {table} if condition: sql f WHERE {condition} sql f LIMIT {limit} return sql这里的逻辑很关键查询列、条件、行数都是独立参数由模型填充最后在代码里拼装。好处是WHERE条件和LIMIT是代码强制加进去的模型哪怕忘了写最终执行时也不会全表扫描。这么做有一个副作用——模型填condition时可能带有单引号或分号存在注入隐患所以脚本里还要做一次简单过滤如果参数里含;或--直接拒绝执行。别嫌麻烦这是拿真实教训换来的。3.3 INSERT技能返回自增ID而不是“执行成功”INSERT技能和SELECT最大的区别在于返回值。用户问“加了一条记录”OpenClaw如果只回复“执行成功”用户无法确认数据真的进去了。所以INSERT脚本必须返回自增ID或影响行数。我一般这样处理import mysql.connector def run(table: str, data: dict) - str: conn mysql.connector.connect( hostos.getenv(MYSQL_HOST), useros.getenv(MYSQL_USER), passwordos.getenv(MYSQL_PASSWORD), databaseos.getenv(MYSQL_DATABASE) ) cursor conn.cursor() columns list(data.keys()) values list(data.values()) placeholders , .join([%s] * len(columns)) sql fINSERT INTO {table} ({, .join(columns)}) VALUES ({placeholders}) try: cursor.execute(sql, values) conn.commit() return fINSERT_OK last_insert_id{cursor.lastrowid} except Exception as e: conn.rollback() return fINSERT_FAIL: {str(e)} finally: cursor.close() conn.close()注意这里的%s占位符——这是MySQL Connector/Python的标准写法不是字符串格式化。千万不要用f-string把data直接拼进SQL否则字段值里带引号直接炸掉而且有注入风险。参数方面data是模型从用户话里抽出来的字典比如用户说“新增用户张三邮箱zhangsantest.com”模型就应生成{name: 张三, email: zhangsantest.com}。还有一个细节字段名没有走参数化。原因很简单MySQL的占位符只能占值不能占表名和列名。所以脚本里要加一个白名单校验从information_schema里查一下这个表真实存在的列只保留匹配的键其余全部丢弃。这样能防止模型乱填字段名导致SQL语法错误。3.4 UPDATE与DELETE技能必须带主键条件必须返回影响行数UPDATE和DELETE是高风险操作技能设计上要加双重保险。第一重是SKILL.md里强制要求带主键条件第二重是脚本里校验条件非空。SKILL.md里我会明确写--- name: mysql_delete description: 按主键ID删除MySQL记录。dangeroustrue执行前必须确认主键ID存在。 params: table: type: string description: 表名 id: type: integer description: 主键ID值必填 ---脚本侧的执行逻辑def run(table: str, id: int) - str: if not id: return DELETE_FAIL: 缺少主键ID conn mysql.connector.connect(...) cursor conn.cursor() sql fDELETE FROM {table} WHERE id %s try: cursor.execute(sql, (id,)) conn.commit() return fDELETE_OK affected_rows{cursor.rowcount} except Exception as e: conn.rollback() return fDELETE_FAIL: {str(e)}这里我只允许id作为条件不开放condition参数。原因很直白模型拼WHERE条件的能力不可靠哪怕它只是在条件里加了一个空格都可能导致全表删除。主键ID是明确值模型抽错的概率低得多。UPDATE技能同理强制id加一个fields字典只允许按主键更新指定字段。这样最坏情况也就是改错一条数据而不是“UPDATE users SET age 18”这种全校学生都变18岁的惨案。这里要提另外一个坑MySQL的rowcount只统计实际修改的行数。如果你UPDATE的值和原值一样MySQL会返回affected_rows0。用户会困惑“明明更新成功了为什么返回0行影响”。所以UPDATE技能里最好在返回信息里加上“值未变化也算执行成功”的说明别让模型把affected_rows0当成失败报给用户。4. 参数、权限与返回处理决定技能能不能进生产环境的三道门槛4.1 连接参数怎么传环境变量优先SSLMODE别乱开技能脚本里直接用os.getenv读环境变量这是最稳妥的方式。原因有两个一是技能文件可能被同步到git仓库硬编码密码等于裸奔二是不同环境本地测试、生产的连接信息本来就不一样环境变量可以在不修改技能代码的情况下切换。在MySQL连接串上有一个参数经常让人翻车ssl_mode。很多初学者看到MySQL报SSL相关错误就开ssl_modeDISABLED实际上在MySQL 8.0以上版本默认就走SSL。如果你连接时报错类似SSL connection error: SSL_CTX_set_tmp_dh_callback那多半是客户端版本和服务端加密套件不匹配正确做法是升级Connector/Python版本而不是一刀切关SSL。当然如果是纯内网测试环境关SSL也不是不行但别在生产环境这么做。连接池方面如果你的OpenClaw技能会被频繁调用每次新建连接的成本会拖慢响应。建议用mysql.connector.connect(pool_namemypool, pool_size5)开连接池。注意连接池模式下conn.close()不是真关闭是归还连接脚本退出前不会断开这是MySQL Connector/Python的正常行为不是内存泄漏。4.2 返回体大小OpenClaw输出截断问题的根源热搜词里有一条“OpenClaw在飞书输出容易被截断”排查下来根子往往不是OpenClaw而是技能返回的文本太长。SELECT技能如果查出200行、每行50个字段的JSON返回串轻轻松松上10KB模型再把这段JSON包装成自然语言回复输出长度直接爆掉。解决办法在技能侧不在OpenClaw配置侧脚本侧强制LIMIT默认20行最多50行从源头控制数据量返回前做字段裁剪只保留用户问到的列如果查询结果确实很大返回“查询成功共N条记录以下为前20条”的摘要而不是倒出全量数据。这三个措施按优先级执行。最简单的方式是在脚本末尾加一段裁剪逻辑我经常用json.dumps(rows[:20], ensure_asciiFalse)硬截断配合返回一个“truncated: true”的标志让模型知道结果不完整。4.3 数据库账号权限给OpenClaw一个“最小权限账号”不要用root这是一条血泪经验千万不要在技能里配置root账号。原因不是root会被盗而是root权限会让模型的错误SQL直接变成生产事故。比如模型写了一条DELETE FROM orders忘了WHERE如果用的是只读账号数据库直接拒绝执行如果用的是root数据就没了。正确做法是给OpenClaw单独建一个账号CREATE USER openclaw% IDENTIFIED BY strong_password_here; GRANT SELECT, INSERT, UPDATE, DELETE ON mydb.* TO openclaw%;细心的读者会发现这套权限组合已经覆盖增删改查。如果只想让OpenClaw做查询把GRANT语句改成只给SELECT就可以。另外%这个host是允许任意IP连接本机部署可以收紧为localhost。MySQL 8.0默认认证插件是caching_sha2_passwordConnector/Python 8.0以上版本支持没问题但如果遇到认证失败可以在创建账号时加IDENTIFIED WITH mysql_native_password BY ...兼容旧客户端——但这个写法从MySQL 9.0开始已经被移除新装环境不要再用。4.4 排序与分页让模型按用户意图正确排序用户说“查最近10条订单”很多模型会直接SELECT * FROM orders LIMIT 10结果返回的是最早的10条。这不算错但不符合用户意图。所以技能参数里要加一个order_by字段并在SKILL.md里强调“用户提到最新/最近时默认按时间字段DESC排序”。order_by的处理同样要过白名单校验不能直接把模型给的字符串拼进SQL。我一般维护一个映射表ALLOWED_ORDERS { latest: created_at DESC, oldest: created_at ASC, price_desc: price DESC, price_asc: price ASC } order_sql ALLOWED_ORDERS.get(args.get(order_by, latest), created_at DESC)这样模型只能从四个预设排序里选不能生成ORDER BY (SELECT ...)之类的花活。排序是增删改查面试题里的高频考点但在OpenClaw技能里它不是一个SQL技巧问题而是一个安全边界问题。5. 避坑OpenClaw操作MySQL最常见的5个故障及解法5.1 报错agent failed before reply: session file locked (timeout 60000ms)现象OpenClaw在Windows Hub或Docker环境下执行技能后Agent迟迟不回复最终报这个错。原因不是技能脚本的问题是OpenClaw的会话文件被锁住了。常见情况是两个Agent进程同时在写同一个session文件或者上一次任务还没结束又发了新任务。解决先确认是否重复启动了OpenClaw服务单实例运行情况下等60秒超时后重试如果频繁出现检查session目录是否有残留的.lock文件删掉后重启OpenClaw。这个报错和MySQL本身无关但容易让新手误判为“数据库连接失败”。我见过有人因为这个报错重装了MySQL结果白折腾。判断要点是看日志如果技能脚本真的执行失败了日志里会有Python报错堆栈如果只有session locked说明脚本压根没被调用。5.2 MySQL报ERROR 2002 (HY000): Cant connect to local MySQL server through socket /tmp/mysql.sock现象技能脚本执行时报这个错但命令行里用mysql -u root -p能正常登录。原因Python连接时用了默认的socket方式而连接串里没指定host或者host写的是localhost。MySQL Connector/Python在host为localhost时会优先走Unix socket而不是TCP/IP。解决把host改成127.0.0.1强制走TCP或者指定socket路径。本地部署用TCP没什么不好但注意MySQL 8.0默认不监听TCP的某些发行版配置需要检查my.cnf里的skip-networking是否为0。5.3 INSERT时中文乱码表里全是“????”现象技能返回“执行成功”但MySQL里中文变成了问号。原因连接字符串没指定字符集服务端和客户端的字符集不一致。解决在连接参数里加charsetutf8mb4同时确认表本身的字符集是utf8mb4而不是utf8。MySQL的utf8不是真正的UTF-8它存不了emoji和部分生僻字utf8mb4才是完整实现。如果是老库已经建成了utf8执行ALTER TABLE mytable CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;可以转换但大表会锁表生产环境要挑维护窗口执行。5.4 数据库连接池连接耗尽技能越用越慢直至超时现象OpenClaw跑了一段时间后所有涉及MySQL的技能都变慢最后报连接数超标。原因连接池的pool_size设置得太大或者连接池里的连接没有正确归还。Connector/Python的连接池默认5个连接如果技能脚本里每次执行都新建连接池而不是复用同一个池连接数会翻倍增长。解决把连接池做成模块级单例不要放在函数里创建另外在连接参数里加pool_reset_sessionTrue确保连接归还时清理临时状态。排查时用SHOW PROCESSLIST;看看当前有多少个 Sleep 状态的连接如果远大于pool_size就是连接泄漏了。5.5 从远程库同步一张表到本地时间字段的时区问题现象用户要求“把远程库的这张表同步到本地”技能脚本用mysqldump导出再mysql导入结果表里时间字段全部偏移了8小时。原因MySQL的TIMESTAMP类型存储的是UTC值展示时按会话时区转换。mysqldump导出的SQL文件里带SET TIME_ZONE00:00导入时本地库会话时区不同导致读出来偏移。解决同步脚本里在执行导入前先执行SET time_zone 08:00;或者统一用DATETIME类型存储时间字段。DATETIME不带时区信息存什么就是什么跨库同步时不会偏移。这个坑在数据同步场景里几乎必踩OpenClaw技能里如果做了Routine类型的同步任务一定要在脚本里显式设置会话时区。6. 验证方法与进阶用法把“能跑”变成“敢用”写完技能后不要急着丢给OpenClaw去调用先做一轮手工验证。我的验证三板斧是先直接用命令行执行脚本确认SQL和连接没问题再写测试SQL模拟模型可能生成的参数确认边界情况不会炸最后才接入OpenClaw跑真实对话。第一板斧的命令是python query.py {table: users, condition: id 1, limit: 5}如果这个命令能返回JSON说明技能本身没问题。接下来测试模型的“坏习惯”——比如不给condition直接查表脚本应该拒绝或强制加上保护性limit传id1; DROP TABLE users这种注入串脚本应该直接报非法参数。这两条过了技能才算基本可信。安全验证过后还有一个值得做的进阶用法把多个技能串成Routine。比如“对订单表做每日健康检查”这个任务可以拆成三步先用mysql_select查当天订单量再用mysql_insert把统计结果写入监控表最后用mysql_update更新状态标记。OpenClaw支持在一个任务里连续调用多个技能只要每个技能的SKILL.md写得足够清晰模型能自己编排调用顺序。我不建议一上来就做这种复合技能先把单个技能跑稳再考虑组合。关于OpenClaw接入外部渠道的注意事项如果你把技能暴露给飞书或Microsoft Teams的机器人使用务必在机器人侧加权限控制——不是所有对话者都有权执行DELETE技能。我见到的做法是在技能脚本里校验调用者身份从OpenClaw传入的上下文中提取用户ID只有白名单内的人才允许执行危险操作。这个校验不用做得很复杂一个环境变量加一个判断就够。最后收个尾。我踩过最深的坑是贪多求全一开始就写了十几个技能结果每个技能都只测过“能跑”没测过“边界”。后来改成先做两个技能——一个SELECT、一个DELETE——把权限、返回截断、会话锁这几个问题全部摸透再批量扩展。技能不在于多在于每个都敢在生产环境点执行。希望这篇笔记能帮你把OpenClaw的MySQL技能从“能跑”推到“敢用”少走几趟我走过的弯路。本文还有配套的精品资源点击获取