OpenClaw-China-Docker故障排查完全清单：Permission denied、JSON非法、401/403等10大问题怎么解

OpenClaw-China-Docker故障排查完全清单Permission denied、JSON非法、401/403等10大问题怎么解【免费下载链接】openclaw-china-dockerOpenClaw 的中国IM平台整合Docker版本预装并配置了飞书、钉钉、QQ机器人、企业微信等主流中国IM软件的插件让您可以快速部署一个支持多个中国IM平台的 AI 机器人网关项目地址: https://gitcode.com/gh_mirrors/op/openclaw-china-dockerOpenClaw-China-Docker 是面向中国 IM 场景的 OpenClaw Docker 整合镜像预装飞书、钉钉、QQ 机器人、企业微信等插件一条命令即可部署支持多平台的中国 IM AI 机器人网关。本文是一份故障排查完全清单覆盖 Permission denied、JSON 非法、账号冲突、401/403 等 10 个部署运维中最常遇到的问题帮你快速定位原因并给出可落地的解法。排查前先记住日志是第一位的遇到任何问题第一步永远先看启动日志里面几乎包含全部关键线索docker compose logs -f openclaw-gateway重点搜索这几个关键词渠道同步、已禁用渠道、未提供环境变量、权限检查失败、不是合法 JSON、冲突。项目完整的常见问题汇总见 docs/faq.md。1. 改了环境变量为什么不生效最快重建方法现象修改了 .env.example 复制出来的.env文件但容器行为毫无变化。原因与解法容器启动时会执行 init.sh根据当前环境变量同步模型、渠道、插件、Gateway 等配置到openclaw.json但以下情况会让你感觉没生效实际启动的不是你刚修改的那份.env容器没有重建或重启手动维护的openclaw.json中存在与环境变量冲突的旧字段标准解法3 步确认当前目录下的.env已保存强制重建容器让新变量注入docker compose up -d --force-recreate进入容器核对实际配置docker compose exec openclaw-gateway /bin/bash su node cat ~/.openclaw/openclaw.json⚠️ 如果想彻底从环境变量重新生成需删除数据目录中的openclaw.json后再重启该操作会丢弃手动修改请先备份详见 docs/faq.md。2. Permission denied 怎么解一步修复挂载目录权限现象容器反复报Permission denied或日志出现❌ 权限检查失败node 用户无法写入后直接退出。原因这不是偶发错误而是宿主机挂载目录与容器内用户权限不一致。常见于宿主机目录由root或其他 UID 创建、目录只读、SELinux 限制挂载卷。项目的自动修复机制docker-compose.yml 中已声明CHOWN、SETUID等能力并默认以 root 启动init.sh 会先尝试把/home/node/.openclaw的所有者自动改回node:node修复成功后再降权运行 Gateway——所以大多数权限问题启动时会自愈。仍失败时的手动解法Linux 宿主机直接修复目录所有权容器内 node 用户 UID/GID 为 1000sudo chown -R 1000:1000 ~/.openclaw已知宿主机 UID/GID 时在.env中显式指定运行用户OPENCLAW_RUN_USER1000:1000启用了 SELinux 的系统挂载卷需追加:z或:Z标签参数否则内核层会拒绝容器写入。3. 不是合法 JSON报错怎么解多账号变量正确写法现象启动日志出现类似这样的报错FEISHU_ACCOUNTS_JSON 不是合法 JSONDINGTALK_ACCOUNTS_JSON 不是合法 JSONWECOM_ACCOUNTS_JSON 不是合法 JSONQQBOT_BOTS_JSON 不是合法 JSON原因init.sh 会严格校验这些多账号环境变量必须是合法的 JSON 对象{...}结构且要求是对象而不是数组。解法用jq . 文件名或在线 JSON 校验器先验证变量内容常见错误用了单引号、缺少逗号/括号、中文引号、把注释写进了 JSON 里账号 ID 只允许小写字母、数字、-、_如bot_1、support大写或带点号都会被判非法各平台每个账号至少包含一个关键字段飞书appId/appSecret、钉钉clientId/clientSecret、企业微信botId/secret、QQ 机器人appId/clientSecret。单账号用户不必写 JSON直接使用对应的快捷变量如FEISHU_APP_IDFEISHU_APP_SECRET即可。4. 账号冲突报错App ID / clientId / botId 冲突怎么避免现象日志提示冲突可能导致消息路由错乱例如飞书 App ID 冲突钉钉 clientId / robotCode / Agent ID 冲突企业微信 botId / Agent ID 冲突QQ 机器人 AppID 冲突原因与解法init.sh 会对多账号做去重校验同一平台下两个账号如果填了相同的 App ID或对应平台的身份标识启动会直接报错退出。解法为每个账号使用各自平台的真实凭证不要用复制粘贴出来的同一套 Key 占位多账号 JSON 中检查每个账号块如channels.feishu.accounts、channels.dingtalk.accounts对应的环境变量的凭证是否一一对应。5. 401 / 403 错误怎么快速定位常见原因按命中率排序API_KEY填错、有多余空格或密钥已失效BASE_URL与实际服务不匹配协议对不上Provider 后端本身拒绝当前模型或当前账号额度、白名单中间代理层改写或丢失了认证头。最快解法最小配置验证法先把.env精简到只保留一组模型参数MODEL_ID、BASE_URL、API_KEY、API_PROTOCOL重启验证能通再逐步叠加MODEL2_*等多 Provider 配置。这样可快速区分密钥问题还是多 Provider 配置问题。完整模型与 Gateway 配置说明见 docs/configuration.md。6. 连接 AI Provider 失败BASE_URL 与协议对照表现象能启动但对话无响应或日志报模型调用失败。排查顺序检查项要点BASE_URLOpenAI 系协议通常需要带/v1后缀API_PROTOCOL必须与服务实际协议一致见下表API_KEY与 Provider 后台核对多 ProviderMODEL2_*、MODEL3_*是否每组都填完整localhost连不上优先改用127.0.0.1协议适用场景Base URL 习惯openai-completionsOpenAI、Gemini 等最常见方式需要/v1openai-responsesOpenAI 新版 Beta需要/v1google-generative-aiGemini 原生不需要/v1anthropic-messagesClaude 原生不需要/v1如果你是通过中间 API 网关如 AIClient-2-API接入可参考 docs/aiclient-2-api.md 的两种协议示例。7. PRIMARY_MODEL 写了模型还是不对看归一化规则现象配置了PRIMARY_MODEL或IMAGE_MODEL_ID实际运行的模型却不听话。归一化规则init.sh不带/时自动补全为default/模型名带/且前缀是已知 Provider 名视为完整引用原样使用带/但前缀不是已知 Provider 名会被整体当作default/...处理。正确示例MODEL_IDqwen3.5-plus MODEL2_NAMEaliyun MODEL2_MODEL_IDqwen-max,qwen3.5-plus PRIMARY_MODELaliyun/qwen3.5-plus IMAGE_MODEL_IDdefault/qwen3.5-plus 注意MODEL_ID里的值本身可能带/如dashscope/qwen3.5-plus此时首段是模型名的一部分归一化时会补default/前缀写引用时要以实际 Provider 名为准。8. 某个平台渠道没生效对照必需环境变量清单现象启动后机器人某个平台飞书/钉钉/QQ/企业微信始终不在线。原因init.sh 会根据必需环境变量是否齐全自动启用或禁用渠道缺字段时对应插件会被自动禁用日志中出现 环境变量缺失已禁用渠道。各平台必需变量速查平台单账号必需变量多账号替代飞书FEISHU_APP_IDFEISHU_APP_SECRETFEISHU_ACCOUNTS_JSON钉钉DINGTALK_CLIENT_IDDINGTALK_CLIENT_SECRETDINGTALK_ACCOUNTS_JSONQQ 机器人QQBOT_APP_IDQQBOT_CLIENT_SECRETQQBOT_BOTS_JSON企业微信WECOM_BOT_IDWECOM_SECRETWECOM_ACCOUNTS_JSONNapCat(微信)NAPCAT_REVERSE_WS_PORT—补全变量后执行docker compose up -d --force-recreate重建即可。所有变量含义见 .env.example 的注释。9. 飞书官方插件没装上 / plugin not found 怎么解现象日志报plugin not found: openclaw-lark或飞书官方插件始终未启用。原因官方插件安装命令npx -y larksuite/openclaw-lark-tools install是交互式流程无法在镜像构建阶段自动完成所以镜像只准备好运行环境。正确解法使用独立工具容器项目特意提供了openclaw-installer工具容器见 docker-compose.yml避免污染主服务docker compose up -d openclaw-gateway docker compose --profile tools up -d openclaw-installer docker exec -it openclaw-installer bash su node npx -y larksuite/openclaw-lark-tools install安装完成后在.env中设置FEISHU_OFFICIAL_PLUGIN_ENABLEDtrue再重建容器。完整流程见 docs/quick-start.md版本不匹配时可先执行npx -y larksuite/openclaw-lark-tools update。微信官方插件同理安装命令为npx -y tencent-weixin/openclaw-weixin-clilatest install流程见 docs/wechat.md。10. 飞书机器人能发消息但收不到消息怎么办这是配置在飞书开放平台后台侧的问题与容器无关按顺序核对 4 项事件接收方式是否选择了使用长连接接收事件事件订阅是否订阅了im.message.receive_v1接收消息事件权限审核相关消息权限是否已申请并通过审核安装位置机器人是否真的安装到了你要用的聊天或群组只加好友/只加一个群其他群收不到。使用飞书官方插件时还要确认交互式安装已完成见问题 9而不是只设置了环境变量。附3 条日常排障黄金命令场景命令看启动与运行日志docker compose logs -f openclaw-gateway进入容器排查记得切用户docker compose exec openclaw-gateway /bin/bash后su node修改配置后强制重建docker compose up -d --force-recreate两个容易踩的细节进入容器后先su node再执行 OpenClaw 相关命令插件安装、配对审批、查看用户目录配置都要用node用户才与实际运行环境一致参见 docs/faq.mdGateway 默认监听端口18789、绑定0.0.0.0。若连接不上确认端口未被占用、安全组已放行仅本地访问建议在.env设置DOCKER_BIND127.0.0.1。参考资料常见问题总览docs/faq.md配置指南docs/configuration.md快速开始与升级docs/quick-start.md高级运行方式docs/advanced.md开发者说明docs/developer-notes.md配置文件示例openclaw.json.example部署编排docker-compose.yml初始化脚本init.sh【免费下载链接】openclaw-china-dockerOpenClaw 的中国IM平台整合Docker版本预装并配置了飞书、钉钉、QQ机器人、企业微信等主流中国IM软件的插件让您可以快速部署一个支持多个中国IM平台的 AI 机器人网关项目地址: https://gitcode.com/gh_mirrors/op/openclaw-china-docker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考