先决条件： Claude Code v1.0.33及以上版本（claude --version）。如果系统无法识别/plugin命令，请先更新：brew upgrade claude-code 或 npm update -g @anthropic-ai/claude-code。

安装：

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

重启Claude Code（或运行/reload-plugins）。

验证：

/context-mode:ctx-doctor

所有检查项都应显示[x]。该诊断工具会验证运行时环境、钩子、FTS5以及插件注册情况。

路由： 自动。SessionStart钩子会在运行时注入路由指令——无需向你的项目中写入任何文件。该插件会注册所有钩子（PreToolUse、PostToolUse、PreCompact、SessionStart）以及6个沙盒工具（ctx_batch_execute、ctx_execute、ctx_execute_file、ctx_index、ctx_search、ctx_fetch_and_index）。

注意： 斜杠命令是Claude Code插件的功能。在其他平台上，你可以在聊天中输入ctx stats、ctx doctor或ctx upgrade——模型会自动调用MCP工具。详情请参阅实用命令。

claude mcp add context-mode -- npx -y context-mode

先决条件： Node.js 18+，已安装Gemini CLI。

安装：

1. 全局安装context-mode：

   npm install -g context-mode
   

2. 将以下内容添加到~/.gemini/settings.json中。这个单一的配置文件会注册MCP服务器和全部四个钩子：

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode"
       }
     },
     "hooks": {
       "BeforeTool": [
         {
           "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode",
           "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }]
         }
       ],
       "AfterTool": [
         {
           "matcher": "",
           "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }]
         }
       ],
       "PreCompress": [
         {
           "matcher": "",
           "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli precompress" }]
         }
       ],
       "SessionStart": [
         {
           "matcher": "",
           "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }]
         }
       ]
     }
   }
   

3. 重启Gemini CLI。

验证：

/mcp list

你应该能看到context-mode: ... - 已连接。

路由： 自动。SessionStart钩子会在运行时注入路由指令——不会向你的项目中写入GEMINI.md文件。所有四个钩子（BeforeTool、AfterTool、PreCompress、SessionStart）都会以编程方式处理路由规则的执行。

为什么要有BeforeTool匹配器？ 它只针对那些会产生大量输出的工具（run_shell_command、read_file、read_many_files、grep_search、search_file_content、web_fetch、activate_skill），再加上context-mode自己的工具（mcp__plugin_context-mode）。这样做可以避免对轻量级工具不必要的钩子开销，同时拦截所有可能使你的上下文窗口爆满的工具。

完整配置参考：configs/gemini-cli/settings.json

先决条件： Node.js 18+，安装了Copilot Chat v0.32及更高版本的VS Code。

安装：

1. 全局安装context-mode：

   npm install -g context-mode
   

2. 在你的项目根目录下创建 .vscode/mcp.json 文件：

   {
     "servers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }
   

3. 创建 .github/hooks/context-mode.json 文件：

   {
     "hooks": {
       "PreToolUse": [
         { "type": "command", "command": "context-mode hook vscode-copilot pretooluse" }
       ],
       "PostToolUse": [
         { "type": "command", "command": "context-mode hook vscode-copilot posttooluse" }
       ],
       "SessionStart": [
         { "type": "command", "command": "context-mode hook vscode-copilot sessionstart" }
       ]
     }
   }
   

4. 重启 VS Code。

验证： 打开 Copilot Chat，输入 ctx stats。Context-mode 工具应该会显示并作出响应。

路由： 自动路由。SessionStart 钩子会在运行时注入路由指令——无需在你的项目中生成 copilot-instructions.md 文件。

完整的钩子配置（包括 PreCompact）请参阅：configs/vscode-copilot/hooks.json

先决条件： Node.js 18+，启用代理模式的 Cursor。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 在你的项目根目录下创建 .cursor/mcp.json 文件（或在 ~/.cursor/mcp.json 中进行全局配置）：

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }
   

3. 创建 .cursor/hooks.json 文件（或在 ~/.cursor/hooks.json 中进行全局配置）：

   {
     "version": 1,
     "hooks": {
       "preToolUse": [
         {
           "command": "context-mode hook cursor pretooluse",
           "matcher": "Shell|Read|Grep|WebFetch|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute"
         }
       ],
       "postToolUse": [
         {
           "command": "context-mode hook cursor posttooluse"
         }
       ],
       "stop": [
         {
           "command": "context-mode hook cursor stop"
         }
       ]
     }
   }
   

   preToolUse 匹配器是可选的——如果没有它，钩子会对所有工具生效。stop 钩子会在代理回合结束时触发，并可以发送后续消息以继续循环。此外还提供 afterAgentResponse 钩子（一次性调用，接收完整响应文本）。

4. 复制路由规则文件。由于 Cursor 缺少 SessionStart 钩子，模型需要一个规则文件来了解路由信息：

   mkdir -p .cursor/rules
   cp node_modules/context-mode/configs/cursor/context-mode.mdc .cursor/rules/context-mode.mdc
   

5. 重启 Cursor 或打开一个新的代理会话。

验证： 打开 Cursor 设置 > MCP，确认“context-mode”已连接。在代理聊天中输入 ctx stats。

路由： 钩子通过 preToolUse、postToolUse 和 stop 程序化地强制执行路由。由于 Cursor 的 sessionStart 钩子目前被其验证器拒绝（论坛报告），因此 .cursor/rules/context-mode.mdc 文件会在会话开始时提供路由指导。项目级别的 .cursor/hooks.json 会覆盖 ~/.cursor/hooks.json。

完整配置：configs/cursor/hooks.json | configs/cursor/mcp.json | configs/cursor/context-mode.mdc

先决条件： Node.js 18+，已安装 OpenCode。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 将以下内容添加到你项目根目录下的 opencode.json 文件中（或在 ~/.config/opencode/opencode.json 中进行全局配置）：

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "context-mode": {
         "type": "local",
         "command": ["context-mode"]
       }
     },
     "plugin": ["context-mode"]
   }
   

   mcp 条目用于注册 6 个沙盒工具。plugin 条目则启用钩子——OpenCode 会在每次工具执行之前和之后直接调用插件的 TypeScript 函数，从而阻止危险命令并强制执行沙盒路由。

3. (可选) 复制路由规则文件。由于 OpenCode 缺少 SessionStart 钩子，模型需要一个 AGENTS.md 文件来了解路由信息：

   cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
   

   这将告诉模型应使用哪些工具以及哪些命令会被阻止。如果没有这个文件，钩子仍然会强制执行路由——但模型将不知道为什么某个命令会被拒绝。

4. 重启 OpenCode。

验证： 在 OpenCode 会话中输入 ctx stats。Context-mode 工具应该会显示并作出响应。

路由： 钩子通过 tool.execute.before 和 tool.execute.after 程序化地强制执行路由。可选的 AGENTS.md 文件为模型提供了路由意识所需的指导。experimental.session.compacting 钩子会在对话压缩时构建恢复快照。

注意： OpenCode 的 SessionStart 钩子尚未可用（#14808），因此不支持启动或恢复会话。不过，通过插件可以完全实现压缩后的恢复功能。

完整配置：configs/opencode/opencode.json | configs/opencode/AGENTS.md

先决条件： Node.js 18+，已安装 KiloCode。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 将以下内容添加到你项目根目录下的 kilo.json 文件中（或在 ~/.config/kilo/kilo.json 中进行全局配置）：

   {
     "$schema": "https://app.kilo.ai/config.json",
     "mcp": {
       "context-mode": {
         "type": "local",
         "command": ["context-mode"]
       }
     },
     "plugin": ["context-mode"]
   }
   

   mcp 条目用于注册 6 个沙盒工具。plugin 条目则启用钩子——KiloCode 会在每次工具执行之前和之后直接调用插件的 TypeScript 函数，从而阻止危险命令并强制执行沙盒路由。

3. (可选) 复制路由规则文件。由于 KiloCode 采用与 OpenCode 相同的插件架构且同样缺少 SessionStart 钩子，模型需要一个 AGENTS.md 文件来了解路由信息：

   cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
   

4. 重启 KiloCode。

验证： 在 KiloCode 会话中输入 ctx stats。Context-mode 工具应该会显示并作出响应。

路由： 钩子通过 tool.execute.before 和 tool.execute.after 程序化地强制执行路由。可选的 AGENTS.md 文件为模型提供了路由意识所需的指导。experimental.session.compacting 钩子会在对话压缩时构建恢复快照。

注意: KiloCode 与 OpenCode 共享相同的插件架构，使用 OpenCodeAdapter，并采用平台特定的配置路径（kilo.json 代替 opencode.json，~/.config/kilo/ 代替 ~/.config/opencode/）。SessionStart 钩子是否可用取决于 KiloCode 的实现。

先决条件: 运行中的 OpenClaw 网关（>2026.1.29），Node.js 22+。

context-mode 作为原生 OpenClaw 网关插件运行，针对的是 Pi Agent 会话（读取/写入/编辑/Bash 工具）。与其他平台不同，这里没有单独的 MCP 服务器——该插件直接通过 OpenClaw 的 插件 API 注册到网关运行时中。

安装:

1. 克隆并安装：

   git clone https://github.com/mksglu/context-mode.git
   cd context-mode
   npm run install:openclaw
   

   安装程序会使用您环境中的 $OPENCLAW_STATE_DIR（默认：/openclaw）。若要指定自定义路径：

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

   常见位置：Docker — /openclaw（默认）。本地 — ~/.openclaw 或您设置 OPENCLAW_STATE_DIR 的任何位置。

   安装程序会完成所有操作：npm install、npm run build、better-sqlite3 原生重建、在 runtime.json 中注册扩展，并通过 SIGUSR1 重启网关。

2. 打开一个 Pi Agent 会话。

验证: 插件会通过 api.on()（生命周期）和 api.registerHook()（命令）注册 8 个钩子。输入 ctx stats 确认工具已加载。

路由: 自动。所有工具拦截、会话跟踪和压缩恢复钩子都会自动激活——无需手动配置钩子或路由文件。

最低版本: OpenClaw >2026.1.29——此版本包含来自 PR #9761 的 api.on() 生命周期修复。在较旧版本上，生命周期钩子会静默失败。适配器会回退到数据库快照重建（精度较低，但能保留关键状态）。

完整文档：docs/adapters/openclaw.md

先决条件: Node.js 18+，已安装 Codex CLI。

安装:

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 添加到 ~/.codex/config.toml：

   [mcp_servers.context-mode]
   command = "context-mode"
   

3. 添加用于强制执行路由和会话跟踪的钩子。创建 ~/.codex/hooks.json：

   {
     "hooks": {
       "PreToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex pretooluse" }] }],
       "PostToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex posttooluse" }] }],
       "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }]
     }
   }
   

   PreToolUse 强制执行沙箱路由（阻止危险命令，重定向至 MCP 工具）。PostToolUse 捕获会话事件。SessionStart 在压缩后恢复状态。

4. 复制路由说明（即使使用钩子，也建议复制以获得完整的路由意识）：

   cp node_modules/context-mode/configs/codex/AGENTS.md ./AGENTS.md
   

   若需全局使用：cp node_modules/context-mode/configs/codex/AGENTS.md ~/.codex/AGENTS.md。全局配置适用于所有项目。如果两者都存在，Codex CLI 会将它们合并。

5. 重启 Codex CLI。

验证: 启动一个会话并输入 ctx stats。Context-mode 工具应显示并响应。

路由: 钩子通过 PreToolUse 以编程方式强制执行路由。PostToolUse 跟踪会话事件。SessionStart 恢复状态。可选的 AGENTS.md 文件为模型提供路由说明。Codex CLI 的钩子系统使用与 Claude Code 相同的 JSON stdin/stdout 通信协议，但不支持参数或输出修改。

先决条件: Node.js 18+，已安装 Antigravity。

安装:

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 添加到 ~/.gemini/antigravity/mcp_config.json：

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }
   

3. 复制路由说明（Antigravity 不支持钩子）：

   cp node_modules/context-mode/configs/antigravity/GEMINI.md ./GEMINI.md
   

4. 重启 Antigravity。

验证: 在 Antigravity 会话中，输入 ctx stats。Context-mode 工具应显示并响应。

路由: 手动。GEMINI.md 文件是唯一的强制手段（约 60% 的合规性）。没有程序化拦截。通过 MCP 协议握手自动检测（clientInfo.name），无需手动配置平台。

完整配置：configs/antigravity/mcp_config.json | configs/antigravity/GEMINI.md

先决条件: Node.js 18+，Kiro 已启用 MCP（设置 > 搜索“MCP”）。

安装:

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 添加到您项目的 .kiro/settings/mcp.json（或 ~/.kiro/settings/mcp.json 用于全局配置）：

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }
   

3. 创建 .kiro/hooks/context-mode.json：

   {
     "name": "context-mode",
     "description": "用于保护上下文窗口的 Context-mode 钩子",
     "hooks": {
       "preToolUse": [
         { "matcher": "*", "command": "context-mode hook kiro pretooluse" }
       ],
       "postToolUse": [
         { "matcher": "*", "command": "context-mode hook kiro posttooluse" }
       ]
     }
   }
   

4. 复制路由说明。由于 Kiro 的 agentSpawn（相当于 SessionStart）尚未实现，因此模型在会话开始时需要一份路由文件：

   cp node_modules/context-mode/configs/kiro/KIRO.md ./KIRO.md
   

5. 重启 Kiro。

验证: 打开 Kiro 面板 > MCP 服务器选项卡，确认“context-mode”显示绿色状态指示灯。在聊天中输入 ctx stats。

路由: 钩子通过 preToolUse/postToolUse 以编程方式强制执行路由。KIRO.md 文件提供了路由说明，因为 agentSpawn（SessionStart 的等效物）尚未连接。工具名称显示为 @context-mode/ctx_batch_execute、@context-mode/ctx_search 等。通过 MCP 协议握手自动检测。

完整配置文件：configs/kiro/mcp.json | configs/kiro/agent.json | configs/kiro/KIRO.md

先决条件: Node.js 18+，已安装Zed。

安装:

1. 全局安装context-mode：

   npm install -g context-mode
   

2. 将以下内容添加到 ~/.config/zed/settings.json（Windows: %APPDATA%\Zed\settings.json）：

   {
     "context_servers": {
       "context-mode": {
         "command": {
           "path": "context-mode"
         }
       }
     }
   }
   

   注意：Zed使用 "context_servers" 和 "command": { "path": "..." } 的语法，而不是其他平台使用的 "mcpServers" 或 "command": "..."。

3. 复制路由指令（Zed不支持钩子）：

   cp node_modules/context-mode/configs/zed/AGENTS.md ./AGENTS.md
   

4. 重启Zed（或保存 settings.json — Zed会在配置更改时自动重启上下文服务器）。

验证: 打开代理面板（Cmd+Shift+A），进入设置，检查“context-mode”旁边的指示灯——绿色表示已激活。在代理聊天中输入 ctx stats。

路由: 手动。AGENTS.md 文件是唯一的执行手段（约60%的合规率）。没有程序化的拦截机制。工具名称显示为 mcp:context-mode:ctx_batch_execute、mcp:context-mode:ctx_search 等。通过MCP协议握手自动检测。

先决条件: Node.js 18+，已安装Pi Coding Agent。

安装:

1. 克隆扩展：

   git clone https://github.com/mksglu/context-mode.git ~/.pi/extensions/context-mode
   cd ~/.pi/extensions/context-mode
   npm install
   npm run build
   

2. 将以下内容添加到 ~/.pi/agent/mcp.json（或项目级别的 .pi/mcp.json）：

   {
     "mcpServers": {
       "context-mode": {
         "command": "node",
         "args": ["/home/youruser/.pi/extensions/context-mode/node_modules/context-mode/start.mjs"]
       }
     }
   }
   

   注意: JSON不会展开 ~。请将 /home/youruser 替换为你的真实主目录（运行 echo $HOME 查看）。

3. 重启Pi。

验证: 在Pi会话中输入 ctx stats。Context-mode工具应出现并响应。

路由: 自动。该扩展注册了所有关键生命周期事件（tool_call、tool_result、session_start、session_before_compact），从而提供完整的会话连续性和路由执行。

Context Mode在Node.js上使用better-sqlite3，它为大多数平台提供了预编译的原生二进制文件。在glibc >= 2.31的系统上（Ubuntu 20.04+、Debian 11+、Fedora 34+、macOS、Windows），只需运行 npm install 即可，无需任何构建工具。

Bun用户: 无需进行原生编译。Context Mode会自动检测Bun，并通过兼容性适配器使用内置的 bun:sqlite 模块。better-sqlite3 及其所有构建依赖项都会被完全跳过。

在较旧的glibc系统上（CentOS 7/8、RHEL 8、Debian 10），预编译的二进制文件无法加载，better-sqlite3会自动回退到从源代码编译，即通过 prebuild-install || node-gyp rebuild --release 进行编译。这需要C++20编译器（GCC 10+）、Make和带有setuptools的Python。

CentOS 8 / RHEL 8（glibc 2.28）：

dnf install -y gcc-toolset-10-gcc gcc-toolset-10-gcc-c++ make python3 python3-setuptools
scl enable gcc-toolset-10 'npm install -g context-mode'

CentOS 7 / RHEL 7（glibc 2.17）：

yum install -y centos-release-scl
yum install -y devtoolset-10-gcc devtoolset-10-gcc-c++ make python3
pip3 install setuptools
scl enable devtoolset-10 'npm install -g context-mode'

Alpine Linux:

Alpine的预编译二进制文件（musl）在better-sqlite3 v12.8.0+中可用。如果使用 ^12.6.2 的依赖范围，npm install 会解析到最新的12.x版本，在Alpine上无需构建工具即可正常工作。如果你锁定较旧的版本：

apk add build-base python3 py3-setuptools
npm install -g context-mode

每次工具调用都会经过钩子，从中提取结构化的事件：

PreCompact 触发
  → 从 SQLite 中读取所有会话事件
  → 构建按优先级分层的 XML 快照（≤2 KB）
  → 将快照存储在 session_resume 表中

SessionStart 触发（来源：“compact”）
  → 检索存储的快照
  → 写入结构化事件文件 → 自动索引到 FTS5
  → 构建包含 15 个类别的会话指南
  → 将 <session_knowledge> 指令注入上下文
  → 模型从上次用户提示处继续，保持完整的工作状态

快照按优先级分层构建——如果 2 KB 的预算紧张，低优先级事件（如意图、MCP 工具调用次数）会首先被舍弃，而关键状态（如当前文件、任务、规则、决策）则始终保留。

压缩后，模型会收到一份 会话指南——一个结构化的叙述性文档，包含可操作的部分：

• 最后请求——用户的最后一条提示，这样模型可以继续工作，而无需询问“我们刚才在做什么？”
• 任务——以复选框形式列出，标注完成状态（已完成标记为 [x]，未完成为 [ ]）
• 关键决策——用户修正和偏好（“改用 X”、“不要做 Y”）
• 修改过的文件——会话期间涉及的所有文件
• 未解决的错误——尚未修复的错误
• Git——执行的操作（checkout、commit、push、status）
• 项目规则——CLAUDE.md / GEMINI.md / AGENTS.md 的路径
• 使用的 MCP 工具——工具名称及调用次数
• 子代理任务——委派工作的摘要
• 使用的技能——调用的斜杠命令
• 环境——工作目录、环境变量
• 数据引用——会话期间粘贴的大段数据
• 会话意图——模式分类（实现、调查、评审、讨论）
• 用户角色——会话期间设定的行为指令

详细的事件数据也会被索引到 FTS5 中，以便通过 search() 函数随时检索。

Claude Code — 完整会话支持。所有 5 种钩子都会触发，捕获工具事件、用户决策，构建压缩快照，并在压缩或 --continue 后恢复状态。

Gemini CLI — 覆盖率较高。PostToolUse（工具使用后）、PreCompact（压缩前）和 SessionStart 都会触发。缺少 UserPromptSubmit，因此无法捕获用户决策和修正——但文件编辑、Git 操作、错误和任务都被完整记录。

VS Code Copilot — 覆盖率较高。与 Gemini CLI 相同——PostToolUse、PreCompact 和 SessionStart 都会触发。虽然无法捕获用户决策，但所有工具级别的事件都会被记录。

Cursor — 部分覆盖。原生的 preToolUse 和 postToolUse 钩子会捕获工具事件。sessionStart 在 Cursor 文档中有所说明，但目前被其验证器拒绝，因此无法实现会话恢复。路由指令改由 MCP 服务器启动时传递。

OpenCode — 部分覆盖。TypeScript 插件通过 tool.execute.after 捕获 PostToolUse 事件，但 SessionStart 尚未实现（#14808）。事件会被存储，但在压缩后不会自动恢复。

KiloCode — 部分覆盖。与 OpenCode 共享相同的插件架构，通过 OpenCodeAdapter 实现。TypeScript 插件通过 tool.execute.after 捕获 PostToolUse 事件，但 SessionStart 是否可用取决于 KiloCode 的实现。事件会被存储，但可能不会在压缩后自动恢复。

OpenClaw / Pi Agent — 覆盖率较高。所有工具生命周期钩子（after_tool_call、before_compaction、session_start）都通过原生网关插件触发。虽然无法捕获用户决策，但文件编辑、Git 操作、错误和任务都被完整记录。如果较旧版本的网关不支持压缩钩子，则会回退到数据库快照重建。详情请参阅 docs/adapters/openclaw.md。

Codex CLI — 基于钩子的会话跟踪。PreToolUse 强制执行路由，PostToolUse 捕获事件，SessionStart 在压缩后恢复状态。与 Claude Code 使用相同的通信协议。PreCompact 和 UserPromptSubmit 尚未实现，因此压缩快照依赖于数据库重建。

Antigravity — 不支持会话功能。与 Codex CLI 相同——没有钩子，无法捕获事件。需要手动将 GEMINI.md 复制到项目根目录。可通过 MCP 协议握手（clientInfo.name）自动检测。

Zed — 不支持会话功能。与 Codex CLI 相同——没有钩子，无法捕获事件。同样需要手动将 AGENTS.md 复制到项目根目录。可通过 MCP 协议握手（clientInfo.name）自动检测。

Kiro — 部分覆盖。原生的 preToolUse 和 postToolUse 钩子会捕获工具事件并强制执行沙箱路由。agentSpawn（Kiro 版本的 SessionStart）尚未实现，因此无法在压缩后恢复会话。需要手动将 KIRO.md 复制到项目根目录。可通过 MCP 协议握手（clientInfo.name）自动检测。

Pi 编程代理 — 覆盖率较高。该扩展注册了所有关键生命周期事件：tool_call（PreToolUse）、tool_result（PostToolUse）、session_start（SessionStart）以及 session_before_compact（PreCompact）。文件编辑、Git 操作、错误和任务都被完整记录。压缩后的会话恢复可以通过该扩展的事件钩子实现。