OpenClaw 适配器深度指南在 Pi Agent 会话中落地 context-mode 沙箱路由与压缩恢复【免费下载链接】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-modecontext-mode 为 17 个主流 AI 编程 Agent 平台提供了统一的上下文窗口优化方案而 OpenClaw 适配器docs/adapters/openclaw.md负责将这一能力接入OpenClaw 网关下的Pi Agent会话通过拦截工具调用将高数据量操作路由进沙箱执行、把会话事件持久化到 SQLite 以便压缩compaction后恢复、并借助 MCP 边车暴露全套ctx_*工具。读完本文你将掌握该适配器的安装排障流程、OpenClaw 插件两套 Hook API 的正确用法、会话连续性Session Continuity的底层实现以及如何基于最低版本要求评估升级风险。OpenClaw 适配器在 context-mode 中的定位OpenClaw是一个管理 Agent 会话、扩展extension与工具路由的网关平台Pi Agent则是 OpenClaw 内置的编程 Agent运行在 OpenClaw 进程内提供 Read、Write、Edit、Bash 等软件开发工具。context-mode 的 OpenClaw 适配器只针对Pi Agent 会话挂接在tool_call:before阶段拦截工具调用把数据密集型操作路由进沙箱沙箱输出可削减约 98% 的上下文占用见 openclaw.plugin.json 的项目描述在tool_call:after阶段跟踪会话事件为后续压缩恢复准备快照。支持的配置形态Pi Agent 会话含 Read/Write/Edit/Bash 编码工具——完全支持是适配器的目标场景自定义 Agent同样具备编码工具——可能可用但未经过测试因为适配器依赖工具名与 Pi Agent 约定的匹配关系。平台能力矩阵适配器在 src/adapters/openclaw/index.ts 中声明了自身能力可直接对照理解其功能边界能力取值说明preToolUsetrue工具调用前拦截路由裁决postToolUsetrue工具调用后捕获事件preCompacttrue通过registerContextEngineownsCompaction管理压缩sessionStarttrue通过command:newHook 触发会话初始化canModifyArgstrue可在tool_call:before中原地修改参数canModifyOutputfalse不修改工具输出canInjectSessionContexttrue通过before_prompt_build生命周期钩子注入上下文对应测试 tests/adapters/openclaw.test.ts 逐项断言了这些能力标志。安装与前置条件快速安装npm run install:openclaw该命令实际执行scripts/install-openclaw-plugin.sh一次性完成构建、扩展目录部署、运行时注册与网关重启。前置条件Node.js 必须在 PATH 中构建与注册步骤依赖OpenClaw 必须至少启动过一次——安装脚本需要openclaw.json该文件在 OpenClaw 首次启动时生成OPENCLAW_STATE_DIR必须指向 OpenClaw 状态目录默认/openclaw可通过参数覆盖npm run install:openclaw -- /path/to/state手动安装适合高级用户或自定义部署bash scripts/install-openclaw-plugin.sh [OPENCLAW_STATE_DIR]脚本细节见 scripts/install-openclaw-plugin.sh。安装脚本内部做了什么从 scripts/install-openclaw-plugin.sh 的源码看安装共分 6 步构建npm installnpm run buildnpm rebuild better-sqlite3为系统 Node 重建原生绑定部署扩展将openclaw.plugin.json复制到$OPENCLAW_STATE_DIR/extensions/context-mode/并生成一个指向构建产物的index.ts桩文件OpenClaw 不跟随目录软链接所以必须是真实目录清理 jiti 缓存删除/tmp/jiti/下context-mode-index.*.cjs、build-adapters-openclaw-plugin.*.cjs等缓存文件避免旧编译产物残留在升级后继续生效验证发现调用openclaw plugins list检查context-mode是否被识别写入运行时配置委托 scripts/lib/register-openclaw-config.mjs 修改openclaw.json重启网关向node.*openclaw/dist/index.js进程发送SIGUSR1触发干净的重载若网关未运行则提示手动openclaw gateway start。第 5 步的配置写入scripts/lib/register-openclaw-config.mjs是幂等的且做了三件关键事移除遗留的plugins.load.paths条目历史上会造成插件重复注册确保context-mode同时出现在plugins.allow与plugins.entries{ enabled: true }注册mcp.servers.context-mode→{ command: node, args: [pluginRoot/server.bundle.mjs] }让 OpenClaw 以 MCP 边车方式拉起 MCP 服务器并暴露ctx_*工具。该逻辑对mcp.servers.context-mode采用“只覆盖command/args两个字段、保留其余字段”的保守策略避免覆盖用户自定义的env、cwd、timeout等配置。故障排查指南“openclaw.json not found”openclaw.json在 OpenClaw首次启动时才生成。这是“先装 context-mode、后启动 OpenClaw”的用户最常见的报错。解决方式先启动一次 OpenClawopenclaw gateway start再重跑安装脚本。“OPENCLAW_STATE_DIR (/path) does not exist. Is OpenClaw installed?”状态目录在预期路径不存在。若你是通过 npm而非 git clone安装的 OpenClaw需要确认其状态存储位置——常见路径为~/.openclaw或/openclaw然后显式传参npm run install:openclaw -- /path/to/state插件已安装但未加载清理 jiti 缓存后重启网关rm -f /tmp/jiti/context-mode-*.cjs若问题依旧用openclaw plugins list确认插件是否出现在列表中。插件加载了但 Agent 工具列表中没有ctx_*工具这是最容易混淆的一点插件的 Hook 通过api.on(...)/api.registerCommand(...)注册但Agent 可调用的ctx_*工具住在 MCP 服务器server.bundle.mjs里。OpenClaw 通过mcp.servers.context-mode声明将服务器作为 MCP 边车拉起才把这些工具暴露给 Agent。安装脚本第 5 步会自动写入该条目若你是手动配置需检查openclaw mcp list并补上openclaw mcp set context-mode \ {\command\:\node\,\args\:[\/absolute/path/to/context-mode/server.bundle.mjs\]} openclaw gateway restart重启后Agent 工具清单中应能看到context-mode__ctx_execute、context-mode__ctx_search、context-mode__ctx_fetch_and_index等OpenClaw 会给 MCP 来源的工具加上服务器名前缀。Hook 注册两套 API 与同步 register 契约适配器依据 OpenClaw 内部架构使用两套不同的注册 API这是最容易踩坑的地方api.on()—— 用于生命周期与工具 Hooksession_start、before_tool_call、after_tool_call、before_compaction、after_compaction、before_prompt_build、before_model_resolve。它们是带结构化负载的类型化事件发射器api.registerHook()—— 用于命令类 Hookcommand:new、command:reset、command:stop使用冒号分隔的事件名与通用 Hook 注册系统。用错 API例如用api.registerHook(before_tool_call, ...)会静默注册成功但永远不触发。这个区分至关重要。两类事件的常量定义集中在 src/adapters/openclaw/hooks.tsHOOK_EVENTStool_call:before/tool_call:after/command:new/command:reset/command:stop与LIFECYCLE_HOOKSsession_start/before_compaction/after_compaction/before_prompt_build/before_model_resolve等。同步 register() initPromise 模式OpenClaw静默丢弃register()的返回值——如果register()是 async 的在其中注册的所有 Hook 都会丢失。因此适配器采用 initPromise 模式同步返回异步初始化先行启动Hook 在首次触发时await该 Promise见 src/adapters/openclaw/plugin.tsregister(api): void { const initPromise (async () { /* async setup */ })(); api.on(after_tool_call, async (e) { await initPromise; // handle event }); }完整的 Hook 注册清单从 src/adapters/openclaw/plugin.ts 的实现看register()内共注册了以下内容Hook注册方式职责before_tool_callapi.on()路由裁决deny 时返回{ block, blockReason }modify 时原地改写paramsafter_tool_callapi.on()捕获会话事件并写入 SQLitecommand:new/command:reset/command:stopapi.registerHook()会话初始化 / 清理cleanupOldSessions(7)保留 7 天session_startapi.on()用 OpenClaw 的 sessionId 重键 DB 会话before_compactionapi.on()将事件冲刷为恢复快照after_compactionapi.on()递增 compact 计数before_model_resolveapi.on()捕获用户消息过滤系统包装消息before_prompt_buildp10api.on()向系统上下文注入恢复快照before_prompt_buildp5api.on()向系统上下文注入路由指令与技能引导session_endapi.on()会话结束前固化最终恢复快照subagent_spawningapi.on()为每个派生的子 Agent 注入路由块Context Engineapi.registerContextEngine()声明上下文引擎ownsCompaction: false/ctx-stats、/ctx-doctor、/ctx-upgradeapi.registerCommand()自动回复的斜杠命令会话连续性从工具调用到压缩快照状态一览Hook注册方法状态after_tool_callapi.on()正常before_compactionapi.on()正常session_startapi.on()正常command:newapi.registerHook()正常command:resetapi.registerHook()正常command:stopapi.registerHook()正常事件捕获链路after_tool_call处理时适配器先把 OpenClaw 的小写工具名映射为 Claude Code 的 PascalCase 约定src/adapters/openclaw/plugin.ts再交给通用的事件抽取器OpenClaw 工具名映射后execBashreadReadwriteWriteedit/apply_patchEditglobGlobgrep/searchGrep同时兼容 OpenClaw v2 与旧版的字段差异结果同时接受resultv2与output旧版错误同时接受字符串errorv2与布尔isError旧版。未识别的工具调用会以通用tool_call事件兜底入库保证事件流不断裂。session_start基于 sessionKey 的重键session_start事件携带sessionId与sessionKey形如agent:name:main。适配器用 src/adapters/openclaw/session-db.ts 的OpenClawSessionDB维护openclaw_session_map表若该 key 已有更早的 sessionId则调用renameSession()在一个事务内跨session_meta、session_events、session_resume、openclaw_session_map四张表整体改名确保网关重启重键后已积累的事件、元数据与恢复快照全部存活。压缩快照与注入before_compaction读取当前会话全部事件用buildResumeSnapshot()构建恢复快照并 upsertafter_compaction递增compact_countbefore_prompt_buildpriority 10仅在compact_count 0时把快照作为prependSystemContext注入一次resumeInjected标志防止同会话重复注入before_prompt_buildpriority 5注入动态生成的路由块带!-- context-mode: routing block injected (sessionID...) --可见标记与技能引导文本。优雅降级如果压缩 Hook 因 OpenClaw 版本过旧而无法触发适配器回退到DB 快照重建直接基于after_tool_call已持久化到 SQLite 的事件重建会话状态。该快照不如 PreCompact 路径精确但仍能保留关键状态活动文件、任务、错误。适配器不会在旧版本上崩溃只是压缩恢复质量下降。上游历史问题与最低版本要求已解决的上游问题Issue #4967—— 压缩 Hook 不触发被关闭为 #3728 的重复项修复已合入Issue #5513——api.on()注册的 Hook 不响应工具生命周期事件由 PR #9761 修复。最低版本OpenClaw 2026.1.292026-01-29 发布的版本是首个包含 PR #9761 的api.on()修复的版本因此适配器要求OpenClaw 2026.1.29。旧版本会坏掉什么通过api.on()注册的生命周期 Hook包括before_compaction、after_compaction、session_start以及工具拦截 Hook可能静默不触发。降级行为压缩 Hook 不触发时回退到 DB 快照重建见上一节适配器不会崩溃但压缩恢复质量降低。Workspace 路由多工作区会话隔离OpenClaw 网关上可能同时跑多个 Agent 工作区工具事件也可能跨会话交错投递。为此适配器内置了WorkspaceRoutersrc/adapters/openclaw/workspace-router.ts从 Pi Agent 会话元数据解析项目路径确保会话数据库与路由指令按工作区隔离从工具调用参数中按cwd file_path command的优先级提取/openclaw/workspace-name形态的路径依据sessionKey约定agent:name:main→/openclaw/workspace-name建立 workspace → sessionId 映射session_start时注册映射command:stop时移除映射after_tool_call先用工作区路径解析正确的 sessionId无匹配时才回退到闭包内 sessionId。同时OpenClawAdapter.getProjectDir()src/adapters/openclaw/index.ts按input.cwd OPENCLAW_PROJECT_DIR 环境变量 process.cwd()的优先级解析项目目录保证下游 Hook 在 worktree 场景或平台省略cwd字段时仍能拿到确定的 projectDir。ctx_* 工具面与 MCP 边车插件通过api.registerTool()暴露 11 个ctx_*工具src/adapters/openclaw/mcp-tools.ts与 openclaw.plugin.json 中contracts.tools一致ctx_execute、ctx_execute_file、ctx_index、ctx_search、ctx_fetch_and_index、ctx_batch_execute、ctx_stats、ctx_doctor、ctx_upgrade、ctx_purge、ctx_insight。这些工具与src/server.ts中 MCP 服务器注册的工具一一对应处理器是刻意保持轻薄的委托层——转调捆绑的 CLIcli.bundle.mjs避免把整个 MCP 服务器栈搬进 OpenClaw 进程、缩小插件爆炸半径。路由块引导 Agent 调用这些工具而工具真正执行时由mcp.servers.context-mode声明的 MCP 边车进程承载。每轮令牌与成本捕获OpenClaw 每轮turn会通过诊断事件总线发出一次model.usage事件携带完整的用量拆分input/output/cacheRead/cacheWrite与预计算的costUsd。注意原生的before_tool_call/after_tool_call中继只携带审批/策略数据不含令牌用量所以用量捕获不能从工具 Hook 获得。适配器通过onDiagnosticEvent()或在 SDK 缺失时经计算说明符动态导入openclaw/plugin-sdk/diagnostic-runtime订阅该总线交由 src/adapters/openclaw/usage.ts 的handleOpenclawUsageEvent()解析 → 构建 → 插入全程不抛异常用量捕获失败绝不会打断 Agent 轮次。costUsd优先于本地定价目录确保成本统计与 OpenClaw 口径一致。关键文件一览文件用途src/adapters/openclaw/plugin.ts主插件入口同步 register、initPromise 模式、全部 Hooksrc/adapters/openclaw/index.tsOpenClawAdapter能力声明、输入解析、响应格式化、配置读写、doctor 校验src/adapters/openclaw/hooks.tsHook 事件常量与校验器src/adapters/openclaw/workspace-router.ts工作区路径解析与会话隔离src/adapters/openclaw/session-db.tsOpenClawSessionDBsessionKey 映射与会话重命名src/adapters/openclaw/usage.tsmodel.usage每轮用量/成本捕获src/adapters/openclaw/mcp-tools.ts11 个ctx_*工具注册定义scripts/install-openclaw-plugin.sh一键安装器scripts/lib/register-openclaw-config.mjs幂等的openclaw.json运行时配置写入openclaw.plugin.json插件清单id、contracts.tools、configSchematests/adapters/openclaw.test.ts适配器单元测试能力、解析、格式化、配置小结与升级建议OpenClaw 适配器的工程要点可以浓缩为三条注册 API 选对生命周期走api.on()、命令走api.registerHook()用错即静默失效、register 保持同步异步初始化收敛进 initPromise避免 Hook 整体丢失、工具面与逻辑面分离Hook 在插件进程内做路由与会话持久化ctx_*工具由 MCP 边车承载。部署时请先确认 OpenClaw 版本 2026.1.29、状态目录与mcp.servers.context-mode条目齐备一旦遇到压缩恢复质量下降优先核对压缩 Hook 是否被旧版本静默吞掉再检查 jiti 缓存与openclaw plugins list的插件可见性。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考