openclaw docker部署后模型连接失败，需依次排查：①容器内模型服务进程是否运行；②8080端口是否监听；③宿主机curl测试health端点；④docker-compose.yml中volumes挂载路径与权限是否正确；⑤model.yaml语法合法性（禁用tab）；⑥权重文件md5完整性校验。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw Docker部署后模型连接失败，表现为Web界面加载空白、日志持续输出“model connection refused”或“failed to connect to model server”，说明容器已启动但无法与后端模型服务建立通信链路。
确认模型服务是否真正运行
进入容器内部检查模型服务进程状态：docker exec -it openclaw-app ps aux | grep "model\|server"。若无任何匹配进程，说明模型服务根本未启动——这通常是因为模型镜像拉取失败或启动命令被跳过。
手动触发模型服务启动：docker exec -it openclaw-app /bin/bash -c "cd /app/model && ./start.sh"。如果报错“No such file or directory”，说明模型二进制文件缺失，需检查镜像构建阶段是否漏掉了COPY指令。
【模型服务必须在容器内以非root用户身份运行，否则会被安全策略拦截】
验证模型服务端口监听状态
方法一：在容器内直接检测端口占用情况
docker exec -it openclaw-app ss -tln | grep :8080。若无输出，说明服务未绑定到8080端口（默认模型服务端口）。
方法二：从宿主机发起连接测试
curl -v http://localhost:8080/health。返回Connection refused表示模型服务未监听；返回503或timeout说明服务已启动但内部异常（如权重加载失败）。
注意：若使用自定义端口，请同步检查环境变量MODEL_PORT是否与docker-compose.yml中ports字段一致，不一致会导致请求被转发到错误端口。
排查模型配置文件挂载路径
第一步：确认docker-compose.yml中volumes配置是否包含模型配置目录映射
例如 - ./config/model.yaml:/app/config/model.yaml。
第二步：进入容器检查该路径是否存在且可读
docker exec -it openclaw-app ls -l /app/config/model.yaml。若提示No such file，说明挂载路径写错或宿主机对应文件未创建。
第三步：验证YAML语法是否合法
docker exec -it openclaw-app python -c "import yaml; print(yaml.safe_load(open('/app/config/model.yaml')))"。若报出ParserError，需修正缩进或冒号格式——【YAML中tab字符会导致解析失败，必须用空格】。
检查模型权重文件完整性
运行命令校验权重文件MD5值：
docker exec -it openclaw-app md5sum /app/models/encoder.bin | grep -q "d4a1b7e9c6f8a2b3c4d5e6f7a8b9c0d1" && echo "OK" || echo "CORRUPTED"。
若输出CORRUPTED，说明权重文件下载中断或被杀毒软件误删。此时应删除容器并重建：docker-compose down && docker-compose up -d。
这一步操作起来很简单，直接把文件拖进去就行。
