OpenClaw技能实战：用Skill封装MySQL增删改查的完整方法

简介面向OpenClaw技能开发者这份压缩包给出了一套基于Python实现MySQL数据库增删改查CRUD的自定义技能方案适用于需要在智能体框架中快速接入数据存储与查询能力的项目场景。包体非常精简共3个文件以Python脚本为主辅以Markdown技能说明和HTML演示页面整体大小仅3KB便于直接阅读和二次修改。内容围绕数据库连接配置、参数化查询、异常处理与安全防护展开覆盖了插入、查询、更新、删除四类基本操作的封装思路同时对事务处理、批量操作等高级扩展方向作了铺垫可帮助开发者快速掌握OpenClaw技能模板的用法。目前已有164人学习下载对正在规划数据库类技能或寻求轻量参考实现的开发者来说是一份实用且低门槛的入门资料。1. OpenClaw技能模块是什么为什么把数据库操作做成技能而不是写死脚本先说结论OpenClaw里的“技能”Skill本质上是给Agent预置的一组能力描述和可执行代码让大模型在对话中按需调用。而把MySQL的增删改查封装成技能最大的价值不是省几行SQL而是让Agent在收到自然语言指令时能自主决定“该不该碰数据库、该执行哪条SQL、执行完怎么回话”。如果你只是写一个Python脚本去连MySQL那叫自动化做成技能才叫Agent。这篇文章适合两种人一是刚把OpenClaw部署起来、想让Agent真正干点活的新手二是已经在用OpenClaw但觉得Agent只会聊天、想给它接上业务系统的开发者。我会从技能文件的组织方式讲起给出可直接落地的MySQL增删改查技能包再把权限控制、事务、安全这些容易翻车的地方单独拎出来讲。先把我自己的使用习惯放前面我一般把数据库技能拆成两个文件——一个SKILL.md告诉模型“你能干什么、该怎么组织SQL”一个execute.py负责真正连库和执行。模型只负责生成SQL和参数Python端负责校验和兜底。这个分工后面会反复提到它是整个方案不出乱子的关键。2. OpenClaw技能机制与MySQL连接选型先搞清楚技能是怎么被调起来的2.1 OpenClaw技能的文件组织与触发逻辑OpenClaw的技能目录有固定结构。一个技能就是一个文件夹里面必须有SKILL.md通常会配一个或多个可执行脚本。SKILL.md不是给人看的文档而是给模型看的“使用说明书”——模型在对话中看到用户需求时会根据这个文件的内容判断是否调用技能。我常用的技能目录结构是这样的skills/ └── mysql_crud/ ├── SKILL.md ├── execute.py ├── config.json └── requirements.txtSKILL.md里面写清楚这个技能的名字、功能描述、参数格式、调用条件和注意事项。模型读到“FetchMySQLData”这样的名字和描述后如果用户说“查一下用户表里最近注册的10个人”它就会尝试调用这个技能并把解析出的参数传给execute.py。这里有个关键点SKILL.md的描述写得越具体模型调用越准确。你写“可以查数据库”模型不知道什么时候该用你写“当用户需要查询MySQL中的业务数据时使用此技能参数包括sql语句和数据库标识”模型就知道在什么场景下激活它。2.2 为什么选PyMySQL而不是其他连接库OpenClaw的技能脚本通常用Python写因为生态成熟、模型生成代码的成功率高。连接MySQL的Python库主要有三个选择MySQLdb、mysql-connector-python、PyMySQL。MySQLdb是古早方案Python3下安装麻烦很多环境没有预编译包。mysql-connector-python是官方驱动功能全但依赖较重。我一般选PyMySQL原因有三个纯Python实现pip安装无坑API和MySQLdb几乎一致迁移成本低在OpenClaw这种需要快速部署的技能场景下它的错误信息更直观模型调试时不容易懵。安装就一条命令pip install pymysql需要注意的是如果你在OpenClaw的Docker容器里跑记得把pymysql装进容器镜像或者挂在启动脚本里否则技能运行时找不到依赖。这个坑我踩过不止一次症状是技能第一次调用报ModuleNotFoundError重启之后又好了其实是容器重建后依赖没装。2.3 技能参数设计让模型知道该传什么execute.py要接收模型传来的参数。OpenClaw的技能调用通常通过JSON传参所以我在脚本里固定解析几个字段sql必填、db_config_key选填指定用哪套连接配置、params选填SQL参数化查询用的。#!/usr/bin/env python3 MySQL增删改查技能执行入口 import json import sys import pymysql from pymysql.cursors import DictCursor def load_config(config_keydefault): # 实际项目中应从配置文件或环境变量读取 configs { default: { host: 127.0.0.1, port: 3306, user: app_user, password: your_password, database: app_db, charset: utf8mb4 } } return configs.get(config_key, configs[default]) def execute_sql(sql, paramsNone, config_keydefault): cfg load_config(config_key) connection pymysql.connect( hostcfg[host], portcfg[port], usercfg[user], passwordcfg[password], databasecfg[database], charsetcfg[charset], cursorclassDictCursor, autocommitFalse ) try: with connection.cursor() as cursor: cursor.execute(sql, params) # 只有查询语句才需要fetch结果 if sql.strip().lower().startswith(select): result cursor.fetchall() return {success: True, rows: result, row_count: len(result)} else: connection.commit() return {success: True, affected_rows: cursor.rowcount} except Exception as e: connection.rollback() return {success: False, error: str(e)} finally: connection.close() def main(): # 从stdin接收OpenClaw传入的JSON参数 try: raw_input sys.stdin.read() payload json.loads(raw_input) if raw_input.strip() else {} sql payload.get(sql) if not sql: print(json.dumps({success: False, error: sql参数不能为空})) return params payload.get(params) config_key payload.get(db_config_key, default) result execute_sql(sql, params, config_key) print(json.dumps(result, ensure_asciiFalse, defaultstr)) except Exception as e: print(json.dumps({success: False, error: f技能执行异常: {str(e)}})) if __name__ __main__: main()这一段代码里有几个设计是刻意的。第一select和其他语句分开处理查询走fetchall写操作走commit避免模型让Agent执行INSERT后拿不到影响行数。第二autocommit设为False自己控制事务这样出错了能回滚。第三所有返回都走JSON模型解析结果时不用猜格式。你可能会问为什么不直接在SQL里写死表名和字段因为那就失去技能的意义了。技能应该接受模型生成的SQL而不是只执行预设语句。但这里有一个安全边界你可以在execute.py里加一个校验函数只允许SELECT/INSERT/UPDATE/DELETE开头拦截DROP、TRUNCATE这类危险操作。我后面在避坑章节会专门说。3. 用OpenClaw技能实现对MySQL的增删改查从SKILL.md到真实调用3.1 编写SKILL.md让模型知道何时调用、怎么传参SKILL.md是整个技能的大脑。模型不会读你的Python代码它只读这个文件。所以里面要写清楚技能叫什么、在什么场景下触发、需要哪些参数、参数是什么格式、有什么注意事项。--- name: mysql_crud description: 当用户需要查询、插入、更新或删除MySQL数据库中的数据时使用。包括但不限于查询用户信息、修改订单状态、删除过期记录、新增业务数据等场景。 version: 1.0.0 parameters: sql: type: string description: 要执行的SQL语句。只允许SELECT、INSERT、UPDATE、DELETE开头的语句。 required: true db_config_key: type: string description: 数据库配置标识默认使用default配置 required: false params: type: array description: SQL参数化查询的参数列表按顺序对应SQL中的%s占位符 required: false --- # MySQL增删改查技能 ## 功能说明 本技能允许Agent对MySQL数据库执行增删改查操作。 ## 调用规则 - 当用户请求涉及数据库操作时优先使用本技能 - 用户用自然语言描述需求时将需求转换为SQL语句 - 查询请求默认加LIMIT限制最多返回100条记录防止结果过大 - UPDATE和DELETE语句必须带有WHERE条件禁止无条件更新或删除 ## 参数说明 - sql参数为必填其他参数可选 - 参数化查询时params列表中的值按顺序对应SQL中的%s占位符 ## 注意事项 - 禁止执行DDL语句如DROP、TRUNCATE、ALTER - 禁止执行多语句拼接一次只执行一条SQL - 查询结果会以JSON格式返回给模型这里有一个很实用的写法在调用规则里写“UPDATE和DELETE必须带WHERE条件”模型在生成SQL时就会主动加上条件。这不是代码强制的而是靠提示约束模型行为。代码里也应该做一道校验双保险但提示的作用别低估——大模型真的会照做。3.2 最小可复现的调用流程用命令行模拟OpenClaw调起技能在接入OpenClaw之前建议先用命令行把你的execute.py跑通。方式很简单把OpenClaw要传的JSON通过stdin喂给脚本echo {sql: SELECT id, username, created_at FROM users ORDER BY created_at DESC LIMIT 5, db_config_key: default} | python3 execute.py正常输出是这样{success: true, rows: [{id: 1, username: alice, created_at: 2025-01-10 10:00:00}], row_count: 1}这一步的意义是先把Python端调通。如果这一步就报错说明问题在数据库连接或SQL本身不要急着去OpenClaw里排查。接OpenClaw时我在配置文件的tools或skills部分注册这个技能指定名称、执行命令和参数格式。OpenClaw会把模型解析出来的参数以JSON形式传给技能脚本脚本执行后把结果返回给模型模型再组织自然语言回复给用户。3.3 增删改查四个操作的实际用法与SQL生成策略分别看四种操作在技能框架下是怎么工作的。查询操作最常见。模型收到“查一下最近一周注册的用户”后生成SQL并调用技能。我在SKILL.md里要求模型默认加LIMIT防止全表扫描SELECT id, username, email, created_at FROM users WHERE created_at DATE_SUB(NOW(), INTERVAL 7 DAY) ORDER BY created_at DESC LIMIT 50插入操作要特别注意返回自增ID。模型执行INSERT后Agent需要知道新记录的ID才能继续对话。我在execute.py里可以在INSERT语句后取cursor.lastrowid# 在execute_sql函数的INSERT分支中增加 if sql.strip().lower().startswith(insert): connection.commit() new_id cursor.lastrowid return {success: True, affected_rows: cursor.rowcount, insert_id: new_id}更新操作的核心是WHERE条件。模型如果生成UPDATE users SET status active WHERE id 5没问题如果生成UPDATE users SET status active不带WHERE就必须拦截。这个拦截逻辑写在execute.py里import re def validate_sql(sql): 校验SQL安全性只允许增删改查必须带WHERE stripped sql.strip().lower() allowed_prefixes (select, insert, update, delete) if not stripped.startswith(allowed_prefixes): return False, 只允许执行增删改查操作 # 对UPDATE和DELETE强制要求WHERE if stripped.startswith((update, delete)): if where not in stripped: return False, UPDATE和DELETE语句必须包含WHERE条件 return True, 删除操作同理。DELETE FROM users WHERE id 1可以执行DELETE FROM users直接拦下来。这不算过度设计生产环境里这是保命的一环。3.4 config.json与多环境配置开发库、测试库、生产库怎么隔离OpenClaw技能如果只配一个数据库开发调试时还好一上生产就麻烦了。模型只要说“查一下订单表”就可能查到生产数据。我的做法是在config.json里定义多套连接配置并明确告诉模型默认用哪套。{ environments: { dev: { host: 127.0.0.1, port: 3306, user: dev_user, password: dev_password, database: dev_db }, prod: { host: 10.0.0.5, port: 3306, user: readonly_user, password: prod_password, database: prod_db } }, default_environment: dev }然后在SKILL.md里写清楚默认使用dev环境如果用户明确要求生产数据才允许切换到prod环境且prod环境的用户只有只读权限。这样即使模型误操作也不会把生产库改坏。数据库账号权限要和技能脚本的校验逻辑配合——脚本校验是第一道门MySQL账号权限是最后一道门。4. 把OpenClaw技能接到实际数据库建表、授权、联调与常见报错4.1 前置工作建库建表、创建专用账号、最小权限授权不建议用root账号给OpenClaw用。我给OpenClaw单独建一个账号只授予必要权限。以MySQL 8.0为例-- 创建专用账号和最小权限 CREATE USER IF NOT EXISTS openclaw_app% IDENTIFIED BY StrongPassword_2025; GRANT SELECT, INSERT, UPDATE, DELETE ON app_db.* TO openclaw_app%; FLUSH PRIVILEGES;注意这里只给了增删改查权限没有DDL权限。这样即使技能被提示词注入诱导执行DROP TABLEMySQL也会因为权限不足直接拒绝。表结构方面业务系统里的表用现有表就行。做测试的话我建一张简单的用户表CREATE TABLE IF NOT EXISTS users ( id INT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(50) NOT NULL UNIQUE, email VARCHAR(100), status TINYINT NOT NULL DEFAULT 1, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;4.2 在OpenClaw中注册技能配置文件与权限开关OpenClaw的技能注册方式取决于你的部署版本。常见的方式是在配置文件中声明技能路径和启用状态。我在配置里这样写skills: mysql_crud: enabled: true path: ./skills/mysql_crud execute_command: python3 execute.py timeout_seconds: 30如果你在Windows上装了OpenClaw的Windows Hub版本路径写法会有差异。社区里常见的报错是Windows下Python路径不是python3而是python或者执行权限不够。我的建议是先在命令行手动执行一次完整调用再把命令填进配置文件不要在配置里猜命令。4.3 联调时的常见报错与排查链路联调阶段最常碰到的报错我按“现象→原因→解决”的格式列在避坑章节里这里先说一个最磨人的连接超时。如果你看到这样的报错TimeoutError: [Errno 110] Connection timed out通常是OpenClaw跑在Docker容器里而MySQL跑在宿主机上容器内连接宿主机不能写127.0.0.1要写宿主机的内网IP或docker0网桥IP。解决方法是把config.json里的host改成宿主机IP或者在docker run时加--networkhost。另一个高频报错是关于SSL的。MySQL 8.0默认开启SSL要求PyMySQL连接时如果不配置会报pymysql.err.OperationalError: (2026, SSL connection error: unknown error number)解决方式是连接参数里加ssl_disabledTrue或者在MySQL端关闭该账号的SSL要求ALTER USER openclaw_app% IDENTIFIED WITH mysql_native_password BY StrongPassword_2025; ALTER USER openclaw_app% REQUIRE SSL;我的建议是在PyMySQL里显式处理SSL而不是去改MySQL端的安全策略connection pymysql.connect( ..., ssl_disabledTrue if not need_ssl else False )4.4 会话锁问题session file locked 的触发条件与规避热词里出现过一个很具体的报错agent failed before reply: session file locked (timeout 60000ms)。这不是MySQL技能的问题而是OpenClaw自身会话文件被锁导致的——通常发生在多个并发会话同时写同一个session文件时。规避办法有三个一是不要在多个终端窗口同时操作同一个会话ID二是检查OpenClaw的工作目录是否有写权限Windows下尤其容易出现目录权限不足三是如果你通过API并发调用OpenClaw每个请求要用独立的session_id。这个报错和MySQL技能配合出现时容易被误判为数据库连接问题实际上数据库压根没被调用到。排查方法很简单看日志。当MySQL技能报这个错时先确认execute.py有没有被调用。如果日志里只有session file locked没有你的Python脚本的日志输出那就不是数据库的问题是OpenClaw进程层面的问题。5. 增删改查技能的五个必踩的坑权限、事务、字符集与超时5.1 UPDATE和DELETE不带WHERE条件直接全表遭殃现象模型生成UPDATE users SET status 0execute.py直接执行全表状态被改。评论区的血泪经验几乎都是从这里开始的。原因模型根据用户指令生成SQL时如果用户说“把所有用户都设置为禁用”模型会生成不带WHERE的UPDATE。这在业务语义上可能没问题但大多数情况下用户本意不是全表更新。解决execute.py里加校验UPDATE和DELETE必须包含WHERE关键字。更严一点可以要求WHERE后面不能是恒真条件比如WHERE 11。你可以做一个简单的正则检查也可以用sqlparse库解析AST但最简单的做法是脚本层校验 MySQL账号只读权限兜底两层叠加等闲不会出事。5.2 字符集乱码utf8和utf8mb4的区别导致中文变问号现象INSERT中文数据成功SELECT出来是???或者乱码。原因MySQL的utf8是utf8mb3存不了emoji和不常见汉字。OpenClaw生成的SQL里含中文时连接字符集不对就会踩这个坑。解决建库时指定CHARACTER SET utf8mb4PyMySQL连接参数里也设置charsetutf8mb4。这两处都配上基本不会再出乱码。如果你发现表已经建成utf8了可以执行ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;5.3 事务只提交不感知多条INSERT中途失败导致数据不一致现象一次对话让Agent插入10条订单记录第5条数据格式不对execute.py报错。回数据库一看前4条已经写进去了。原因技能脚本里如果commit太早或者没有用事务包住整批操作就会出现部分成功。解决把execute.py的设计改成默认不自动提交批量操作全部成功后再统一commit。我在前面代码里已经写了autocommitFalse关键是INSERT分支里不要在循环中commit。最好让脚本只接收一条SQL多条操作由模型分多次调用技能。不要允许一次调用执行多语句的SQLMySQLdb默认也不让你用分号拼接多个语句。5.4 连接超时与连接池缺失长会话运行中MySQL连接被Kill现象OpenClaw会话挂了一会儿再问数据库报MySQL server has gone away。原因MySQL的wait_timeout默认8小时但你如果设了更短或者数据库重启了连接就断了。openclaw会话闲置时间较长时这种断连很常见。解决常见的做法是把连接放在with语句里用完就关。不要尝试手动保持长连接。每次调用都新建连接性能损失在内部场景下可以接受换来的是省心。如果调用频率高到每秒几十次再考虑连接池方案用DBUtils或SQLAlchemy的PooledDB。5.5 模型把数据库密码当答案回复给用户现象用户问“你知道数据库的配置吗”模型把config.json里的密码原样输出。原因模型能读到技能文件内容如果你的配置文件里写了明文密码模型可能把它当作可公开信息。解决密码放在环境变量或OpenClaw的secrets机制里config.json里只写占位符。同时技术在SKILL.md里加一条“数据库连接信息属于敏感信息禁止向用户透露”。这属于提示层约束不是绝对安全但配合环境变量方案能让敏感信息不出现在模型可读范围里。6. 让技能更可靠SQL白名单、日志追踪与批量操作的进阶姿势前面把增删改查跑通了这一章讲怎么把技能从“能用”变成“好用”。三个方向SQL安全校验从简单拦截升级为解析级检查操作日志完整记录出错能追溯批量操作的处理策略。SQL安全校验的升级方案我推荐加一个词法检查。简单拦截只是查前缀和WHERE关键字但SELECT * FROM users; DROP TABLE users这类通过分号拼接的注入就拦不住。一句话不支持多语句执行# 在连接参数中加client_flag import pymysql from pymysql.constants import CLIENT connection pymysql.connect( ..., client_flagCLIENT.MULTI_STATEMENTS # 这个默认不开 )PyMySQL默认不允许一次执行多条语句所以分号拼接的问题天然被挡了一部分。我建议你不要主动开启MULTI_STATEMENTS让这条天然防线保持生效。日志记录是排障的命根子。我在execute.py里加了一段很简单的记录逻辑import logging logging.basicConfig( filename/var/log/openclaw/mysql_crud.log, levellogging.INFO, format%(asctime)s %(levelname)s: %(message)s ) def execute_sql(sql, paramsNone, config_keydefault): logging.info(f执行SQL: {sql}, 参数: {params}, 环境: {config_key}) result ... if result.get(success): logging.info(f执行成功, 影响行数: {result.get(affected_rows, result.get(row_count, 0))}) else: logging.error(f执行失败: {result.get(error)}) return result日志至少解决三个问题模型生成的SQL到底是什么——你可以在日志里看到原始SQL判断模型是不是生成了奇怪的东西报错时能区分是数据库问题还是OpenClaw调用问题审计时能追踪谁在什么时间对数据做了什么操作。批量操作的策略我的建议是拆成多次技能调用。比如用户要求“把100条用户数据的状态改为vip”模型可以生成一条UPDATE带IN子句也可以生成100条UPDATE。前者SQL很长后者调用很慢。实际做法是让模型生成一条UPDATE用IN子句包住ID列表UPDATE users SET status 2 WHERE id IN (1, 2, 3, ...)如果ID列表实在太大超出一个SQL的上限可以按每500个ID拆成多个SQL。但无论怎么拆每次execute.py的调用只执行一条SQL保持事务幂等。你要在SKILL.md里把这个规则写清楚让模型遵守。最后说一个进阶技巧在execute.py里支持read-only模式和write模式的切换。如果用户只是做查询可以用只读数据库账号只有当用户明确执行INSERT/UPDATE/DELETE时才切换到有写权限的账号。这样可以把误操作的风险进一步压低。实现也不复杂在choose_config函数里根据SQL前缀选择环境即可。我的习惯是默认全走只读账号遇到写操作再提示用户确认。这套逻辑跑顺之后OpenClaw在内部工具场景里真的可以当一个能听懂人话的数据运维来用。写到这里想提一句配置层面的经验之前被坑过OpenClaw调Windows Hub、OpenClaw部署时经常会把技能注册到默认目录之外导致技能找不到。我的做法是先ls一下技能目录确认挂载再去调技能。这些习惯养成了后面就很少翻车。希望帮到你。本文还有配套的精品资源点击获取