必须配置外部数据库连接以实现OpenClaw小龙虾数据持久化与系统集成，具体包括：一、确认JDBC驱动兼容性并放入lib目录；二、修改config/application.yml中datasource配置；三、手动创建数据库、用户及授权；四、验证网络与服务连通性；五、依据日志异常关键词排查通信、认证、版本或驱动冲突问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用OpenClaw小龙虾时需要将应用数据持久化或与现有业务系统集成，则必须配置外部数据库连接。以下是完成OpenClaw小龙虾外部数据库连接与数据源配置的具体操作步骤：
一、确认数据库驱动兼容性
OpenClaw小龙虾基于Java运行，依赖JDBC驱动与外部数据库通信。不同数据库需对应版本匹配的JDBC驱动jar包，且该jar必须置于OpenClaw指定的lib目录中，否则启动时会抛出ClassNotFoundException或SQLException。
1、访问目标数据库的官方JDBC驱动下载页面，例如MySQL 8.0对应mysql-connector-j-8.0.x.jar，PostgreSQL对应postgresql-42.x.x.jar。
2、核对OpenClaw小龙虾当前使用的Java版本（执行java -version），确保所选JDBC驱动支持该JDK主版本（如JDK 11需选用支持JDBC 4.2及以上规范的驱动）。
3、将下载的JDBC驱动jar文件复制到OpenClaw安装目录下的lib子目录中。
二、修改application.yml配置文件
OpenClaw小龙虾采用Spring Boot框架，默认通过application.yml统一管理数据源参数。该文件位于config目录下，直接编辑可覆盖默认嵌入式H2数据库配置，启用外部数据库连接。
1、使用文本编辑器打开config/application.yml文件。
2、定位到spring:节点下的datasource:区块，删除或注释原有url:、username:、password:等字段。
3、按如下格式填入外部数据库信息：
url: jdbc:mysql://192.168.1.100:3306/openclaw_db?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
username: <strong><font color="green">openclaw_user</font></strong><br> password: <strong><font color="green">SecurePass2024!</font></strong><br> driver-class-name: com.mysql.cj.jdbc.Driver
4、保存文件并关闭编辑器。
三、初始化数据库结构
OpenClaw小龙虾不自动创建数据库和表结构，首次连接前须手动准备目标数据库及基础Schema。若未预先建库或权限不足，服务将无法启动并报错“Unknown database”或“Access denied for user”。
1、使用数据库客户端（如MySQL Workbench、DBeaver或命令行mysql）登录目标数据库服务器。
2、执行CREATE DATABASE IF NOT EXISTS openclaw_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
解决常见 OpenClaw 工作流瓶颈：平台 engage‑gates/429 回退辅助（始于 MoltX），标准化 JSON 结果封装用于脚本链式，工作区路径解析辅助，以及简易技能发布指挥（准备/发布/草稿公告）。
3、执行CREATE USER '<strong><font color="green">openclaw_user</font></strong>'@'%' IDENTIFIED BY '<strong><font color="green">SecurePass2024!</font></strong>';
4、执行GRANT ALL PRIVILEGES ON openclaw_db.* TO '<strong><font color="green">openclaw_user</font></strong>'@'%'; FLUSH PRIVILEGES;
四、验证连接有效性
配置完成后需验证JDBC连接是否真正可达，避免因网络策略、防火墙或数据库监听设置导致连接超时。OpenClaw小龙虾自身不提供独立连接测试界面，需借助外部工具或日志反馈确认。
1、确保目标数据库服务已启动，并监听在配置文件中指定的IP与端口（如3306或5432）。
2、检查服务器防火墙是否放行对应端口，例如Linux执行sudo ufw status确认3306端口为allow状态。
3、在OpenClaw所在主机执行telnet或nc命令测试连通性：telnet 192.168.1.100 3306，返回Connected即表示网络层通畅。
4、启动OpenClaw小龙虾服务，观察控制台日志中是否出现HikariPool-1 - Starting...及后续connected to database类提示。
五、处理常见连接异常
当外部数据库连接失败时，OpenClaw小龙虾通常会在启动日志中输出明确的异常堆栈。根据错误关键词可快速定位根源，无需重启整个服务即可修正配置。
1、若日志中出现Communications link failure，说明TCP连接被拒绝或中断，重点排查数据库地址、端口、防火墙及数据库是否运行。
2、若出现Access denied for user，表明认证失败，需核对application.yml中的username与password是否与数据库用户完全一致，注意大小写与特殊字符转义。
3、若出现Unknown system variable 'tx_isolation'，说明MySQL版本过高（如8.0.33+）与旧版驱动不兼容，应升级mysql-connector-j至8.0.33或更高版本。
4、若出现Failed to obtain JDBC Connection且无具体原因，检查lib目录下是否存在多个冲突的JDBC驱动jar（如同时存在mysql-connector-java-5.1.x.jar和8.0.x.jar），仅保留一个匹配版本。
