大文件上传问题排查与解决指南日期: 2026-07-01场景: OpenClaw WebChat 上传 113 MB docx 文件状态: ✅ 已解决问题概述上传 113 MB 的 Word 文档时遇到多层限制导致上传失败WebSocket payload 限制(100 MB)附件大小限制(20 MB)Node.js 内存溢出(OOM)错误链路分析错误 1: WebSocket payload 限制错误信息:warn gateway/ws error conn... remote192.168.121.114: Max payload size exceeded原因: OpenClaw WebSocket 层的默认 payload 限制为 100 MB排查命令:grep-rnmaxPayload\|100.*1024.*1024src/gateway/解决方案:修改src/gateway/server-constants.ts中的MAX_PAYLOAD_BYTES重新构建镜像docker compose build注意: 此限制在可能不是主要瓶颈因为后续错误显示文件已经通过了 WebSocket 层。错误 2: 附件大小限制关键瓶颈错误信息:Error: attachment 文件.docx: exceeds size limit (118512366 20971520 bytes)原因:resolveChatAttachmentMaxBytes()的默认值为 20 MB定位文件:src/gateway/chat-attachments.ts关键代码:exportconstDEFAULT_CHAT_ATTACHMENT_MAX_MB20;解决方案: 修改为 200 MB// src/gateway/chat-attachments.tsexportconstDEFAULT_CHAT_ATTACHMENT_MAX_MB200;// 从 20 改为 200验证命令:grep-nDEFAULT_CHAT_ATTACHMENT_MAX_MBsrc/gateway/chat-attachments.ts错误 3: Node.js 内存溢出错误信息:[8:0x215c3000] 103857 ms: Mark-Compact (reduce) 4034.8 (4100.1) MB原因: 处理 113 MB 文件时 Node.js 内存耗尽导致 WebSocket 连接超时断开排查命令:dockercompose logs openclaw-agent3--tail100|grep-EGC|Mark-Compact|OOM解决方案: 增加 Node.js 内存限制修改docker-compose.yml:openclaw-agent3:# ... 其他配置 ...command:-sh--c-python3 /home/node/.openclaw/workspace/scripts/file_server.py /tmp/server.log 21 exec node --max-old-space-size6144 dist/index.js gateway --bind ${OPENCLAW_GATEWAY_BIND:-lan} --port 18789关键参数:--max-old-space-size6144(6 GB)完整解决步骤1. 修改源码限制# 编辑源码文件visrc/gateway/chat-attachments.ts# 找到并修改第 64 行附近exportconst DEFAULT_CHAT_ATTACHMENT_MAX_MB200;# 原值为 202. 修改 Docker 配置# 编辑 docker-compose.ymlvidocker-compose.yml# 在 openclaw-agent3 的 command 部分添加 Node.js 内存参数command: -sh--c-python3 /home/node/.openclaw/workspace/scripts/file_server.py/tmp/server.log21execnode--max-old-space-size6144dist/index.js gateway--bind${OPENCLAW_GATEWAY_BIND:-lan}--port187893. 重新构建并重启# 重新构建镜像dockercompose build openclaw-agent3# 重启容器dockercompose up-dopenclaw-agent3# 查看日志确认启动成功dockercompose logs openclaw-agent3|tail-304. 验证重新上传大文件确认✅ 不再报 “exceeds size limit” 错误✅ 不再出现内存溢出✅ WebSocket 连接稳定配置对照表限制类型默认值修改后配置文件/源码位置是否需要重启WebSocket payload100 MB需源码修改src/gateway/server-constants.ts是重构建Chat attachment20 MB200 MBsrc/gateway/chat-attachments.ts是重构建Node.js heap~4 GB6 GBdocker-compose.ymlcommand是重启容器hooks.maxBodyBytes100 MB200 MBopenclaw.json是重启排查命令速查# 1. 查看限制相关代码grep-rnexceeds size limit\|DEFAULT_CHAT_ATTACHMENT_MAX_MBsrc/# 2. 查看内存使用dockercompose logs openclaw-agent3|grep-EGC|Mark-Compact|memory# 3. 查看容器内存限制dockercompose inspect openclaw-agent3|grep-A5Memory# 4. 实时查看日志dockercompose logs-fopenclaw-agent3# 5. 检查 Node.js 内存参数dockercomposeexecopenclaw-agent3psaux|grepnode最佳实践建议对于文件上传业务场景文件大小建议方案 20 MB直接上传无需修改20-100 MB修改DEFAULT_CHAT_ATTACHMENT_MAX_MB为 100100-200 MB修改为 200 增加 Node.js 内存到 6 GB 200 MB压缩后上传或使用外部存储长期优化建议流式处理: 修改文件处理逻辑使用流式读取而不是加载到内存分片上传: 实现大文件分片上传机制外部存储: 集成 OSS/S3只上传 URL监控告警: 添加内存使用监控提前预警相关文件源码:src/gateway/chat-attachments.tsDocker:docker-compose.yml配置:openclaw.json日志:.learnings/ERRORS.md经验总结多层限制: 大文件上传涉及多层限制WebSocket、应用层、系统层需要逐层排查日志是关键: 通过错误日志可以精确定位限制位置内存是瓶颈: 处理大文件时Node.js 内存往往是主要瓶颈源码修改必要: 某些限制是硬编码的必须修改源码并重新构建最后更新: 2026-07-01 17:05