简介数据库操作的安全边界是 AI Agent 落地产出的核心挑战。当智能体需要直接访问 MySQL 时简单让模型拼接 SQL 会放大注入与误操作风险。通过参数化查询、字段白名单、强制条件校验等基础工程手段可以在原理上约束 AI 的行为将不确定性控制在允许范围内。OpenClaw 的 Skill 机制把这类能力封装成命名的工具接口让开发者以本地脚本的形式安全暴露增删改查同时保留清晰的权限边界与可审计日志。该模式适合面向 AI 的数据库服务集成、企业内部数据助手等场景也可为其他智能体框架提供设计参考。本文围绕 OpenClaw 与 MySQL 的实战过程展示如何构建一个安全可控的数据库操作技能。 最近在给 OpenClaw 做技能扩展正好需要让智能体能直接读写 MySQL。说实话刚开始我觉得这事儿很简单不就是让 AI 自己写 SQL 去执行吗结果真做起来才发现如果不管控“AI 写 SQL 直连数据库”这个组合在真实业务里跟裸奔没什么区别。所以我把整套能力封装成了标准 Skill让 OpenClaw 在受控范围内完成增删改查。这篇文章就是把整个过程完整复盘一次包括 Skill 怎么设计、代码怎么写、哪些坑必须躲希望能帮你少走弯路。如果你是刚接触 OpenClaw 的新手或者已经在用 OpenClaw 但一直没敢碰数据库操作这篇文章应该正好卡在你的需求点上。我会从环境部署讲到 Skill 实现再讲到真实调用场景尽量把每个决策背后的原因也交代清楚。1. 项目概述与整体设计思路1.1 动手之前先想清楚 Skill 做数据库操作的边界先说结论OpenClaw 接入 MySQL 最合理的姿势不是让 AI 自由发挥生成 SQL而是把数据库操作封装成有限集合的 SkillAI 只负责“按需调用”和“传参数”。为什么这么设计你想象一下如果让 AI 直接生成 SQL 丢给生产库执行它会遇到三类问题。第一AI 对表结构不熟悉很容易生成不存在的字段名报错后它会自作聪明地换一种写法然后继续报错这个循环非常难受。第二SQL 注入风险没法完全消除AI 生成的字符串条件拼接正好是注入攻击最爱的入口。第三不可控你不知道它下一秒会执行一条DELETE FROM不带 WHERE还是DROP TABLE。所以我定的边界是Skill 里只暴露确定的表、确定的字段、确定的操作类型AI 只能在这个框架里面传值。它可以说“查一下用户表里最近注册的 10 个人”但没办法让它“删库跑路”——因为在 Skill 代码层就没开放这种能力。这套思路本质上和你在后端接口层做参数白名单是一个道理。1.2 为什么选 OpenClaw 做这个事你可能也看到过 Coze、Dify、Workbuddy 这一堆智能体平台它们都能接数据库为什么我在这个项目里选了 OpenClaw核心原因是 OpenClaw 的 Skill 机制更接近“本地代码扩展”。你在 OpenClaw 里写一个 Skill本质上就是把一段 Python 或 Shell 脚本挂到 AI 的调用链上脚本跑在你自己控制的环境里不走云端的黑盒网关。这意味着你可以直接使用 pymysql、直接读取本地配置文件、直接连内网数据库不需要绕一圈 HTTP 接口。另一个原因是它的调试链路短。Coze 那边接数据库很多时候你得先做一个自定义插件再把插件发布成 API 服务链路长、排错麻烦。OpenClaw 这边Skill 脚本可以直接在终端跑通再挂载到对话里验证两步就能完成闭环特别适合我这种喜欢先本地跑通再集成的人。1.3 整体链路设计先看一条完整的调用链用户自然语言 - OpenClaw 模型解析意图 - 匹配到 mysql_crud Skill - 生成参数 JSON - 调用 Python 脚本 - pymysql 执行 SQL - 结果写回 stdout - OpenClaw 转成自然语言回复这个链路里真正的 MySQL 操作发生在 Python 脚本内部AI 模型只负责两件事判断“该用哪个操作”以及“该传什么参数”。这两件事恰好是模型最擅长的而 SQL 生成和执行细节则完全由脚本来掌控。我在项目里把 Skill 拆成了两个维度操作类型和参数校验。操作类型固定为 select、insert、update、delete 四种参数里再区分表名、条件、字段值等。这样既保证灵活性又不至于失控。后面我会详细展开代码实现你先记住这个链路后面所有实操都是围绕它展开的。2. 环境准备把 OpenClaw 和 MySQL 都跑起来2.1 OpenClaw 部署不同平台的注意事项OpenClaw 的部署不是这篇文章的重点但既然要让 Skill 真正跑起来环境这关必须过。我基于常见实践给你捋一下关键点详细步骤还是以官方文档为准。Windows 上部署最容易踩的坑是 Python 环境变量没配好。OpenClaw 依赖 Python 3.10 以上版本装完后你在 CMD 里执行python --version如果提示“不是内部或外部命令”说明没把 Python 加入 PATH。这种情况不用重装去“系统属性 - 环境变量 - Path”里手动加上 Python 安装目录就行。Linux 和 macOS 上部署相对顺滑但要注意权限问题。我见过不少人在 Ubuntu 上直接sudo pip install openclaw结果装到了系统 Python 目录后面跑 Skill 时因为权限不足报错。建议用一个独立的 Python 虚拟环境或者用pip install --user安装避免动系统级依赖。还有一个通用提醒OpenClaw 部署完以后先跑一下官方自带的示例 Skill 做冒烟测试。如果连示例都跑不通问题大概率出在环境本身而不是你的 Skill 代码。别急着写自己的 Skill先把基础链路打通后面排查范围会小很多。2.2 MySQL 安装的版本选择以及必须做的两个配置MySQL 的安装方式各平台差异很大但版本选择有一个原则生产环境尽量用 5.7 或 8.0 的 LTS 版本别追最新大版本。8.0 和 5.7 在增删改查层面几乎没有区别但在认证插件上差别很大。8.0 默认用的caching_sha2_password某些老版本的 Python 库不认识这个认证方式连接时会直接报错。如果你用的是 pymysql 且版本较旧连接 8.0 很可能遇到这个问题。我的建议是如果是新项目直接用 MySQL 8.0然后把 pymysql 升级到 1.x 最新版生态兼容性最好。安装完成后有两件事必须做属于那种“不做一定后悔”的配置。第一件事确认监听地址。默认情况下 MySQL 只监听 127.0.0.1如果你的 OpenClaw 跑在另一台机器上需要在my.cnf或my.ini里把bind-address改为0.0.0.0然后在防火墙里放行 3306 端口。这里我建议你谨慎一点如果 OpenClaw 和 MySQL 在同一台机器上保持默认 127.0.0.1 就是最安全的。第二件事单独建一个业务账号别用 root 连接。我在项目里新建了一个叫openclaw的账号只授予项目所需数据库的增删改查权限。这样即使 Skill 脚本被注入或误操作影响范围也被限制在单库级别不会波及整个 MySQL 实例。2.3 准备一张练习用的表结构在写 Skill 代码之前先把数据库和表准备好。我用一个最典型的用户表来做演示字段不多但覆盖了增删改查的所有场景。CREATE DATABASE IF NOT EXISTS openclaw_demo DEFAULT CHARACTER SET utf8mb4; USE openclaw_demo; CREATE TABLE IF NOT EXISTS user_info ( id INT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(64) NOT NULL UNIQUE, nickname VARCHAR(64) DEFAULT , email VARCHAR(128) DEFAULT , status TINYINT DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里有几个细节值得说明。第一为什么所有字符类型都带长度因为 varchar 的长度直接影响索引和存储开销64 和 128 对用户名字段来说已经够用别随手写个 255。第二status字段用 TINYINT 而不是 VARCHAR因为状态这种枚举型数据用数字存更省空间也方便扩展。第三created_at给了默认值这样 insert 的时候可以不传这个字段减少参数复杂度。3. Skill 的实现核心代码与关键细节3.1 Skill 目录结构和清单文件怎么定义OpenClaw 的 Skill 通常是一个独立目录里面至少包含一个描述文件和一个可执行脚本。描述文件的作用是让模型知道“这个技能是干什么的、什么时候该调用它、需要传什么参数”我用的是 YAML 格式这是社区里比较通用的做法。name: mysql_crud description: 对 MySQL 数据库执行增删改查操作支持 select、insert、update、delete 四种操作。 version: 1.0.0 parameters: - name: operation type: string required: true description: 操作类型枚举值 select、insert、update、delete - name: table type: string required: true description: 目标数据表名 - name: conditions type: object required: false description: 条件字段映射例如 {id: 1} - name: data type: object required: false description: 写入或更新的字段映射例如 {username: tom, status: 1}写 description 的时候有个技巧要写清楚“什么时候用”而不是只写“能干什么”。比如“当用户需要查询、新增、修改或删除数据库记录时使用”比“MySQL 增删改查”更容易触发。模型是靠描述来匹配意图的描述越贴近真实会话场景命中率越高。3.2 数据库连接封装别在每次调用里重复建连Skill 脚本虽然是“一次调用一次进程”但连接这块还是值得封装一下。我在脚本里单独抽了一个get_connection函数统一管理连接参数。#!/usr/bin/env python3 import os import sys import json import pymysql DB_CONFIG { host: os.getenv(MYSQL_HOST, 127.0.0.1), port: int(os.getenv(MYSQL_PORT, 3306)), user: os.getenv(MYSQL_USER, openclaw), password: os.getenv(MYSQL_PASSWORD, ), database: os.getenv(MYSQL_DATABASE, openclaw_demo), charset: utf8mb4, cursorclass: pymysql.cursors.DictCursor, }可能有人会问为什么不直接在脚本里硬编码账号密码答案很简单不安全。Skill 脚本可能会被分享、备份、放到 Git 仓库里一旦硬编码数据库密码就跟着泄漏了。用环境变量虽然不能做到绝对安全但至少把敏感信息隔离在代码之外这个习惯值得养成。另外我用了DictCursor查询结果会以字典列表的形式返回每条记录都是{字段名: 值}的结构。这个结构在后续转成自然语言回复时非常方便直接就能按字段名取数据。3.3 查询操作的实现参数化查询是底线查询是增删改查里最常用、也最容易出问题的操作。核心实现逻辑是接收表名和条件动态拼接 WHERE 子句但值部分必须走参数化查询。def execute_select(table, conditionsNone, limit10): conn get_connection() try: with conn.cursor() as cursor: sql fSELECT * FROM {table} params [] if conditions: where_clause AND .join([f{k} %s for k in conditions.keys()]) sql f WHERE {where_clause} params list(conditions.values()) sql LIMIT %s params.append(limit) cursor.execute(sql, params) rows cursor.fetchall() return {success: True, data: rows, count: len(rows)} except Exception as e: return {success: False, error: str(e)} finally: conn.close()这里最关键的一行是cursor.execute(sql, params)。参数不是拼接进 SQL 字符串的而是通过%s占位符传入的。这样即使参数里包含 OR 11 --这样的恶意内容pymysql 也会把它当作纯字符串处理不会改变 SQL 结构。这是防止 SQL 注入的底线绝对不能省。LIMIT 默认值是 10这个细节很重要。如果没有这个限制AI 可能一次性查出全表几十万条数据轻则响应缓慢重则把内存打爆。加个默认 limit既保护了数据库也保护了 OpenClaw 的上下文窗口。3.4 新增和更新操作字段白名单与影响行数新增和更新的逻辑类似都是先校验字段是否合法再执行写入。我在这里加了一个小设计允许的表和字段白名单。ALLOWED_TABLES {user_info} def validate_table(table): if table not in ALLOWED_TABLES: raise ValueError(f表 {table} 不在白名单内) def execute_insert(table, data): validate_table(table) allowed_fields {username, nickname, email, status} filtered {k: v for k, v in data.items() if k in allowed_fields} if not filtered: return {success: False, error: 没有合法字段} keys list(filtered.keys()) placeholders , .join([%s] * len(keys)) sql fINSERT INTO {table} ({, .join(keys)}) VALUES ({placeholders}) conn get_connection() try: with conn.cursor() as cursor: cursor.execute(sql, list(filtered.values())) conn.commit() return {success: True, insert_id: cursor.lastrowid} except Exception as e: conn.rollback() return {success: False, error: str(e)} finally: conn.close()你可能会想data是从 AI 传过来的 JSON 对象为什么还要做字段过滤因为 AI 有时候会自作主张加字段。比如你让它新增用户它可能顺手传一个id或created_at进来如果不过滤轻则报错重则覆盖自增主键。白名单机制直接把这个风险掐死在入口。更新操作和插入类似但多了一个强制条件必须带conditions并且我会检查条件是否为空。没有 WHERE 条件的 UPDATE 会更新整张表这个事故太常见了必须在代码层面拦一道。3.5 删除操作默认加保护条件必须明确删除是最危险的操作我在设计上做了三重保护。第一conditions必须存在且非空否则直接拒绝执行。第二条件里必须包含一个能精确定位的字段比如主键id。第三执行前先做一次 SELECT确认影响行数在预期范围内。当然第三重属于业务层面的校验脚本里我用简单的方式实现先查一遍如果影响行数为 0 或条件太宽泛就返回提示。def execute_delete(table, conditions): if not conditions: return {success: False, error: 删除操作必须带条件} validate_table(table) where_clause AND .join([f{k} %s for k in conditions.keys()]) sql fDELETE FROM {table} WHERE {where_clause} conn get_connection() try: with conn.cursor() as cursor: cursor.execute(sql, list(conditions.values())) conn.commit() return {success: True, affected_rows: cursor.rowcount} except Exception as e: conn.rollback() return {success: False, error: str(e)} finally: conn.close()这里有个体验细节删除成功后AI 回复用户时最好能带上“删除了几条记录”这个数字来自cursor.rowcount。我见过不少实现删除后只回一句“删除成功”用户压根不知道到底删没删干净、删了几条。有数字用户才心里有数。4. 实操全过程让 OpenClaw 真的把数据查出来4.1 第一轮先脱离 OpenClaw纯脚本联调写 Skill 脚本时我建议你先别急着挂载到 OpenClaw 上先在终端里把脚本跑通。做法是写一个简单的 stdin 读取逻辑接收 JSON 参数然后把结果输出成 JSON 字符串。if __name__ __main__: input_data json.loads(sys.stdin.read()) operation input_data.get(operation) table input_data.get(table) conditions input_data.get(conditions, {}) data input_data.get(data, {}) limit input_data.get(limit, 10) if operation select: result execute_select(table, conditions, limit) elif operation insert: result execute_insert(table, data) elif operation update: result execute_update(table, data, conditions) elif operation delete: result execute_delete(table, conditions) else: result {success: False, error: f不支持的操作: {operation}} print(json.dumps(result, ensure_asciiFalse))测试时可以用管道把 JSON 喂给脚本echo {operation: select, table: user_info, conditions: {status: 1}, limit: 5} | python3 mysql_crud.py我强烈建议把这一步做扎实。因为一旦挂到 OpenClaw 上你还要面对模型传参不规范的问题如果脚本本身没调试好到时候你就分不清是脚本的问题还是模型解析的问题了。先把脚本调试到“任何合法 JSON 都能给出正确响应”这一步大概能挡掉一半的后续排查工作量。4.2 第二轮把 Skill 挂载到 OpenClaw脚本跑通以后把整个 Skill 目录放到 OpenClaw 的 skills 目录下然后在 OpenClaw 的配置里启用这个 Skill。启用的方式因版本而异核心是让 OpenClaw 能扫描到该 Skill 的 YAML 描述文件。挂载成功后建议先做一个“假调用”测试在对话里问 OpenClaw“你有没有操作 MySQL 数据库的能力”如果模型正确识别了 Skill 的存在它会告诉你具备相关能力并主动询问你要操作什么。如果这个阶段模型完全感知不到 Skill检查一下 YAML 文件的name和description是不是写清楚了有时候是描述太模糊模型没意识到该用这个技能。还有一个常见坑Skill 脚本的路径里有中文或空格可能导致 OpenClaw 调用脚本时找不到文件。保险起见Skill 目录名尽量用英文小写加下划线比如mysql_crud避免各种系统兼容性问题。4.3 第三轮模拟真实对话场景挂载成功后我开始用真实的自然语言去验证四种操作。查询场景我输入“查一下用户表里最近注册的 3 个人要用户名和昵称”。OpenClaw 识别出操作类型是 select表是 user_info条件里可能带上 created_at 排序但我在 Skill 里没暴露排序参数所以它只能在 limit 上做文章。最终执行结果是把最近 3 条记录返回再转成自然语言回复。新增场景我输入“新增一个用户用户名叫 zhangsan昵称叫张三”。这时模型会生成一个 insert 操作data 参数为{username: zhangsan, nickname: 张三}。脚本执行后返回insert_id模型会基于这个 ID 回复“新增成功用户 ID 是 1”。更新场景我说“把 ID 为 2 的用户状态改成 0禁用掉”。模型应当解析出operationupdate、tableuser_info、data{status: 0}、conditions{id: 2}执行后返回影响行数。删除场景我说“删除 ID 为 3 的用户”。这里模型可能会犹豫因为删除是不可逆操作。但在 Skill 层面只要它明确解析出了条件和表名就会执行删除。如果你想更稳一点可以在描述文件里加一句“删除操作前必须和用户确认”让模型生成删除前先追问一句这个策略在真实项目里很管用。4.4 第四轮日志与调试实际跑起来以后调试是绕不开的。OpenClaw 通常有日志文件会记录每次 Skill 调用的输入输出。遇到问题时我建议按这个顺序排查先看 OpenClaw 的日志确认模型到底传了什么参数。很多情况下问题出在模型传参错误比如该传conditions却传了condition脚本收到后识别不到自然报错。这时候调整 YAML 描述里的参数名让模型更容易理解比改脚本更有效。再看脚本本身的报错输出。如果脚本抛了异常异常信息会打印到 stderrOpenClaw 一般会捕获并反馈到对话里。常见的有连接超时、表不存在、字段不存在按提示处理即可。最后看 MySQL 端的日志和状态。如果脚本执行了但数据没变化多半是事务没提交或者被回滚了。我在写更新和删除时都加了conn.commit()如果忘了这一步数据确实不会变但也不会报错这种“静默失败”最让人头疼。5. 常见问题与排查技巧实录5.1 连接失败先分清是哪一层连不上连接 MySQL 失败的场景常见报错有这么几种。第一种是Cant connect to MySQL server意思是网络层就通不了。先ping一下数据库主机再确认 3306 端口是否开放尤其注意云服务器安全组策略。第二种是Access denied for user这个最直接就是用户名或密码错误或者该用户没有远程登录权限。MySQL 默认创建的账号往往是rootlocalhost如果 Skill 脚本从另一台机器连接必须显式创建授权账号CREATE USER openclaw% IDENTIFIED BY 密码;再GRANT SELECT, INSERT, UPDATE, DELETE ON openclaw_demo.* TO openclaw%;。第三种是认证插件不兼容报错通常是Authentication plugin caching_sha2_password cannot be loaded。解决办法是把 pymysql 升级到新版或者在 MySQL 里把账号的认证方式改回mysql_native_password。我建议优先升级 pymysql因为改认证方式是向后兼容的妥协不是长久之计。5.2 中文乱码字符集三个地方必须统一在 Skill 里处理中文数据乱码是高频问题。乱码的根源通常是三个地方的字符集不一致MySQL 实例、数据库表、Python 连接参数。MySQL 实例字符集在启动时读配置文件数据库和表的字符集在建库建表时确定Python 连接的字符集我在 DB_CONFIG 里设成了utf8mb4。这三处必须统一成utf8mb4缺一个都可能出问题。有一种情况特别容易忽略脚本输出 JSON 时用了ensure_asciiFalse但 OpenClaw 在读取 stdout 时可能按系统默认编码解析如果系统是 Windows 且默认 GBK就会显示乱码。解决办法是在print的时候显式指定输出编码或者在脚本开头加上sys.stdout.reconfigure(encodingutf-8)确保输出流走 UTF-8。5.3 模型传参不规范不要硬扛用描述文件去引导这是我在整个项目里遇到最多的问题。模型对参数名的理解有很大的随机性你定义的是conditions它可能传成where、filters、condition一旦传错脚本就收不到条件查询可能退化成全表扫描。我的经验是在 YAML 的 description 里用自然语言描述每个参数的用法。不要只写“条件参数”而是写“用于过滤记录的字段映射例如 {id: 1} 表示查询 id 等于 1 的记录”。模型看描述时是按语义理解的你给一个具体例子它通常会照着这个格式传。如果还是传错还有一个兜底方案在脚本里把可能出现的参数别名都兼容一遍比如conditions input_data.get(conditions) or input_data.get(where) or input_data.get(filters)。这算是个土办法但实际非常好用。5.4 问题排查速查表现象可能原因处理方式连接超时网络不通、防火墙拦截 3306先 ping 主机再检查安全组和防火墙连接被拒绝bind-address 只绑本机修改bind-address0.0.0.0并重启 MySQL登录失败账号未授权远程访问创建openclaw%账号并授权认证插件报错MySQL 8.0 与旧版 pymysql 不兼容升级 pymysql或改回 native_password中文乱码字符集不统一实例、库表、连接全部使用 utf8mb4插入失败但无报错字段白名单过滤掉了所有字段检查 data 里字段名是否在白名单内更新影响全表conditions 为空未拦截代码里强制 conditions 非空查询结果太多没带 LIMIT脚本里默认 limit10stdout 内容中文乱码系统编码不是 UTF-8sys.stdout.reconfigure(encodingutf-8)6. 实践复盘与扩展建议6.1 Skill 拆细一点还是合并成一个做这个项目时我反复犹豫过一个问题增删改查是拆成四个 Skill还是合并成一个mysql_crud最后我选了合并因为它四个操作虽然逻辑不同但本质都是“操作 MySQL”参数结构也有很强的关联性合并成一个 Skill 可以降低模型选择技能的开销。但如果你的业务表很多或者每张表有不同的权限控制我建议你拆开。比如user_query、order_query、user_write各自独立这样可以在描述文件里写清楚每张表能做什么不能做什么模型调用时意图更明确权限边界也更清晰。我的经验是表少于三张用一个综合 Skill表多了还是按业务域拆开。6.2 从 CRUD 再往前走一步增删改查跑通后你可能会想扩展更多能力。我觉得比较自然的延伸方向有几个。第一个是统计查询。模型很适合响应“统计每个状态下的用户数”这类问题只要在 Skill 里加一个aggregate操作允许传入聚合函数和分组字段就能把 count、sum、group by 这类能力安全地暴露给模型。第二个是异步执行和结果回调。如果数据库操作很慢比如一张大数据量的表做复杂查询同步等待会占用 OpenClaw 的调用时间。可以把查询任务丢到队列里完成后通过回调把结果喂回对话。这个改造比较复杂但真实场景里很有价值。第三个是写操作前的审批流。我在做删除操作保护时提到过“让模型先确认”更严格的做法是在 OpenClaw 外层配置一个审批节点任何写操作都先暂停等人工点击确认后再真正执行。这在生产环境里几乎是必须的毕竟数据库操作不可逆。6.3 我对这个项目最深的几点体会项目做下来我最深的一个体会是数据库 Skill 的核心难点其实不在于“让 AI 会写 SQL”而在于“限制 AI 只能做你允许它做的事”。代码本身的复杂度反而是次要的真正的复杂度在于你如何设计边界、如何引导模型传参、如何预设各种异常场景。还有一点想提醒你别把 Skill 脚本写得太过“聪明”。不要试图在脚本里实现复杂的业务逻辑比如自动关联查询多张表、自动做数据校验。Skill 脚本越简单越好它更像一个“翻译器”把 AI 的参数翻译成安全、确定的 SQL 执行。一旦脚本承担了太多业务逻辑它就会膨胀、难维护最后反而成了系统的脆弱点。最后一个小建议脚本里的错误信息一定要写得足够人类可读。OpenClaw 会把脚本的报错原封不动反馈给用户如果你的报错是KeyError: conditions用户一脸懵如果你写成缺少条件参数 conditions请提供需要查询的条件用户自然就懂了。这个细节能极大提升体验也是我在这个项目里反复打磨的地方。本文还有配套的精品资源点击获取 OpenClaw 接入 MySQL：为 AI 安全封装数据库操作 Skill
简介数据库操作的安全边界是 AI Agent 落地产出的核心挑战。当智能体需要直接访问 MySQL 时简单让模型拼接 SQL 会放大注入与误操作风险。通过参数化查询、字段白名单、强制条件校验等基础工程手段可以在原理上约束 AI 的行为将不确定性控制在允许范围内。OpenClaw 的 Skill 机制把这类能力封装成命名的工具接口让开发者以本地脚本的形式安全暴露增删改查同时保留清晰的权限边界与可审计日志。该模式适合面向 AI 的数据库服务集成、企业内部数据助手等场景也可为其他智能体框架提供设计参考。本文围绕 OpenClaw 与 MySQL 的实战过程展示如何构建一个安全可控的数据库操作技能。 最近在给 OpenClaw 做技能扩展正好需要让智能体能直接读写 MySQL。说实话刚开始我觉得这事儿很简单不就是让 AI 自己写 SQL 去执行吗结果真做起来才发现如果不管控“AI 写 SQL 直连数据库”这个组合在真实业务里跟裸奔没什么区别。所以我把整套能力封装成了标准 Skill让 OpenClaw 在受控范围内完成增删改查。这篇文章就是把整个过程完整复盘一次包括 Skill 怎么设计、代码怎么写、哪些坑必须躲希望能帮你少走弯路。如果你是刚接触 OpenClaw 的新手或者已经在用 OpenClaw 但一直没敢碰数据库操作这篇文章应该正好卡在你的需求点上。我会从环境部署讲到 Skill 实现再讲到真实调用场景尽量把每个决策背后的原因也交代清楚。1. 项目概述与整体设计思路1.1 动手之前先想清楚 Skill 做数据库操作的边界先说结论OpenClaw 接入 MySQL 最合理的姿势不是让 AI 自由发挥生成 SQL而是把数据库操作封装成有限集合的 SkillAI 只负责“按需调用”和“传参数”。为什么这么设计你想象一下如果让 AI 直接生成 SQL 丢给生产库执行它会遇到三类问题。第一AI 对表结构不熟悉很容易生成不存在的字段名报错后它会自作聪明地换一种写法然后继续报错这个循环非常难受。第二SQL 注入风险没法完全消除AI 生成的字符串条件拼接正好是注入攻击最爱的入口。第三不可控你不知道它下一秒会执行一条DELETE FROM不带 WHERE还是DROP TABLE。所以我定的边界是Skill 里只暴露确定的表、确定的字段、确定的操作类型AI 只能在这个框架里面传值。它可以说“查一下用户表里最近注册的 10 个人”但没办法让它“删库跑路”——因为在 Skill 代码层就没开放这种能力。这套思路本质上和你在后端接口层做参数白名单是一个道理。1.2 为什么选 OpenClaw 做这个事你可能也看到过 Coze、Dify、Workbuddy 这一堆智能体平台它们都能接数据库为什么我在这个项目里选了 OpenClaw核心原因是 OpenClaw 的 Skill 机制更接近“本地代码扩展”。你在 OpenClaw 里写一个 Skill本质上就是把一段 Python 或 Shell 脚本挂到 AI 的调用链上脚本跑在你自己控制的环境里不走云端的黑盒网关。这意味着你可以直接使用 pymysql、直接读取本地配置文件、直接连内网数据库不需要绕一圈 HTTP 接口。另一个原因是它的调试链路短。Coze 那边接数据库很多时候你得先做一个自定义插件再把插件发布成 API 服务链路长、排错麻烦。OpenClaw 这边Skill 脚本可以直接在终端跑通再挂载到对话里验证两步就能完成闭环特别适合我这种喜欢先本地跑通再集成的人。1.3 整体链路设计先看一条完整的调用链用户自然语言 - OpenClaw 模型解析意图 - 匹配到 mysql_crud Skill - 生成参数 JSON - 调用 Python 脚本 - pymysql 执行 SQL - 结果写回 stdout - OpenClaw 转成自然语言回复这个链路里真正的 MySQL 操作发生在 Python 脚本内部AI 模型只负责两件事判断“该用哪个操作”以及“该传什么参数”。这两件事恰好是模型最擅长的而 SQL 生成和执行细节则完全由脚本来掌控。我在项目里把 Skill 拆成了两个维度操作类型和参数校验。操作类型固定为 select、insert、update、delete 四种参数里再区分表名、条件、字段值等。这样既保证灵活性又不至于失控。后面我会详细展开代码实现你先记住这个链路后面所有实操都是围绕它展开的。2. 环境准备把 OpenClaw 和 MySQL 都跑起来2.1 OpenClaw 部署不同平台的注意事项OpenClaw 的部署不是这篇文章的重点但既然要让 Skill 真正跑起来环境这关必须过。我基于常见实践给你捋一下关键点详细步骤还是以官方文档为准。Windows 上部署最容易踩的坑是 Python 环境变量没配好。OpenClaw 依赖 Python 3.10 以上版本装完后你在 CMD 里执行python --version如果提示“不是内部或外部命令”说明没把 Python 加入 PATH。这种情况不用重装去“系统属性 - 环境变量 - Path”里手动加上 Python 安装目录就行。Linux 和 macOS 上部署相对顺滑但要注意权限问题。我见过不少人在 Ubuntu 上直接sudo pip install openclaw结果装到了系统 Python 目录后面跑 Skill 时因为权限不足报错。建议用一个独立的 Python 虚拟环境或者用pip install --user安装避免动系统级依赖。还有一个通用提醒OpenClaw 部署完以后先跑一下官方自带的示例 Skill 做冒烟测试。如果连示例都跑不通问题大概率出在环境本身而不是你的 Skill 代码。别急着写自己的 Skill先把基础链路打通后面排查范围会小很多。2.2 MySQL 安装的版本选择以及必须做的两个配置MySQL 的安装方式各平台差异很大但版本选择有一个原则生产环境尽量用 5.7 或 8.0 的 LTS 版本别追最新大版本。8.0 和 5.7 在增删改查层面几乎没有区别但在认证插件上差别很大。8.0 默认用的caching_sha2_password某些老版本的 Python 库不认识这个认证方式连接时会直接报错。如果你用的是 pymysql 且版本较旧连接 8.0 很可能遇到这个问题。我的建议是如果是新项目直接用 MySQL 8.0然后把 pymysql 升级到 1.x 最新版生态兼容性最好。安装完成后有两件事必须做属于那种“不做一定后悔”的配置。第一件事确认监听地址。默认情况下 MySQL 只监听 127.0.0.1如果你的 OpenClaw 跑在另一台机器上需要在my.cnf或my.ini里把bind-address改为0.0.0.0然后在防火墙里放行 3306 端口。这里我建议你谨慎一点如果 OpenClaw 和 MySQL 在同一台机器上保持默认 127.0.0.1 就是最安全的。第二件事单独建一个业务账号别用 root 连接。我在项目里新建了一个叫openclaw的账号只授予项目所需数据库的增删改查权限。这样即使 Skill 脚本被注入或误操作影响范围也被限制在单库级别不会波及整个 MySQL 实例。2.3 准备一张练习用的表结构在写 Skill 代码之前先把数据库和表准备好。我用一个最典型的用户表来做演示字段不多但覆盖了增删改查的所有场景。CREATE DATABASE IF NOT EXISTS openclaw_demo DEFAULT CHARACTER SET utf8mb4; USE openclaw_demo; CREATE TABLE IF NOT EXISTS user_info ( id INT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(64) NOT NULL UNIQUE, nickname VARCHAR(64) DEFAULT , email VARCHAR(128) DEFAULT , status TINYINT DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里有几个细节值得说明。第一为什么所有字符类型都带长度因为 varchar 的长度直接影响索引和存储开销64 和 128 对用户名字段来说已经够用别随手写个 255。第二status字段用 TINYINT 而不是 VARCHAR因为状态这种枚举型数据用数字存更省空间也方便扩展。第三created_at给了默认值这样 insert 的时候可以不传这个字段减少参数复杂度。3. Skill 的实现核心代码与关键细节3.1 Skill 目录结构和清单文件怎么定义OpenClaw 的 Skill 通常是一个独立目录里面至少包含一个描述文件和一个可执行脚本。描述文件的作用是让模型知道“这个技能是干什么的、什么时候该调用它、需要传什么参数”我用的是 YAML 格式这是社区里比较通用的做法。name: mysql_crud description: 对 MySQL 数据库执行增删改查操作支持 select、insert、update、delete 四种操作。 version: 1.0.0 parameters: - name: operation type: string required: true description: 操作类型枚举值 select、insert、update、delete - name: table type: string required: true description: 目标数据表名 - name: conditions type: object required: false description: 条件字段映射例如 {id: 1} - name: data type: object required: false description: 写入或更新的字段映射例如 {username: tom, status: 1}写 description 的时候有个技巧要写清楚“什么时候用”而不是只写“能干什么”。比如“当用户需要查询、新增、修改或删除数据库记录时使用”比“MySQL 增删改查”更容易触发。模型是靠描述来匹配意图的描述越贴近真实会话场景命中率越高。3.2 数据库连接封装别在每次调用里重复建连Skill 脚本虽然是“一次调用一次进程”但连接这块还是值得封装一下。我在脚本里单独抽了一个get_connection函数统一管理连接参数。#!/usr/bin/env python3 import os import sys import json import pymysql DB_CONFIG { host: os.getenv(MYSQL_HOST, 127.0.0.1), port: int(os.getenv(MYSQL_PORT, 3306)), user: os.getenv(MYSQL_USER, openclaw), password: os.getenv(MYSQL_PASSWORD, ), database: os.getenv(MYSQL_DATABASE, openclaw_demo), charset: utf8mb4, cursorclass: pymysql.cursors.DictCursor, }可能有人会问为什么不直接在脚本里硬编码账号密码答案很简单不安全。Skill 脚本可能会被分享、备份、放到 Git 仓库里一旦硬编码数据库密码就跟着泄漏了。用环境变量虽然不能做到绝对安全但至少把敏感信息隔离在代码之外这个习惯值得养成。另外我用了DictCursor查询结果会以字典列表的形式返回每条记录都是{字段名: 值}的结构。这个结构在后续转成自然语言回复时非常方便直接就能按字段名取数据。3.3 查询操作的实现参数化查询是底线查询是增删改查里最常用、也最容易出问题的操作。核心实现逻辑是接收表名和条件动态拼接 WHERE 子句但值部分必须走参数化查询。def execute_select(table, conditionsNone, limit10): conn get_connection() try: with conn.cursor() as cursor: sql fSELECT * FROM {table} params [] if conditions: where_clause AND .join([f{k} %s for k in conditions.keys()]) sql f WHERE {where_clause} params list(conditions.values()) sql LIMIT %s params.append(limit) cursor.execute(sql, params) rows cursor.fetchall() return {success: True, data: rows, count: len(rows)} except Exception as e: return {success: False, error: str(e)} finally: conn.close()这里最关键的一行是cursor.execute(sql, params)。参数不是拼接进 SQL 字符串的而是通过%s占位符传入的。这样即使参数里包含 OR 11 --这样的恶意内容pymysql 也会把它当作纯字符串处理不会改变 SQL 结构。这是防止 SQL 注入的底线绝对不能省。LIMIT 默认值是 10这个细节很重要。如果没有这个限制AI 可能一次性查出全表几十万条数据轻则响应缓慢重则把内存打爆。加个默认 limit既保护了数据库也保护了 OpenClaw 的上下文窗口。3.4 新增和更新操作字段白名单与影响行数新增和更新的逻辑类似都是先校验字段是否合法再执行写入。我在这里加了一个小设计允许的表和字段白名单。ALLOWED_TABLES {user_info} def validate_table(table): if table not in ALLOWED_TABLES: raise ValueError(f表 {table} 不在白名单内) def execute_insert(table, data): validate_table(table) allowed_fields {username, nickname, email, status} filtered {k: v for k, v in data.items() if k in allowed_fields} if not filtered: return {success: False, error: 没有合法字段} keys list(filtered.keys()) placeholders , .join([%s] * len(keys)) sql fINSERT INTO {table} ({, .join(keys)}) VALUES ({placeholders}) conn get_connection() try: with conn.cursor() as cursor: cursor.execute(sql, list(filtered.values())) conn.commit() return {success: True, insert_id: cursor.lastrowid} except Exception as e: conn.rollback() return {success: False, error: str(e)} finally: conn.close()你可能会想data是从 AI 传过来的 JSON 对象为什么还要做字段过滤因为 AI 有时候会自作主张加字段。比如你让它新增用户它可能顺手传一个id或created_at进来如果不过滤轻则报错重则覆盖自增主键。白名单机制直接把这个风险掐死在入口。更新操作和插入类似但多了一个强制条件必须带conditions并且我会检查条件是否为空。没有 WHERE 条件的 UPDATE 会更新整张表这个事故太常见了必须在代码层面拦一道。3.5 删除操作默认加保护条件必须明确删除是最危险的操作我在设计上做了三重保护。第一conditions必须存在且非空否则直接拒绝执行。第二条件里必须包含一个能精确定位的字段比如主键id。第三执行前先做一次 SELECT确认影响行数在预期范围内。当然第三重属于业务层面的校验脚本里我用简单的方式实现先查一遍如果影响行数为 0 或条件太宽泛就返回提示。def execute_delete(table, conditions): if not conditions: return {success: False, error: 删除操作必须带条件} validate_table(table) where_clause AND .join([f{k} %s for k in conditions.keys()]) sql fDELETE FROM {table} WHERE {where_clause} conn get_connection() try: with conn.cursor() as cursor: cursor.execute(sql, list(conditions.values())) conn.commit() return {success: True, affected_rows: cursor.rowcount} except Exception as e: conn.rollback() return {success: False, error: str(e)} finally: conn.close()这里有个体验细节删除成功后AI 回复用户时最好能带上“删除了几条记录”这个数字来自cursor.rowcount。我见过不少实现删除后只回一句“删除成功”用户压根不知道到底删没删干净、删了几条。有数字用户才心里有数。4. 实操全过程让 OpenClaw 真的把数据查出来4.1 第一轮先脱离 OpenClaw纯脚本联调写 Skill 脚本时我建议你先别急着挂载到 OpenClaw 上先在终端里把脚本跑通。做法是写一个简单的 stdin 读取逻辑接收 JSON 参数然后把结果输出成 JSON 字符串。if __name__ __main__: input_data json.loads(sys.stdin.read()) operation input_data.get(operation) table input_data.get(table) conditions input_data.get(conditions, {}) data input_data.get(data, {}) limit input_data.get(limit, 10) if operation select: result execute_select(table, conditions, limit) elif operation insert: result execute_insert(table, data) elif operation update: result execute_update(table, data, conditions) elif operation delete: result execute_delete(table, conditions) else: result {success: False, error: f不支持的操作: {operation}} print(json.dumps(result, ensure_asciiFalse))测试时可以用管道把 JSON 喂给脚本echo {operation: select, table: user_info, conditions: {status: 1}, limit: 5} | python3 mysql_crud.py我强烈建议把这一步做扎实。因为一旦挂到 OpenClaw 上你还要面对模型传参不规范的问题如果脚本本身没调试好到时候你就分不清是脚本的问题还是模型解析的问题了。先把脚本调试到“任何合法 JSON 都能给出正确响应”这一步大概能挡掉一半的后续排查工作量。4.2 第二轮把 Skill 挂载到 OpenClaw脚本跑通以后把整个 Skill 目录放到 OpenClaw 的 skills 目录下然后在 OpenClaw 的配置里启用这个 Skill。启用的方式因版本而异核心是让 OpenClaw 能扫描到该 Skill 的 YAML 描述文件。挂载成功后建议先做一个“假调用”测试在对话里问 OpenClaw“你有没有操作 MySQL 数据库的能力”如果模型正确识别了 Skill 的存在它会告诉你具备相关能力并主动询问你要操作什么。如果这个阶段模型完全感知不到 Skill检查一下 YAML 文件的name和description是不是写清楚了有时候是描述太模糊模型没意识到该用这个技能。还有一个常见坑Skill 脚本的路径里有中文或空格可能导致 OpenClaw 调用脚本时找不到文件。保险起见Skill 目录名尽量用英文小写加下划线比如mysql_crud避免各种系统兼容性问题。4.3 第三轮模拟真实对话场景挂载成功后我开始用真实的自然语言去验证四种操作。查询场景我输入“查一下用户表里最近注册的 3 个人要用户名和昵称”。OpenClaw 识别出操作类型是 select表是 user_info条件里可能带上 created_at 排序但我在 Skill 里没暴露排序参数所以它只能在 limit 上做文章。最终执行结果是把最近 3 条记录返回再转成自然语言回复。新增场景我输入“新增一个用户用户名叫 zhangsan昵称叫张三”。这时模型会生成一个 insert 操作data 参数为{username: zhangsan, nickname: 张三}。脚本执行后返回insert_id模型会基于这个 ID 回复“新增成功用户 ID 是 1”。更新场景我说“把 ID 为 2 的用户状态改成 0禁用掉”。模型应当解析出operationupdate、tableuser_info、data{status: 0}、conditions{id: 2}执行后返回影响行数。删除场景我说“删除 ID 为 3 的用户”。这里模型可能会犹豫因为删除是不可逆操作。但在 Skill 层面只要它明确解析出了条件和表名就会执行删除。如果你想更稳一点可以在描述文件里加一句“删除操作前必须和用户确认”让模型生成删除前先追问一句这个策略在真实项目里很管用。4.4 第四轮日志与调试实际跑起来以后调试是绕不开的。OpenClaw 通常有日志文件会记录每次 Skill 调用的输入输出。遇到问题时我建议按这个顺序排查先看 OpenClaw 的日志确认模型到底传了什么参数。很多情况下问题出在模型传参错误比如该传conditions却传了condition脚本收到后识别不到自然报错。这时候调整 YAML 描述里的参数名让模型更容易理解比改脚本更有效。再看脚本本身的报错输出。如果脚本抛了异常异常信息会打印到 stderrOpenClaw 一般会捕获并反馈到对话里。常见的有连接超时、表不存在、字段不存在按提示处理即可。最后看 MySQL 端的日志和状态。如果脚本执行了但数据没变化多半是事务没提交或者被回滚了。我在写更新和删除时都加了conn.commit()如果忘了这一步数据确实不会变但也不会报错这种“静默失败”最让人头疼。5. 常见问题与排查技巧实录5.1 连接失败先分清是哪一层连不上连接 MySQL 失败的场景常见报错有这么几种。第一种是Cant connect to MySQL server意思是网络层就通不了。先ping一下数据库主机再确认 3306 端口是否开放尤其注意云服务器安全组策略。第二种是Access denied for user这个最直接就是用户名或密码错误或者该用户没有远程登录权限。MySQL 默认创建的账号往往是rootlocalhost如果 Skill 脚本从另一台机器连接必须显式创建授权账号CREATE USER openclaw% IDENTIFIED BY 密码;再GRANT SELECT, INSERT, UPDATE, DELETE ON openclaw_demo.* TO openclaw%;。第三种是认证插件不兼容报错通常是Authentication plugin caching_sha2_password cannot be loaded。解决办法是把 pymysql 升级到新版或者在 MySQL 里把账号的认证方式改回mysql_native_password。我建议优先升级 pymysql因为改认证方式是向后兼容的妥协不是长久之计。5.2 中文乱码字符集三个地方必须统一在 Skill 里处理中文数据乱码是高频问题。乱码的根源通常是三个地方的字符集不一致MySQL 实例、数据库表、Python 连接参数。MySQL 实例字符集在启动时读配置文件数据库和表的字符集在建库建表时确定Python 连接的字符集我在 DB_CONFIG 里设成了utf8mb4。这三处必须统一成utf8mb4缺一个都可能出问题。有一种情况特别容易忽略脚本输出 JSON 时用了ensure_asciiFalse但 OpenClaw 在读取 stdout 时可能按系统默认编码解析如果系统是 Windows 且默认 GBK就会显示乱码。解决办法是在print的时候显式指定输出编码或者在脚本开头加上sys.stdout.reconfigure(encodingutf-8)确保输出流走 UTF-8。5.3 模型传参不规范不要硬扛用描述文件去引导这是我在整个项目里遇到最多的问题。模型对参数名的理解有很大的随机性你定义的是conditions它可能传成where、filters、condition一旦传错脚本就收不到条件查询可能退化成全表扫描。我的经验是在 YAML 的 description 里用自然语言描述每个参数的用法。不要只写“条件参数”而是写“用于过滤记录的字段映射例如 {id: 1} 表示查询 id 等于 1 的记录”。模型看描述时是按语义理解的你给一个具体例子它通常会照着这个格式传。如果还是传错还有一个兜底方案在脚本里把可能出现的参数别名都兼容一遍比如conditions input_data.get(conditions) or input_data.get(where) or input_data.get(filters)。这算是个土办法但实际非常好用。5.4 问题排查速查表现象可能原因处理方式连接超时网络不通、防火墙拦截 3306先 ping 主机再检查安全组和防火墙连接被拒绝bind-address 只绑本机修改bind-address0.0.0.0并重启 MySQL登录失败账号未授权远程访问创建openclaw%账号并授权认证插件报错MySQL 8.0 与旧版 pymysql 不兼容升级 pymysql或改回 native_password中文乱码字符集不统一实例、库表、连接全部使用 utf8mb4插入失败但无报错字段白名单过滤掉了所有字段检查 data 里字段名是否在白名单内更新影响全表conditions 为空未拦截代码里强制 conditions 非空查询结果太多没带 LIMIT脚本里默认 limit10stdout 内容中文乱码系统编码不是 UTF-8sys.stdout.reconfigure(encodingutf-8)6. 实践复盘与扩展建议6.1 Skill 拆细一点还是合并成一个做这个项目时我反复犹豫过一个问题增删改查是拆成四个 Skill还是合并成一个mysql_crud最后我选了合并因为它四个操作虽然逻辑不同但本质都是“操作 MySQL”参数结构也有很强的关联性合并成一个 Skill 可以降低模型选择技能的开销。但如果你的业务表很多或者每张表有不同的权限控制我建议你拆开。比如user_query、order_query、user_write各自独立这样可以在描述文件里写清楚每张表能做什么不能做什么模型调用时意图更明确权限边界也更清晰。我的经验是表少于三张用一个综合 Skill表多了还是按业务域拆开。6.2 从 CRUD 再往前走一步增删改查跑通后你可能会想扩展更多能力。我觉得比较自然的延伸方向有几个。第一个是统计查询。模型很适合响应“统计每个状态下的用户数”这类问题只要在 Skill 里加一个aggregate操作允许传入聚合函数和分组字段就能把 count、sum、group by 这类能力安全地暴露给模型。第二个是异步执行和结果回调。如果数据库操作很慢比如一张大数据量的表做复杂查询同步等待会占用 OpenClaw 的调用时间。可以把查询任务丢到队列里完成后通过回调把结果喂回对话。这个改造比较复杂但真实场景里很有价值。第三个是写操作前的审批流。我在做删除操作保护时提到过“让模型先确认”更严格的做法是在 OpenClaw 外层配置一个审批节点任何写操作都先暂停等人工点击确认后再真正执行。这在生产环境里几乎是必须的毕竟数据库操作不可逆。6.3 我对这个项目最深的几点体会项目做下来我最深的一个体会是数据库 Skill 的核心难点其实不在于“让 AI 会写 SQL”而在于“限制 AI 只能做你允许它做的事”。代码本身的复杂度反而是次要的真正的复杂度在于你如何设计边界、如何引导模型传参、如何预设各种异常场景。还有一点想提醒你别把 Skill 脚本写得太过“聪明”。不要试图在脚本里实现复杂的业务逻辑比如自动关联查询多张表、自动做数据校验。Skill 脚本越简单越好它更像一个“翻译器”把 AI 的参数翻译成安全、确定的 SQL 执行。一旦脚本承担了太多业务逻辑它就会膨胀、难维护最后反而成了系统的脆弱点。最后一个小建议脚本里的错误信息一定要写得足够人类可读。OpenClaw 会把脚本的报错原封不动反馈给用户如果你的报错是KeyError: conditions用户一脸懵如果你写成缺少条件参数 conditions请提供需要查询的条件用户自然就懂了。这个细节能极大提升体验也是我在这个项目里反复打磨的地方。本文还有配套的精品资源点击获取