context-mode 在 OpenClaw 安装插件时报 “openclaw.json not found“ 怎么排查？-平芜编程栈

context-mode 在 OpenClaw 安装插件时报 "openclaw.json not found" 怎么排查？

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode

在 context-mode 项目目录里执行npm run install:openclaw安装 OpenClaw 插件时，安装脚本会在 preflight 检查阶段直接退出，并打印类似这样的信息：

✗ /openclaw/openclaw.json not found. Start OpenClaw once first, then re-run this script.

（上面的路径是文档示例，实际打印的是你当前状态目录下的完整路径。）

这个报错的成因在安装脚本里写得很明确：脚本把$OPENCLAW_STATE_DIR/openclaw.json当作 OpenClaw 的唯一配置文件，确认文件存在之后才会继续写入插件注册项；而这个文件是 OpenClaw首次启动时自己创建的。所以只要出现过这个错误，原因只有两种：OpenClaw 从未被启动过，或者脚本使用的状态目录路径与 OpenClaw 实际存放状态的位置不一致。下面的排查就围绕这两条走。

先确认你看到的是哪条报错

install-openclaw-plugin.sh 的 preflight 按顺序检查三件事：node在 PATH 中 → 状态目录存在 → 状态目录下存在openclaw.json。因此第一步是分清你收到的是下面哪一条（两者均为脚本原文输出）：

报错信息	含义
`✗ <state-dir>/openclaw.json not found.`	状态目录存在，但`openclaw.json`还没被创建——最常见于 OpenClaw 从未启动过
`✗ OPENCLAW_STATE_DIR (<state-dir>) does not exist. Is OpenClaw installed?`	状态目录本身不存在——传给脚本的路径不是 OpenClaw 的状态目录

另外，如果第一步就失败，还会看到✗ node is required but not found in PATH，先解决 Node.js 不在 PATH 的问题再继续（README.md 要求 Node.js 22+，适配器文档要求 Node.js 在 PATH 中）。

情况一：状态目录正确，但 openclaw.json 不存在

这是 docs/adapters/openclaw.md 中列出的最常见问题：在从未启动过 OpenClaw 之前就去安装 context-mode。处理方式：

先启动一次 OpenClaw，首次启动会创建openclaw.json：
```
openclaw gateway start
```
回到 context-mode 项目目录，重新执行安装：
```
npm run install:openclaw
```

重新执行前，如果是在 Windows 上操作，注意install:openclaw脚本要求 bash 环境（Git Bash 或 WSL），直接在 Windows 原生 shell 运行会报错退出。

情况二：状态目录路径不对

安装脚本使用的状态目录默认是/openclaw，同时也接受环境变量OPENCLAW_STATE_DIR或命令行参数。README.md 给出的常见存放位置是：

Docker—/openclaw（默认值）；
本地安装—~/.openclaw，或你自行设置的OPENCLAW_STATE_DIR位置。

如果 OpenClaw 其实已经启动过、只是状态不在默认路径，把路径作为参数传给安装命令即可。下面命令中的/path/to/state替换为你的实际状态目录：

npm run install:openclaw -- /path/to/state

拿不准位置时，先检查~/.openclaw和/openclaw这两个候选目录：适配器文档建议，通过 npm（而非克隆仓库）安装 OpenClaw 的用户尤其要先确认状态实际存在哪里。docs/adapters/openclaw.md 还给出了等价的手动安装方式，适合自定义环境：

bash scripts/install-openclaw-plugin.sh [OPENCLAW_STATE_DIR]

重跑安装后如何验证

preflight 通过之后，脚本会依次执行：构建（npm install、npm run build、better-sqlite3原生模块重建）、把扩展写入<state-dir>/extensions/context-mode/、清理 jiti 缓存、用openclaw plugins list验证插件被发现、向openclaw.json写入plugins.entries["context-mode"]与 MCP sidecar 条目（由 register-openclaw-config.mjs 完成，幂等）、最后给运行中的 gateway 发 SIGUSR1 触发重启。注意这个过程中脚本会写入 OpenClaw 状态目录、修改openclaw.json，并在/tmp/jiti/下删除 context-mode 相关的旧编译缓存；已有 gateway 进程会收到 SIGUSR1 并重启。

根据脚本输出判断结果：

✓ context-mode discovered— 脚本执行openclaw plugins list时找到了插件；
✓ done — context-mode plugin installed and active— 安装完成；
如果看到的是⚠ could not verify discovery (openclaw not in PATH or plugin not found) — continuing anyway，说明脚本无法确认发现（openclaw 不在 PATH 或没找到插件），它会继续执行，此时需要手动验证：
```
openclaw plugins list
```
确认列表中出现了context-mode；
如果看到的是⚠ gateway not running — start it manually: OPENCLAW_STATE_DIR=<state-dir> openclaw gateway start，说明 gateway 没在运行，按脚本打印的命令手动启动，把环境变量值替换为你的状态目录。

最后做端到端确认：README.md 的验证方式是打开一个 Pi Agent 会话，输入ctx stats，工具能响应即说明插件已加载。

边界与其他情况

这个安装错误本身与 OpenClaw 版本无关，但适配器要求OpenClaw >2026.1.29：更早版本上通过api.on()注册的生命周期钩子可能静默失效，这是安装成功之后才会遇到的另一类现象，适配器会退化为从 SQLite 已持久化事件重建会话快照，不会崩溃，只是压缩恢复精度下降。
如果openclaw.json问题解决后遇到“插件已加载但 agent 工具列表里缺少ctx_*工具”，那是另一条排查路径：ctx_*工具由mcp.servers.context-mode声明的 MCP sidecar 提供，需按 docs/adapters/openclaw.md 对应小节用openclaw mcp list检查、必要时用openclaw mcp set context-mode ...补上该条目，再openclaw gateway restart。