概览

LeanCTX 是面向 AI 编程代理的本地上下文运行时：它为文件读取、代码搜索、目录导航、代码理解和 Shell 输出提供压缩与结构化能力，同时保留路径隔离、命令 allowlist 和敏感信息防护等安全边界。

在 Windows 11 与 Codex Desktop/CLI 中，稳定生效并不是“安装一个 exe”这么简单，而是一条由五层组成的调用链：

LeanCTX 二进制与 PATH
        ↓
Codex MCP 注册
        ↓
Codex Hooks：配置、信任、启用
        ↓
AGENTS.md：告诉模型何时优先走 LeanCTX
        ↓
Allowlist 与路径边界：决定具体命令能否执行

任何一层缺失，都可能出现“LeanCTX 已安装，但 Codex 仍主要使用原生工具”的现象。

本文按 Windows 11、PowerShell 7、Codex Desktop 与 LeanCTX 3.9.19 的实测环境编写。LeanCTX 的版本、工具数量和客户端集成会继续变化，部署时应以本机 lean-ctx --version、lean-ctx doctor 和 Codex 当前实际暴露的工具为准。

一、先理解 MCP、Hooks、AGENTS 与 Allowlist 的分工

这四部分彼此协作，但不能相互替代。

层次解决的问题缺失时的表现
MCPCodex 能否看到并调用 LeanCTX 能力没有 ctx_call、ctx_* 或 LeanCTX shell
Hooks生命周期注入、原生工具重写或观察原生 Read/Grep/Shell 不会被提示、重写或记录
AGENTS.md模型面对多个工具时优先选择哪条路线工具明明存在，模型仍可能习惯性调用原生工具
AllowlistLeanCTX Shell 实际允许执行哪些命令出现 [BLOCKED] 或命令被安全策略拒绝

因此，MCP 是主能力入口；Hooks 是客户端路由与生命周期增强；AGENTS 是模型决策规则；Allowlist 是执行安全边界。

Windows 11 上为 Codex 安装与配置 LeanCTX：MCP、Hooks、Allowlist 与完整验证-CXT - Enjoy Life | 生活、技术、交友、分享

二、安装或升级 LeanCTX

1. 首选 GitHub Releases 预编译版本

对于没有预装 Node.js/npm 或 Rust/Cargo 的 Windows 11 主机，推荐优先从 LeanCTX 官方 GitHub Releases 获取与系统架构匹配的预编译构建。这条路径不需要下载本地编译工具链，可以减少安装时间以及由编译器、链接器和依赖环境引入的排障成本。

将 lean-ctx.exe 放入一个稳定、属于当前用户且已加入 PATH 的目录。例如：

New-Item -ItemType Directory -Force "$env:USERPROFILE\bin"
Move-Item .\lean-ctx.exe "$env:USERPROFILE\bin\lean-ctx.exe"

重新打开 PowerShell 后验证：

Get-Command lean-ctx -All
lean-ctx --version

如果机器上存在多个版本，必须先处理路径冲突。Codex Desktop 可能继承与交互式 PowerShell 不同的环境变量，因此“终端能运行”并不自动证明“客户端能找到同一个 exe”。

2. 可选：npm 或 Cargo

如果主机本来就具备相应运行时，也可以选择：

# 已安装 Node.js 与 npm
npm install -g lean-ctx-bin

# 或：已安装完整 Rust/Cargo 工具链
cargo install lean-ctx

不建议仅为安装 LeanCTX 临时引入一整套本地编译环境；除非确实需要 Cargo 构建，否则 Windows 主机使用 Releases 预编译版本通常更直接。

3. 升级现有安装

已经安装 LeanCTX 时，可以使用其内置更新命令：

lean-ctx update
lean-ctx --version

本文验证时，本机输出为：

lean-ctx 3.9.19

不要只根据下载文件名判断版本；最终以实际执行的二进制输出为准。

三、为 Codex 注册 LeanCTX MCP

1. 优先使用官方包装命令

在普通本机 PowerShell 中运行：

lean-ctx wrap codex

该命令用于注册 Codex MCP 集成和相关客户端配置。已有复杂 Codex 配置时，先备份：

Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.before-leanctx"

如果希望逐项选择，也可以使用：

lean-ctx setup

完成后，完全退出并重新启动 Codex Desktop。MCP 配置通常在客户端启动时加载，只关闭单个任务并不等同于重启整个客户端。

2. 手动核对 config.toml

Codex 的用户级配置通常位于：

%USERPROFILE%\.codex\config.toml

一个可核对的最小形态如下：

[features]
hooks = true

[mcp_servers.lean-ctx]

command = "C:/Users/<YOUR_USER>/bin/lean-ctx.exe" args = [] startup_timeout_sec = 30 tool_timeout_sec = 120

请把 <YOUR_USER> 替换为实际用户名，或者使用已经确认会被 Codex Desktop 继承的 lean-ctx 命令名。

注意：

  • 如果文件中已经有 [features]，只在原表内合并 hooks = true，不要创建重复表。
  • Windows 图形客户端的 PATH 可能不同于 PowerShell；稳定的绝对路径通常更容易排查。
  • MCP 注册成功只表示 Codex“可以调用”LeanCTX，并不保证模型每次都自动优先选择它。

3. 只暴露 ctx_call 是否正常

正常。不同 LeanCTX profile 或 MCP 工具预算可能产生两种工具面：

  • 直接暴露多个 ctx_* 与 LeanCTX shell 工具；
  • 只暴露 ctx_call，再由它按名称调用 ctx_read、ctx_search、ctx_shell 等内部能力。

第二种是网关模式，不代表安装失败。规则中必须明确：当 ctx_call 是唯一入口时，通过它调用所需的 LeanCTX 能力，不要假定原生工具会自动透明转发。

四、配置 Codex Hooks

1. hooks.json 的作用

Codex 用户级 Hook 文件通常位于：

%USERPROFILE%\.codex\hooks.json

以下模板对应本次验证通过的四类事件、五个命令处理器。把 <LEAN_CTX_EXE> 替换为实际绝对路径：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Read|Grep|Glob",
        "hooks": [
          {
            "type": "command",
            "command": "<LEAN_CTX_EXE> hook codex-pretooluse",
            "timeout": 15
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "<LEAN_CTX_EXE> hook observe",
            "timeout": 5
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume|clear",
        "hooks": [
          {
            "type": "command",
            "command": "<LEAN_CTX_EXE> hook codex-session-start",
            "timeout": 15
          },
          {
            "type": "command",
            "command": "<LEAN_CTX_EXE> hook observe",
            "timeout": 5
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "<LEAN_CTX_EXE> hook observe",
            "timeout": 3
          }
        ]
      }
    ]
  }
}

SessionEnd 的超时上限是 3 秒。写成 5 秒时，Codex 会把它限制为 3 秒并显示加载警告，因此应直接配置为 3。

2. 为什么 hooks.json 没有 enabled 字段

这是正常设计。Codex 把“定义”“总开关”和“信任状态”分开管理：

  • hooks.json 定义事件、matcher、命令与 timeout；
  • config.toml 中的 [features] hooks = true 控制 Hook 功能；
  • Codex Hooks 页面负责审核、信任和逐项启用命令 Hook。

非托管命令 Hook 即使已经写入文件，也不会在未经审核时直接执行。打开 Codex 的 Hooks 页面，对每个处理器执行：

  1. 展开并检查命令、matcher 和 timeout；
  2. 点击 Trust；
  3. 打开右侧开关；
  4. 完全重启 Codex。

如果之后修改了命令定义，Codex 会按新的定义重新计算信任状态，通常需要再次审核和信任。

五、加入最小 LeanCTX 路由规则

工具注册解决“能不能调用”，AGENTS 规则解决“模型优先调用什么”。建议在适用的 AGENTS.md 中保留一个小而完整的骨架，而不是复制整份 LeanCTX 手册。

推荐英文规范如下：

### LeanCTX Token-Saving Route

- Use LeanCTX for eligible local context work when available. When Hook replacement redirects a native tool, use the specified `ctx_*` route directly. When neither MCP nor Hook routing is available but the CLI is installed, use `lean-ctx -c` for verbose or high-output Shell commands; otherwise use permitted native or specialized tools as needed.
- Prefer one complete read for small files requiring exact structure or formatting. If triage omits required content, do not repeat the same broad read; retrieve only the missing evidence through a narrower read or another permitted source.
- Triage means compressed output, not failure. Treat a permanent denial as terminal only for the denied invocation or route; judge success from blocking status, error text, exit results, and required evidence, then follow any stated alternative or use a materially different permitted path.
- Keep command names aligned with the LeanCTX allowlist. Allowing a command does not allow every invocation form; if inline interpreter code or complex inline Shell logic is blocked, use an approved script or, when writes are authorized, a minimal project-internal temporary script, then remove it after verification if reproducible.

六、按需维护 PowerShell Allowlist

LeanCTX 的 Shell allowlist 是安全边界。应采用“遇到稳定、低风险、重复出现的需求，再逐项增加”的策略；不要把命令参数、解析碎片或整段脚本误加入 allowlist。

查看当前有效的显式附加清单：

lean-ctx allow

截至 2026-08-24，本机 restricted 模式的当前显式附加清单为：

Remove-Item
Copy-Item
New-Item
wsl
Move-Item
Push-Location
Pop-Location
Rename-Item
Expand-Archive
Compress-Archive
Set-Content
Add-Content
Out-File
Tee-Object
Clear-Content
Stop-Process
Invoke-WebRequest
Invoke-RestMethod
Start-Transcript
Stop-Transcript
Set-ItemProperty
Start-Process
Unblock-File
winget
icacls
Set-Acl
takeown
attrib
ssh
scp
sftp
Stop-Computer
Restart-Computer
shutdown

这些条目是通过 lean-ctx allow <command> 以 additive 方式加入的，不会移除默认命令；显式附加清单及总许可数以本机 lean-ctx allow 输出为准。Remove-Item、Move-Item、Copy-Item 和 New-Item 具有文件系统变更能力，使用前必须核对精确绝对路径、目标范围和可恢复性；wsl 还可能间接执行 Linux 文件和系统操作。

本次对常用 PowerShell 命令逐项进行直接 cmdlet 入口测试后，下面这些命令在默认规则下已可用，无需重复加入显式清单：

Get-Content       Get-ChildItem       Get-Item
Test-Path         Resolve-Path        Get-Location
Join-Path         Split-Path          Select-String
Get-Command       Get-Date            Get-FileHash
ConvertFrom-Json  ConvertTo-Json      Select-Object
Sort-Object       Measure-Object      Group-Object
Format-List       Format-Table        Out-String
Get-Member        Where-Object

不要把 --list 当成查看参数传给 lean-ctx allow；在当前 CLI 中，lean-ctx allow <value> 会按 additive 规则处理参数，查看清单应直接运行 lean-ctx allow。

不建议仅为“方便”默认放行 Tee-Object，因为它可写文件；Get-Unique 与 Join-String 也不是必要补充，多数场景可分别使用 Sort-Object -Unique 和 PowerShell 的 -join 完成。

配置 Skills 与 Memory 的精确路径访问

Shell allowlist 只解决“哪些命令能运行”，不会放行当前 project root 之外的文件。Codex 必须按需读取已选技能的完整 SKILL.md；如果 AGENTS 又要求本地读取始终经过 ctx_*，而 LeanCTX 没有获准访问全局 Skills 目录，就会形成“必须读取、但唯一读取路线拒绝”的配置死路。

先确认当前生效的 LeanCTX 配置文件并建立可恢复快照：

lean-ctx config path
Copy-Item "$env:USERPROFILE\.config\lean-ctx\config.toml" ".\config.toml.before-skills-path-fix"

然后在 LeanCTX config.toml 的根级加入精确目录；不要放进 [context] 表：

allow_paths = [
    "C:/Users/<YOUR_USER>/.codex/skills",
    "C:/Users/<YOUR_USER>/.codex/plugins/cache",
]
extra_roots = [
    "C:/Users/<YOUR_USER>/.codex/memories",
]

请把 <YOUR_USER> 替换为实际用户名，并以当前会话暴露的真实技能路径为准：

  • .agents/skills 是 Codex 官方文档中的用户级 Agent Skills 目录；仅当该目录实际存在并被当前 Codex 使用时，才把它追加到 allow_paths；
  • .codex/skills 可包含当前环境安装的系统或本地技能；
  • .codex/plugins/cache 可包含插件随附的技能；
  • allow_paths 适合按明确路径读取但不需要作为项目扫描根的 Skills；
  • extra_roots 会把目录加入搜索与索引范围，适合规则要求通过 ctx_search 检索的 Memory。

不要把整个 C:/Users/<YOUR_USER>、Documents 或磁盘根加入白名单，也不要关闭 path_jail。配置修改后不要假定已有 MCP 进程一定热加载；如果仍显示旧边界、调用持续挂起或进程已处于异常状态，完全退出并重新启动 Codex 后再测试。

验证时不能只运行 CLI lean-ctx read：CLI 可能只给出 defense-in-depth 警告，而 Codex MCP 才是本次要修复的实际路径。应执行：

lean-ctx config validate
lean-ctx doctor

然后在重启后的 Codex 新任务中确认：

  1. ctx_read 能读取用户级、系统级和插件技能的 SKILL.md；
  2. ctx_search 能检索 .codex/memories/MEMORY.md；
  3. 未列入 allow_paths 或 extra_roots 的 project root 外路径仍返回 path escapes project root。

七、完整验证：不要只看“安装成功”

1. 静态检查

lean-ctx --version
lean-ctx status --json
lean-ctx doctor
lean-ctx doctor integrations --json
lean-ctx allow --list

重点确认：

  • 实际二进制版本与路径符合预期；
  • Codex MCP 配置被检测到；
  • 有效配置文件路径正确；
  • restricted 模式仍然启用；
  • 新增命令出现在 additive extra allowlist 中。

Windows 上如果 doctor 显示 daemon 不受支持，不必把它当作 Codex stdio MCP 故障。

2. 客户端检查

完全重启 Codex，创建一个新任务，然后让它执行：

  • 读取项目中的一个 Markdown 或源代码文件；
  • 搜索一个只出现数次的标识符；
  • 运行一个只读 PowerShell 聚合命令。

观察实际工具调用：

  • 直接出现 ctx_read、ctx_search、ctx_shell；
  • 或出现 ctx_call，其内部调用相应 LeanCTX 工具；
  • 原生 Shell/Read 被 PreToolUse 提示、重写或要求改走 LeanCTX。

只看到原生工具名称而没有任何 Hook 或 LeanCTX 证据，不能算验证通过。

3. 统计检查

在测试前后运行：

lean-ctx gain --deep

应能看到 LeanCTX 接触到的调用数量或节省统计继续增长。这里的统计只覆盖经过 LeanCTX 的流量，不等于整个 Codex 会话的总 token，也不等于模型供应商账单。

需要实时观察时可以运行：

lean-ctx watch

其中 budget、SLO 或角色 token 百分比是 LeanCTX 的会话预算遥测，不是 Codex 模型上下文窗口或 OpenAI API 限额。偶尔在超长任务中超过软预算并显示 WARNING，不代表安装失效；应结合 lean-ctx doctor overhead --json 区分固定上下文开销是否真正超限。详细解释见配套排障篇。

八、维护、更新与回滚

更新 LeanCTX 后建议重新执行：

lean-ctx --version
lean-ctx wrap codex
lean-ctx doctor

然后重新检查 Hooks 页面。只要 Hook 命令定义发生变化，就可能需要重新信任。

需要撤销 Codex 集成时：

lean-ctx unwrap codex

回滚前保留 config.toml 和 hooks.json 的可恢复副本。不要把含凭据、私有 MCP 地址、token 或机器专用敏感信息的完整配置提交到公开仓库。

最终验收清单

  • lean-ctx --version 输出预期版本与二进制。
  • lean-ctx doctor 能识别 Codex MCP。
  • config.toml 中 LeanCTX MCP 配置有效。
  • hooks.json 有四类事件、五个处理器，SessionEnd 为 3 秒。
  • Hooks 页面中的命令已检查、信任并启用。
  • Codex 已完全重启，并在新任务中暴露 ctx_call 或 ctx_*。
  • AGENTS 规则明确 LeanCTX 的默认范围与原生工具例外。
  • Group-Object 等新增命令通过最小 allowlist 管理。
  • LeanCTX 根级 allow_paths/extra_roots 精确覆盖必需的 Skills 与 Memory，且未放宽整个用户目录。
  • 新 MCP 调用能读取 SKILL.md、搜索 Memory，并继续拒绝未授权的根外路径。
  • lean-ctx gain --deep 在真实测试后继续增长。

完成这些步骤后，LeanCTX 才算在 Windows 11 下从“已安装”进入“可验证、可维护、稳定生效”的状态。

如果安装完成后仍出现“不优先调用”、Hook 未信任、allowlist 拦截或路径隔离错误，可继续阅读配套文章：Codex 中 LeanCTX 安装后不生效：Windows 11 排障手册。

九、令牌节省路由与安全回退

LeanCTX 的目标是减少进入模型上下文的冗长本地输出，而不是强制所有读写和命令都经过同一入口。部署完成后，应根据当前客户端实际暴露的能力选择最短可用路径。

9.1 选择 MCP、Hook、CLI 或原生工具

  • MCP 或 Hook 路由可用时，优先使用客户端暴露的 ctx_*、LeanCTX shell 或 ctx_call。
  • MCP 与 Hook 路由不可用、但 CLI 已安装时，对冗长或高输出量的 Shell 命令使用 lean-ctx -c "<command>"；需要未经压缩的精确输出时使用 lean-ctx raw "<command>"。
  • 编辑与写入、交互式或 TTY 进程、LeanCTX 不具备的能力，以及需要独立验证的操作，使用原生或专用工具。

lean-ctx wrap codex 会为 Codex 注册 LeanCTX MCP，并将所选客户端接入本地代理；它是集成方式之一，不应被写成判断 LeanCTX 是否可用的唯一条件。可用 lean-ctx status 和 lean-ctx doctor 检查当前连接与配置。

9.2 正确理解压缩与拒绝

  • [lean-ctx: N lines filtered by triage] 是压缩提示，本身不等于命令失败；应结合退出状态和所需证据判断是否需要定向展开。
  • [BLOCKED — DO NOT RETRY]、allowlist 明确拒绝或 path escapes project root 表示当前路径被永久拒绝。停止改写引号、参数顺序或等价命令反复尝试，改用其他允许的工具或路径。
  • 回退没有固定次数限制：只要方案真正不同、仍在授权范围内并能产生新证据，就可以继续执行。

9.3 命令 allowlist 与路径边界是两层控制

lean-ctx allow <command> 只增加命令许可，不会自动允许访问当前 project root 之外的目录。对于确实需要访问的外部项目，只添加精确的 extra_roots 或 allow_paths；不要为了绕过限制而放开整个用户目录、Documents 或磁盘根目录。

文档快照流程常用的 PowerShell 命令包括：

lean-ctx allow New-Item
lean-ctx allow Copy-Item
lean-ctx allow Test-Path
lean-ctx allow Get-FileHash
lean-ctx allow --list

只放行工作流实际需要的命令。完成复制后，应同时验证快照存在，并比较原文件与快照的哈希；外部文件既不受当前 Git 历史保护、又无法创建或验证快照时，不要直接修改原件。

参考资料