说实话我第一次在机器上部署OpenClaw的时候就差点在无法启动这一步被劝退。安装脚本跑得很顺依赖也装完了配置填好之后我满怀期待敲下启动命令——结果进程撑了不到三秒直接消失。再启动一次日志里冒出Gateway服务的报错然后整个平台又安静了。当时我的表情大概就和很多第一次接触OpenClaw的人一样这到底是哪一步出了问题后来反反复复装了几套环境踩遍了启动阶段的坑我才发现OpenClaw的启动困难户绝大多数病因都集中在同一个节点上——Gateway服务。它相当于这个个人AI智能体平台的内部调度中枢所有模型请求、工具调用、外部连接都要从它这里过。Gateway起不来OpenClaw整体就表现为无法启动。这篇文章就把我这一路排查的经验完整写下来。无论你是Windows WSL2配合Companion部署还是Ubuntu直接安装只要遇到启动即退出、端口无响应、模型路由报错这类问题都可以按下面的思路一层一层往下查。1. 先别急着重装OpenClaw启动失败的第一现场判读1.1 三种最常见的启动失败形态在动手改任何配置之前先把你的故障归个类。我见过太多人一遇到启动失败就删了重装结果同一个坑踩三次。OpenClaw的启动失败其实分三种形态每一种对应的排查方向完全不同。第一种是进程启动后立即退出。你运行启动命令终端里刷了几行日志然后进程就没了回到命令行提示符。这种情况十有八九出在配置解析阶段——YAML缩进错了、环境变量没设置、必填字段缺失程序启动时校验没过直接自杀退出。第二种是主进程还活着但Gateway端口始终不通。你能看到进程在但请求发不过去客户端或界面一直提示连接失败。这种情况优先查端口占用、WSL2网络模式、Companion进程的通信链路。第三种最隐蔽——进程正常、端口也通但一发起对话就报模型相关的错误比如后面要重点讲的doesnt look like an anthropic model这种看起来完全不像人话的提示。这类问题不在启动本身而在模型路由配置。我的建议是遇到故障先别慌按照下面的表格对号入座。故障形态典型表现优先排查方向启动即退出进程秒退、无有效日志配置文件语法、环境变量、依赖版本端口无响应进程在但连接失败端口占用、WSL2网络、Companion链路请求报错启动正常但对话失败模型路由、API Key、模型格式1.2 五分钟定位法先分清是安装问题还是运行问题给故障归类之后再用一套固定的命令把现场信息抓下来。这套命令我每次都跑五分钟内基本能确定问题大致范围。# 确认主程序版本和可执行文件是否完整 openclaw --version # 确认进程是否真的还在 ps aux | grep openclaw # 确认Gateway端口是否在监听 ss -tlnp | grep 8765 # 抓最近的日志尾巴 tail -n 100 ~/.openclaw/logs/gateway.logWindows环境下对应的命令是 PowerShell 里的netstat -ano | findstr :8765和tasklist /FI PID eq 进程号。执行完这一轮你至少能区分两件事是主程序压根没起来还是主程序起来了但Gateway没起来。这两个范围对应的修复手段完全不同混在一起排查会非常浪费时间。这里顺便说一个很多新手会犯的错误日志不看凭感觉猜。我在不少群里看到有人贴一句报错就问怎么办其实日志文件里通常已经写明了失败原因。OpenClaw的日志做得不算差问题只在于你要知道去哪看、按什么顺序看。到第6节我会把日志的位置和阅读顺序单独讲清楚。2. Gateway服务才是真正的门卫解析它为什么总在启动阶段掉链子2.1 Gateway在OpenClaw里到底干什么你得先理解Gateway在整个架构里的位置排查思路才立得住。打个比方OpenClaw的智能体本体就像一个前台经理它能理解你的指令、安排任务、调用工具但经理不可能自己同时对接所有供应商它把请求全部交给一个中转调度室这个调度室就是Gateway。Gateway负责的事包括把你发给智能体的消息路由到正确的模型服务商比如Anthropic的Claude或者本地跑的Qwen管理各个模型服务商的连接和密钥处理请求鉴权以及在多个模型之间做切换和流量分配。像Obsidian笔记集成这类外部工具请求同样要从Gateway走。换句话说主程序负责想Gateway负责通。Gateway挂了主程序就算活得好好的也一个消息都发不出去——表现出来就是无法启动或启动后不可用。理解了这层关系你就能明白为什么那么多启动故障最后都指向Gateway它是所有外部通信的必经之路任何一个环节断了它都是第一个发作的。2.2 端口占用与进程残留最常见的隐形杀手Gateway起不来的第一个高发原因不是配置而是端口被占。很多人包括我在调试过程中反复重启OpenClaw上一轮的Gateway进程没被干净地回收新的进程抢不到端口启动逻辑直接判定失败退出。如果你配置了Gateway集群多实例每个实例必须分配不同端口否则后启动的实例必然失败。排查方式很简单# Linux查看端口占用 ss -tlnp | grep 8765 # Windows查看端口占用 netstat -ano | findstr :8765如果发现端口被一个无名的旧进程占着先别急着kill。看一下那个进程的命令行确认是不是之前残留的Gateway进程确认后杀掉再重启。Windows下可以用taskkill /PID 进程号 /FLinux下用kill -9 进程号。另外还有一个容易被忽略的点有些版本的Gateway在启动时会先检查端口是否被占用占用就直接退出但不写明显错误日志只会在日志里留一行类似Address already in use的记录。如果你看到这行基本可以锁定端口冲突。2.3 配置文件的Gateway段一丁点语法错误都会让服务直接退出第二个高发原因是配置文件里的Gateway段落出了问题。OpenClaw的配置一般用YAML格式YAML这个格式对缩进极其敏感多一个空格、少一个冒号解析器都可能把整个配置读成一堆无效字段然后Gateway启动校验失败。一个典型的Gateway配置段大概长这样不同版本字段名略有差异以你手头版本的示例配置为准gateway: host: 127.0.0.1 port: 8765 routes: - name: anthropic-main provider: anthropic model: claude-sonnet-4-20250514 api_key: ${ANTHROPIC_API_KEY}注意几个细节routes下面每个路由项用-开头而且-后面必须有一个空格api_key引用环境变量用${变量名}的写法如果这个环境变量没设置启动阶段就会报错host如果是127.0.0.1那只有本机能访问Gateway如果你想从别的机器或子系统访问需要改成0.0.0.0。这里有个实操技巧改完配置后先单独解析一下配置文件确认语法没问题再启动。很多莫名其妙的启动失败就是配置文件多了一个不可见字符导致的。3. Windows部署的独家暗坑WSL2环境与Companion配置互相拖后腿3.1 WSL2状态检查别再忽略PowerShell的提示在Windows上部署OpenClaw官方推荐路线基本是WSL2 Windows Companion。这个组合的好处是兼容性好坏处是坑也多——特别是WSL2本身的状态一旦有问题OpenClaw的启动就会变得扑朔迷离。最常见的场景你下载了安装包按教程一步步来结果启动时提示无法安全验证WSL2环境之类的话。很多人这时候就懵了以为是OpenClaw的问题其实先要检查WSL2本身。在PowerShell里按顺序执行# 查看WSL整体状态 wsl --status # 查看已安装的发行版和运行状态 wsl --list --verbose # 如果内核版本太老更新一下 wsl --update诊断的关键在于wsl --status的输出。如果它显示默认版本是1代或者某个发行版处于Stopped状态OpenClaw的Companion连不上子系统自然就表现为无法启动。还有个高频问题WSL2默认分配的内存不够OpenClaw启动时报内存不足但报错信息写得很隐晦。解决方法是在用户目录下建一个.wslconfig文件把内存和CPU放开一些[wsl2] memory8GB processors4 swap4GB改完在PowerShell里执行wsl --shutdown让它生效再重新启动OpenClaw。3.2 Windows Companion连接失败权限、防火墙与路径Companion是Windows和WSL2之间的桥梁负责把Windows侧的剪切板、文件、窗口控制等能力暴露给运行在Linux里的OpenClaw智能体。Companion连不上OpenClaw虽然能启动但很多功能是残废的交互上表现为假启动。Companion连接失败的原因我碰到过的主要有三类。第一类是权限不足Companion需要以正常用户权限跑有时候还要在系统设置里放行辅助功能权限第二类是防火墙拦截Windows Defender或第三方安全软件会把Companion的本地端口通信当成可疑行为需要在防火墙规则里显式放行第三类是路径问题Companion依赖的辅助脚本或工作目录如果包含中文或特殊字符某些版本的进程会直接熄火。这三类问题的共同特征是日志里能看到Companion尝试连接但反复超时。排查时先确认Companion进程在不在再看它在日志里报的端口然后用netstat确认这个端口是否真的被监听。一般来说端口通了Companion和WSL2基本就能握手成功。3.3 终端进程异常conpty/winpty的连带影响还有一个看起来跟OpenClaw无关、实际上能让你卡半天的问题终端本身炸了。在Windows上跑OpenClaw时很多人用的是VSCode集成终端或Windows Terminal。如果终端启动时提示终端进程启动失败: 启动期间发生本机异常(无法启动 conpty)或者已移除 winpty那你的命令行环境本身就有问题OpenClaw的启动脚本在这种终端里跑不出正常结果。这类问题的根源通常是终端组件的版本和系统不匹配或者之前的终端配置被改动过。处理办法比较粗暴但有效把集成终端恢复默认设置或者换一个终端软件。我在Windows上调试OpenClaw时遇到终端异常会直接改用PowerShell原生的独立窗口绕开IDE集成终端的二次封装很多莫名其妙的启动失败瞬间就消失了。4. 模型路由与Anthropic格式报错看得懂报错才能对症下药4.1 doesnt look like an anthropic model到底在说什么在OpenClaw的启动故障里最让人头疼的是这一条报错——doesnt look like an anthropic model: expected a gateway model route。我第一次看到这个报错的时候反应是这说的是什么。其实这句话翻译成人话是这样的OpenClaw的智能体核心在内部默认使用Anthropic的消息格式说话它需要经由Gateway找到一个符合Anthropic格式的模型路由。如果你的Gateway路由表里配置的某个路由指向的模型服务商不是Anthropic或者模型格式不兼容系统在启动校验时就会抛出这条报错。换句话说这个报错不是说你没有配模型而是说你配的模型路由长得不像系统想要的那个。常见原因有两种一是你把主模型直接指定成了某个本地模型的名称但该模型对应的路由没有声明为与Anthropic格式兼容二是路由表里压根没有匹配的条目系统找不到任何能用的默认路由。4.2 模型路由表把请求送到正确的模型网关理解了报错的含义修复就简单了——检查路由表。路由表是Gateway用来决定哪个模型请求走哪条路的配置。拿我目前用的配置举例gateway: host: 127.0.0.1 port: 8765 routes: - name: anthropic-primary provider: anthropic model: claude-sonnet-4-20250514 api_key: ${ANTHROPIC_API_KEY} - name: local-openai-compatible provider: openai-compatible base_url: http://127.0.0.1:11434/v1 model: qwen2.5:3b default_route: anthropic-primary关键点在最后一行default_route。它指定了路由表里谁兜底。如果你的default_route指向了local-openai-compatible而主程序又期望一个Anthropic格式的模型就可能触发上面那条报错。修的时候优先确认三件事路由的类型字段是不是写对了default_route指向的路由是不是你实际想用的模型对应的API Key环境变量是不是已经填进环境里了。我见过很多人配置都写对了唯独忘了导出环境变量Gateway启动后拿不到密钥模型路由校验直接失败。4.3 本地模型接入时的路由写法如果你跟我一样不想所有请求都走云端模型想接入本地跑的Qwen这类模型路由写法有一个要点本地模型多数提供的是OpenAI兼容的API而不是Anthropic格式。那Gateway就得做一次格式转换把内部请求翻译成OpenAI风格再发出去。这种转换功能一般由路由类型字段控制。把provider写成openai-compatiblebase_url指向本地服务的地址本地大模型工具默认开在11434端口model填模型名。OpenClaw的Gateway拿到请求后会自动做协议翻译你的智能体就能用Anthropic格式的思维模型去指挥一个本地小模型干活。这里有个经验之谈接入本地模型后启动也许没问题但对话响应可能特别慢甚至超时报错。这不一定是配置问题更可能是本地模型本身的推理速度瓶颈。排查的时候别把矛头全指向Gateway先单独调一下本地模型的接口确认它本身响应正常再回来查路由。5. Node.js与依赖版本版本错位引发的连锁翻车现场5.1 为什么OpenClaw对Node生态这么敏感OpenClaw的Gateway组件以及大量工具集成建立在Node.js生态上这意味着你的Node版本、npm版本、以及node_modules里依赖的实际版本共同决定了很多故障会不会发生。Node生态有一个特点不同大版本之间的行为差异很大而且依赖安装时会生成锁文件锁文件和实际环境的错位经常触发启动阶段的诡异报错。我遇到过一个非常典型的场景一台机器上原来装着Node 16后来升到Node 20OpenClaw的依赖里有些包在Node 16下能跑在Node 20下就会在启动时抛错。报错信息五花八门有的指向某模块找不到有的指向某API不存在反正第一眼绝对看不出是版本问题。5.2 从报错反推版本问题一条可复现的排查链路当你怀疑是版本问题的时候不要慌着重装按这条链路一步步确认# 第一步确认Node和npm的实际版本 node --version npm --version # 第二步查OpenClaw要求的版本范围看项目说明或package.json npm ls openclaw/core # 第三步检查关键依赖是否完整 npm ls --depth0如果某个依赖显示invalid或者UNMET DEPENDENCY那就是典型的依赖树损坏。解决思路是清理后重装注意不是装到一半中断也不是简单重复一遍npm installrm -rf node_modules package-lock.json npm cache clean --force npm install把锁文件一起删掉会让npm重新解析依赖树这通常能解决一大批莫名其妙启动不了的问题。代价是安装时间变长但比起反复试错这点时间值得花。5.3 依赖缓存损坏的修复思路还有一种情况依赖本身没问题但npm的本地缓存坏了。这种情况常见于安装过程中网络波动或磁盘空间不足。npm cache clean --force可以在不动node_modules的情况下先清掉缓存然后重新执行安装。另外提醒一句如果你在Windows上通过WSL2跑OpenClawNode的安装位置和路径必须注意。WSL2里有一个比较经典的问题——你装了Windows版Node然后在Linux子系统里执行node可能调用的还是Windows的那个导致路径和权限行为完全不符合预期。建议在WSL2内单独安装Linux版Node并且在~/.bashrc里确认优先级避免PATH混乱。6. 从日志真相到修复落地一条完整的Gateway排障实操链路6.1 日志在哪里看前面的章节说了很多原因但具体到你的机器上到底是哪一个最终要靠日志来定罪。OpenClaw不同部署方式下日志位置不一样我先列出最常见的几个部署方式日志路径说明Ubuntu/Linux直接安装~/.openclaw/logs/gateway.log默认用户目录下systemd服务方式journalctl -u openclaw-gateway -f用日志系统统一捕获Docker方式docker logs 容器名看容器标准输出Windows WSL2WSL2内的Linux日志路径先在子系统里执行wsl进入阅读日志有个顺序技巧先看最后的启动阶段日志找有没有ERROR、FATAL级别的记录再看服务有没有打印出监听地址和端口最后看有没有伴随的异常堆栈。有堆栈就优先看堆栈的第一行那里通常藏着真正的失败原因。6.2 一次真实的排查过程复盘拿我最近一次帮朋友排查的经历当例子。现象是OpenClaw启动后界面能打开但一发送消息就报Gateway连接失败。我按顺序做了四步。第一步查进程和端口发现主进程和Gateway进程都在但Gateway监听的是127.0.0.1:8765而界面请求发往的是另一个端口。第二步看配置发现配置文件里Gateway端口写的是8866和环境实际监听的8765对不上——配置文件改过但进程是旧配置启动的。第三步杀掉所有OpenClaw进程重新启动日志显示监听端口变成了8866但界面还是报错。第四步仔细看日志发现有一行提示CORS配置不允许来自界面地址的跨域请求于是把Gateway配置里的允许来源加上界面的地址段重启后一切正常。这个案例很好地说明了排障的顺序不要一上来就怀疑最深奥的问题先把端口、进程、配置、日志这些最基础的信息验一遍。八成故障都出在这些笨问题上。6.3 修复完成后的验证清单修完之后别急着宣称好了用下面这套清单做一次完整验证每一步通过再继续下一步。进程存活验证ps aux | grep openclaw能看到主进程和Gateway进程都在。端口监听验证ss -tlnp | grep 端口能看到Gateway正在监听。健康检查验证curl http://127.0.0.1:端口/health返回正常状态码不同版本路径可能不同。模型路由验证发一个最小请求到Gateway确认能拿到模型响应而不是路由错误。端到端验证通过OpenClaw的客户端或命令行真正发起一次对话确认整条链路通畅。如果前四步都过了但第五步失败问题基本锁定在模型路由或API Key上回到第4节查。如果第五步也过了说明故障已经修复可以放心去用。最后说个我自己的习惯每次排查OpenClaw启动故障我都会把当时的报错原文、日志片段、改动内容记在一个文档里。这看起来麻烦但第二次遇到同类问题时查找效率能提升好几倍。你大概率不会只装一次OpenClaw换机器、升级版本、换模型服务商都会让这些记录派上用场。如果你现在正被无法启动卡住按第1节的表格归个类再从对应章节往下查大概率半小时内能定位到病根。祝顺利。 
长河君 · 2026/10/3 3:51:57 · 阅读 1.2k OpenClaw启动失败排查指南：从Gateway到模型路由的完整解决方案
说实话我第一次在机器上部署OpenClaw的时候就差点在无法启动这一步被劝退。安装脚本跑得很顺依赖也装完了配置填好之后我满怀期待敲下启动命令——结果进程撑了不到三秒直接消失。再启动一次日志里冒出Gateway服务的报错然后整个平台又安静了。当时我的表情大概就和很多第一次接触OpenClaw的人一样这到底是哪一步出了问题后来反反复复装了几套环境踩遍了启动阶段的坑我才发现OpenClaw的启动困难户绝大多数病因都集中在同一个节点上——Gateway服务。它相当于这个个人AI智能体平台的内部调度中枢所有模型请求、工具调用、外部连接都要从它这里过。Gateway起不来OpenClaw整体就表现为无法启动。这篇文章就把我这一路排查的经验完整写下来。无论你是Windows WSL2配合Companion部署还是Ubuntu直接安装只要遇到启动即退出、端口无响应、模型路由报错这类问题都可以按下面的思路一层一层往下查。1. 先别急着重装OpenClaw启动失败的第一现场判读1.1 三种最常见的启动失败形态在动手改任何配置之前先把你的故障归个类。我见过太多人一遇到启动失败就删了重装结果同一个坑踩三次。OpenClaw的启动失败其实分三种形态每一种对应的排查方向完全不同。第一种是进程启动后立即退出。你运行启动命令终端里刷了几行日志然后进程就没了回到命令行提示符。这种情况十有八九出在配置解析阶段——YAML缩进错了、环境变量没设置、必填字段缺失程序启动时校验没过直接自杀退出。第二种是主进程还活着但Gateway端口始终不通。你能看到进程在但请求发不过去客户端或界面一直提示连接失败。这种情况优先查端口占用、WSL2网络模式、Companion进程的通信链路。第三种最隐蔽——进程正常、端口也通但一发起对话就报模型相关的错误比如后面要重点讲的doesnt look like an anthropic model这种看起来完全不像人话的提示。这类问题不在启动本身而在模型路由配置。我的建议是遇到故障先别慌按照下面的表格对号入座。故障形态典型表现优先排查方向启动即退出进程秒退、无有效日志配置文件语法、环境变量、依赖版本端口无响应进程在但连接失败端口占用、WSL2网络、Companion链路请求报错启动正常但对话失败模型路由、API Key、模型格式1.2 五分钟定位法先分清是安装问题还是运行问题给故障归类之后再用一套固定的命令把现场信息抓下来。这套命令我每次都跑五分钟内基本能确定问题大致范围。# 确认主程序版本和可执行文件是否完整 openclaw --version # 确认进程是否真的还在 ps aux | grep openclaw # 确认Gateway端口是否在监听 ss -tlnp | grep 8765 # 抓最近的日志尾巴 tail -n 100 ~/.openclaw/logs/gateway.logWindows环境下对应的命令是 PowerShell 里的netstat -ano | findstr :8765和tasklist /FI PID eq 进程号。执行完这一轮你至少能区分两件事是主程序压根没起来还是主程序起来了但Gateway没起来。这两个范围对应的修复手段完全不同混在一起排查会非常浪费时间。这里顺便说一个很多新手会犯的错误日志不看凭感觉猜。我在不少群里看到有人贴一句报错就问怎么办其实日志文件里通常已经写明了失败原因。OpenClaw的日志做得不算差问题只在于你要知道去哪看、按什么顺序看。到第6节我会把日志的位置和阅读顺序单独讲清楚。2. Gateway服务才是真正的门卫解析它为什么总在启动阶段掉链子2.1 Gateway在OpenClaw里到底干什么你得先理解Gateway在整个架构里的位置排查思路才立得住。打个比方OpenClaw的智能体本体就像一个前台经理它能理解你的指令、安排任务、调用工具但经理不可能自己同时对接所有供应商它把请求全部交给一个中转调度室这个调度室就是Gateway。Gateway负责的事包括把你发给智能体的消息路由到正确的模型服务商比如Anthropic的Claude或者本地跑的Qwen管理各个模型服务商的连接和密钥处理请求鉴权以及在多个模型之间做切换和流量分配。像Obsidian笔记集成这类外部工具请求同样要从Gateway走。换句话说主程序负责想Gateway负责通。Gateway挂了主程序就算活得好好的也一个消息都发不出去——表现出来就是无法启动或启动后不可用。理解了这层关系你就能明白为什么那么多启动故障最后都指向Gateway它是所有外部通信的必经之路任何一个环节断了它都是第一个发作的。2.2 端口占用与进程残留最常见的隐形杀手Gateway起不来的第一个高发原因不是配置而是端口被占。很多人包括我在调试过程中反复重启OpenClaw上一轮的Gateway进程没被干净地回收新的进程抢不到端口启动逻辑直接判定失败退出。如果你配置了Gateway集群多实例每个实例必须分配不同端口否则后启动的实例必然失败。排查方式很简单# Linux查看端口占用 ss -tlnp | grep 8765 # Windows查看端口占用 netstat -ano | findstr :8765如果发现端口被一个无名的旧进程占着先别急着kill。看一下那个进程的命令行确认是不是之前残留的Gateway进程确认后杀掉再重启。Windows下可以用taskkill /PID 进程号 /FLinux下用kill -9 进程号。另外还有一个容易被忽略的点有些版本的Gateway在启动时会先检查端口是否被占用占用就直接退出但不写明显错误日志只会在日志里留一行类似Address already in use的记录。如果你看到这行基本可以锁定端口冲突。2.3 配置文件的Gateway段一丁点语法错误都会让服务直接退出第二个高发原因是配置文件里的Gateway段落出了问题。OpenClaw的配置一般用YAML格式YAML这个格式对缩进极其敏感多一个空格、少一个冒号解析器都可能把整个配置读成一堆无效字段然后Gateway启动校验失败。一个典型的Gateway配置段大概长这样不同版本字段名略有差异以你手头版本的示例配置为准gateway: host: 127.0.0.1 port: 8765 routes: - name: anthropic-main provider: anthropic model: claude-sonnet-4-20250514 api_key: ${ANTHROPIC_API_KEY}注意几个细节routes下面每个路由项用-开头而且-后面必须有一个空格api_key引用环境变量用${变量名}的写法如果这个环境变量没设置启动阶段就会报错host如果是127.0.0.1那只有本机能访问Gateway如果你想从别的机器或子系统访问需要改成0.0.0.0。这里有个实操技巧改完配置后先单独解析一下配置文件确认语法没问题再启动。很多莫名其妙的启动失败就是配置文件多了一个不可见字符导致的。3. Windows部署的独家暗坑WSL2环境与Companion配置互相拖后腿3.1 WSL2状态检查别再忽略PowerShell的提示在Windows上部署OpenClaw官方推荐路线基本是WSL2 Windows Companion。这个组合的好处是兼容性好坏处是坑也多——特别是WSL2本身的状态一旦有问题OpenClaw的启动就会变得扑朔迷离。最常见的场景你下载了安装包按教程一步步来结果启动时提示无法安全验证WSL2环境之类的话。很多人这时候就懵了以为是OpenClaw的问题其实先要检查WSL2本身。在PowerShell里按顺序执行# 查看WSL整体状态 wsl --status # 查看已安装的发行版和运行状态 wsl --list --verbose # 如果内核版本太老更新一下 wsl --update诊断的关键在于wsl --status的输出。如果它显示默认版本是1代或者某个发行版处于Stopped状态OpenClaw的Companion连不上子系统自然就表现为无法启动。还有个高频问题WSL2默认分配的内存不够OpenClaw启动时报内存不足但报错信息写得很隐晦。解决方法是在用户目录下建一个.wslconfig文件把内存和CPU放开一些[wsl2] memory8GB processors4 swap4GB改完在PowerShell里执行wsl --shutdown让它生效再重新启动OpenClaw。3.2 Windows Companion连接失败权限、防火墙与路径Companion是Windows和WSL2之间的桥梁负责把Windows侧的剪切板、文件、窗口控制等能力暴露给运行在Linux里的OpenClaw智能体。Companion连不上OpenClaw虽然能启动但很多功能是残废的交互上表现为假启动。Companion连接失败的原因我碰到过的主要有三类。第一类是权限不足Companion需要以正常用户权限跑有时候还要在系统设置里放行辅助功能权限第二类是防火墙拦截Windows Defender或第三方安全软件会把Companion的本地端口通信当成可疑行为需要在防火墙规则里显式放行第三类是路径问题Companion依赖的辅助脚本或工作目录如果包含中文或特殊字符某些版本的进程会直接熄火。这三类问题的共同特征是日志里能看到Companion尝试连接但反复超时。排查时先确认Companion进程在不在再看它在日志里报的端口然后用netstat确认这个端口是否真的被监听。一般来说端口通了Companion和WSL2基本就能握手成功。3.3 终端进程异常conpty/winpty的连带影响还有一个看起来跟OpenClaw无关、实际上能让你卡半天的问题终端本身炸了。在Windows上跑OpenClaw时很多人用的是VSCode集成终端或Windows Terminal。如果终端启动时提示终端进程启动失败: 启动期间发生本机异常(无法启动 conpty)或者已移除 winpty那你的命令行环境本身就有问题OpenClaw的启动脚本在这种终端里跑不出正常结果。这类问题的根源通常是终端组件的版本和系统不匹配或者之前的终端配置被改动过。处理办法比较粗暴但有效把集成终端恢复默认设置或者换一个终端软件。我在Windows上调试OpenClaw时遇到终端异常会直接改用PowerShell原生的独立窗口绕开IDE集成终端的二次封装很多莫名其妙的启动失败瞬间就消失了。4. 模型路由与Anthropic格式报错看得懂报错才能对症下药4.1 doesnt look like an anthropic model到底在说什么在OpenClaw的启动故障里最让人头疼的是这一条报错——doesnt look like an anthropic model: expected a gateway model route。我第一次看到这个报错的时候反应是这说的是什么。其实这句话翻译成人话是这样的OpenClaw的智能体核心在内部默认使用Anthropic的消息格式说话它需要经由Gateway找到一个符合Anthropic格式的模型路由。如果你的Gateway路由表里配置的某个路由指向的模型服务商不是Anthropic或者模型格式不兼容系统在启动校验时就会抛出这条报错。换句话说这个报错不是说你没有配模型而是说你配的模型路由长得不像系统想要的那个。常见原因有两种一是你把主模型直接指定成了某个本地模型的名称但该模型对应的路由没有声明为与Anthropic格式兼容二是路由表里压根没有匹配的条目系统找不到任何能用的默认路由。4.2 模型路由表把请求送到正确的模型网关理解了报错的含义修复就简单了——检查路由表。路由表是Gateway用来决定哪个模型请求走哪条路的配置。拿我目前用的配置举例gateway: host: 127.0.0.1 port: 8765 routes: - name: anthropic-primary provider: anthropic model: claude-sonnet-4-20250514 api_key: ${ANTHROPIC_API_KEY} - name: local-openai-compatible provider: openai-compatible base_url: http://127.0.0.1:11434/v1 model: qwen2.5:3b default_route: anthropic-primary关键点在最后一行default_route。它指定了路由表里谁兜底。如果你的default_route指向了local-openai-compatible而主程序又期望一个Anthropic格式的模型就可能触发上面那条报错。修的时候优先确认三件事路由的类型字段是不是写对了default_route指向的路由是不是你实际想用的模型对应的API Key环境变量是不是已经填进环境里了。我见过很多人配置都写对了唯独忘了导出环境变量Gateway启动后拿不到密钥模型路由校验直接失败。4.3 本地模型接入时的路由写法如果你跟我一样不想所有请求都走云端模型想接入本地跑的Qwen这类模型路由写法有一个要点本地模型多数提供的是OpenAI兼容的API而不是Anthropic格式。那Gateway就得做一次格式转换把内部请求翻译成OpenAI风格再发出去。这种转换功能一般由路由类型字段控制。把provider写成openai-compatiblebase_url指向本地服务的地址本地大模型工具默认开在11434端口model填模型名。OpenClaw的Gateway拿到请求后会自动做协议翻译你的智能体就能用Anthropic格式的思维模型去指挥一个本地小模型干活。这里有个经验之谈接入本地模型后启动也许没问题但对话响应可能特别慢甚至超时报错。这不一定是配置问题更可能是本地模型本身的推理速度瓶颈。排查的时候别把矛头全指向Gateway先单独调一下本地模型的接口确认它本身响应正常再回来查路由。5. Node.js与依赖版本版本错位引发的连锁翻车现场5.1 为什么OpenClaw对Node生态这么敏感OpenClaw的Gateway组件以及大量工具集成建立在Node.js生态上这意味着你的Node版本、npm版本、以及node_modules里依赖的实际版本共同决定了很多故障会不会发生。Node生态有一个特点不同大版本之间的行为差异很大而且依赖安装时会生成锁文件锁文件和实际环境的错位经常触发启动阶段的诡异报错。我遇到过一个非常典型的场景一台机器上原来装着Node 16后来升到Node 20OpenClaw的依赖里有些包在Node 16下能跑在Node 20下就会在启动时抛错。报错信息五花八门有的指向某模块找不到有的指向某API不存在反正第一眼绝对看不出是版本问题。5.2 从报错反推版本问题一条可复现的排查链路当你怀疑是版本问题的时候不要慌着重装按这条链路一步步确认# 第一步确认Node和npm的实际版本 node --version npm --version # 第二步查OpenClaw要求的版本范围看项目说明或package.json npm ls openclaw/core # 第三步检查关键依赖是否完整 npm ls --depth0如果某个依赖显示invalid或者UNMET DEPENDENCY那就是典型的依赖树损坏。解决思路是清理后重装注意不是装到一半中断也不是简单重复一遍npm installrm -rf node_modules package-lock.json npm cache clean --force npm install把锁文件一起删掉会让npm重新解析依赖树这通常能解决一大批莫名其妙启动不了的问题。代价是安装时间变长但比起反复试错这点时间值得花。5.3 依赖缓存损坏的修复思路还有一种情况依赖本身没问题但npm的本地缓存坏了。这种情况常见于安装过程中网络波动或磁盘空间不足。npm cache clean --force可以在不动node_modules的情况下先清掉缓存然后重新执行安装。另外提醒一句如果你在Windows上通过WSL2跑OpenClawNode的安装位置和路径必须注意。WSL2里有一个比较经典的问题——你装了Windows版Node然后在Linux子系统里执行node可能调用的还是Windows的那个导致路径和权限行为完全不符合预期。建议在WSL2内单独安装Linux版Node并且在~/.bashrc里确认优先级避免PATH混乱。6. 从日志真相到修复落地一条完整的Gateway排障实操链路6.1 日志在哪里看前面的章节说了很多原因但具体到你的机器上到底是哪一个最终要靠日志来定罪。OpenClaw不同部署方式下日志位置不一样我先列出最常见的几个部署方式日志路径说明Ubuntu/Linux直接安装~/.openclaw/logs/gateway.log默认用户目录下systemd服务方式journalctl -u openclaw-gateway -f用日志系统统一捕获Docker方式docker logs 容器名看容器标准输出Windows WSL2WSL2内的Linux日志路径先在子系统里执行wsl进入阅读日志有个顺序技巧先看最后的启动阶段日志找有没有ERROR、FATAL级别的记录再看服务有没有打印出监听地址和端口最后看有没有伴随的异常堆栈。有堆栈就优先看堆栈的第一行那里通常藏着真正的失败原因。6.2 一次真实的排查过程复盘拿我最近一次帮朋友排查的经历当例子。现象是OpenClaw启动后界面能打开但一发送消息就报Gateway连接失败。我按顺序做了四步。第一步查进程和端口发现主进程和Gateway进程都在但Gateway监听的是127.0.0.1:8765而界面请求发往的是另一个端口。第二步看配置发现配置文件里Gateway端口写的是8866和环境实际监听的8765对不上——配置文件改过但进程是旧配置启动的。第三步杀掉所有OpenClaw进程重新启动日志显示监听端口变成了8866但界面还是报错。第四步仔细看日志发现有一行提示CORS配置不允许来自界面地址的跨域请求于是把Gateway配置里的允许来源加上界面的地址段重启后一切正常。这个案例很好地说明了排障的顺序不要一上来就怀疑最深奥的问题先把端口、进程、配置、日志这些最基础的信息验一遍。八成故障都出在这些笨问题上。6.3 修复完成后的验证清单修完之后别急着宣称好了用下面这套清单做一次完整验证每一步通过再继续下一步。进程存活验证ps aux | grep openclaw能看到主进程和Gateway进程都在。端口监听验证ss -tlnp | grep 端口能看到Gateway正在监听。健康检查验证curl http://127.0.0.1:端口/health返回正常状态码不同版本路径可能不同。模型路由验证发一个最小请求到Gateway确认能拿到模型响应而不是路由错误。端到端验证通过OpenClaw的客户端或命令行真正发起一次对话确认整条链路通畅。如果前四步都过了但第五步失败问题基本锁定在模型路由或API Key上回到第4节查。如果第五步也过了说明故障已经修复可以放心去用。最后说个我自己的习惯每次排查OpenClaw启动故障我都会把当时的报错原文、日志片段、改动内容记在一个文档里。这看起来麻烦但第二次遇到同类问题时查找效率能提升好几倍。你大概率不会只装一次OpenClaw换机器、升级版本、换模型服务商都会让这些记录派上用场。如果你现在正被无法启动卡住按第1节的表格归个类再从对应章节往下查大概率半小时内能定位到病根。祝顺利。