启动aionclaw失败时，应先查看命令行控制台实时输出（加--debug参数），再检查本地main.log和gateway.log日志，最后确认openclaw子服务进程及日志；控制台错误最及时，日志文件提供结构化快照，子服务日志揭示底层原因。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
启动 AionClaw 失败时，日志不是随便打开一个就行——控制台输出是第一手证据，它没来得及写进文件就崩溃了；而本地 logs 目录里的 main.log 和 gateway.log 是结构化快照，能告诉你服务到底跑到了哪一步、卡在了模型加载还是端口绑定。错过这两处，等于闭着眼排查。
先盯住命令行控制台的实时输出
启动失败最及时的线索永远在终端窗口里：AionClaw 启动过程极短，一旦出错，错误堆栈会直接刷屏并退出，根本来不及落盘到文件。这一步漏看，后面翻日志全是“服务未启动”的空记录。
打开 PowerShell（Windows）或 Terminal（macOS），进入 AionClaw 安装目录，执行：./AionClaw.exe --debug（Windows）或 ./AionClaw --debug（macOS）。
注意：不加 --debug 参数，很多关键初始化错误会被静默吞掉，只留一行“failed to start”，你根本不知道它连配置都没读完。
再查 %APPDATA%\AionClaw\logs 或 ~/Library/Application Support/AionClaw/logs
如果控制台一闪而过或已关闭，立刻去本地日志目录找补救证据。Windows 用户路径是 %APPDATA%\AionClaw\logs，macOS 用户是 ~/Library/Application Support/AionClaw/logs。
进入 latest 子文件夹，用记事本或 VS Code 打开 main.log —— 这是主进程生命周期日志，记录从加载 config.json 到尝试启动 Gateway 的全过程。
重点搜索三类关键词：ERROR、panic、failed to bind。如果看到 failed to bind address 0.0.0.0:3000，说明端口被占；如果只有 config validation failed 但无后续，大概率是 API Key 格式错误或 Base URL 少了 https:// 前缀。
最后确认 OpenClaw 子服务是否独立运行
方法一：检查进程是否存在
Windows 执行：tasklist | findstr openclaw；macOS/Linux 执行：ps aux | grep openclaw。若返回结果为空，说明 AionClaw 并未拉起底层 OpenClaw 实例，问题出在自身启动链断裂，此时 main.log 是唯一可信源。
方法二：手动查看子服务日志
若进程存在，进入 OpenClaw 安装目录下的 logs/ 子文件夹，打开 openclaw.log。这里会暴露更底层的问题，比如 WSL2 环境校验失败（could not safely verify the WSL2 environment）、Docker daemon 未运行、或模型平台连接超时。这类错误在 AionClaw 的 main.log 里通常只显示为 subprocess exited with code 1，真正原因藏在这里。
