数据库连接失败说明mysql服务、网络、权限或参数至少一项未就位：需确认mysql已运行且监听0.0.0.0:3306，用户授权包含'openclaw'@'%'并执行flush privileges，openclaw配置中host填实际ip而非localhost，密码用引号包裹，防火墙及云安全组放行3306端口，且客户端兼容caching_sha2_password插件。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw部署完成后，执行初始化或服务启动时提示数据库连接失败，无法写入元数据或读取配置，说明MySQL服务、网络通路、权限策略或客户端参数中至少有一项未就位。
确认MySQL服务已运行且监听正确地址
第一步：运行 systemctl status mysqld 或 systemctl status mysql，检查服务状态是否为 active (running)。若显示 inactive，直接执行 systemctl start mysqld 启动。
第二步：检查 MySQL 是否监听在 OpenClaw 配置中指定的地址和端口。默认应监听 3306 端口，但关键要看 bind_address 设置——如果配置文件中写的是 bind_address = 127.0.0.1，则远程组件（如 OpenClaw 控制节点）必然连不上。必须改为 bind_address = 0.0.0.0 或具体管理网段 IP（例如 192.168.10.0/24 内的控制器 IP）。
第三步：改完配置后必须重启服务：systemctl restart mysqld，再用 ss -tlnp | grep :3306 验证监听地址是否已更新。若仍显示 LISTEN ON 127.0.0.1:3306，说明配置未生效或文件路径错误（常见于多配置文件共存，如 /etc/my.cnf 被 /etc/mysql/mysql.conf.d/mysqld.cnf 覆盖）。
验证OpenClaw所用数据库用户具备跨主机访问权限
MySQL 的权限判定严格依赖 【'user'@'host'】 这个三元组。OpenClaw 配置里写的数据库地址如果是 controller 或 192.168.10.5，那么对应授权就必须显式包含该 host 值。
登录 MySQL root 用户后，先执行：SELECT User, Host FROM mysql.user WHERE User = 'openclaw';。如果结果中只有 'openclaw'@'localhost'，而 OpenClaw 组件不在同一台机器上运行，那连接必定失败。
正确做法是补授权：GRANT ALL PRIVILEGES ON openclaw.* TO 'openclaw'@'%' IDENTIFIED BY 'your_strong_password'; FLUSH PRIVILEGES;。注意：百分号 % 不匹配 localhost，若 OpenClaw 某些脚本（如本地 CLI 工具）也需连接，额外加一条 'openclaw'@'localhost' 授权。
【切勿跳过 FLUSH PRIVILEGES；否则新权限不会立即生效】
检查OpenClaw配置中的数据库连接参数
打开 OpenClaw 主配置文件（通常是 /etc/openclaw/openclaw.conf 或 config/database.yml），定位 database 段落：
确认 host 字段不是 localhost —— 这会导致容器内或远程调用时解析为容器自身环回地址，而非宿主机 MySQL。应填实际 IP，例如 192.168.10.10。
确认 port 字段与 MySQL 实际监听端口一致；若修改过默认 3306，此处必须同步更新。
检查 password 字段：若密码含 $、@、/ 等 shell 特殊字符，在 YAML 或 INI 文件中未用引号包裹，会导致解析失败。务必用单引号或双引号包住整个密码值。
排查网络层拦截
方法一：从 OpenClaw 所在节点执行 telnet 192.168.10.10 3306（将 IP 替换为 MySQL 实际地址）。如果连接超时或拒绝，说明网络不通。
方法二：检查 MySQL 服务器本机防火墙：firewall-cmd --list-ports（CentOS）或 ufw status（Ubuntu）。若 3306 未列出，运行 firewall-cmd --permanent --add-port=3306/tcp && firewall-cmd --reload 开放端口。
方法三：云环境必须检查安全组——OpenClaw 节点的出向 + MySQL 节点的入向，双向都要放行 TCP 3306。仅开放 MySQL 节点入向还不够，OpenClaw 节点出向若被限制（如阿里云默认限制所有出向），照样连不上。
验证 MySQL 客户端认证插件兼容性
MySQL 8.0+ 默认使用 caching_sha2_password 插件，而部分 OpenClaw 依赖的旧版 Python MySQL 驱动（如 PyMySQL
临时解决：登录 MySQL，执行 ALTER USER 'openclaw'@'%' IDENTIFIED WITH mysql_native_password BY 'your_strong_password'; FLUSH PRIVILEGES;。这会把认证方式降级为兼容旧驱动的模式。
长期方案：升级 OpenClaw 依赖的数据库驱动，或在 MySQL 配置中全局设 default_authentication_plugin=mysql_native_password（需重启 mysqld）。
