Codex

official

安装或刷新插件

先按快速开始安装此分支、生成配置并启动 Server。 在运行 Codex 的机器上加载客户端配置后安装匹配插件：

set -a
. ./.env
set +a
powercontext setup codex
powercontext doctor codex

该命令会把仓库添加为 Codex marketplace，安装 PowerContext 插件，并创建用户数据目录。重复执行是安全的。 --ref 应与安装 PowerContext 工具时使用的 ref 一致。

刷新安装时，setup .env 文件或进程环境中新声明的客户端地址会覆盖保存的客户端设置和之前安装的 MCP 地址。 未提供新地址时，setup 复用保存的地址。文件与进程中声明的地址冲突时，仍需显式选择：使用 --server-url， 并在重新执行前统一或清除运行时地址覆盖。--source 指定插件代码来源，不指定 Server 地址。

在 Windows 上，安装与诊断会使用 PATH 中解析出的 Codex 可执行入口，包括 npm 的 .cmd 启动脚本。 当前目录中的启动脚本不会优先于 PATH：解析直接枚举 PATH 目录；PATH 中显式写入的 . 条目与空条目仍按其位置与语义生效。 PATH 为空字符串时完全不搜索，未设置时回退到系统标准搜索根；两种行为均与 shutil.which 一致。 对于 .cmd / .bat 入口，PowerContext 会在启动该条命令前拒绝可执行路径或命令参数中的 shell 元字符 （& | < > ( ) ^ % ! "）及 ASCII 控制字符，支持空格和 Unicode。这可避免批处理解释静默改写来源或 ref； 请使用原生可执行文件，或不含这些字符的启动脚本路径及参数。该限制不作用于原生可执行文件或其他平台。 不支持的 source/ref 参数会在注册 marketplace 前被拒绝；如果后续命令因返回的 marketplace 名称而被拒绝， 注册步骤可能已经完成，安装不会因此自动回滚。

首次会话 Hook 信任

配置完成后开启新的 Codex 会话。发送第一条消息前，通过 /hooks 检查 PowerContext Hook，并在收到提示时授予信任。 SessionStart 解析会话 Scope，并按配置加载启动上下文；UserPromptSubmit 准备相关上下文，并独立地将用户输入采集为 Source。 插件还使用 PreToolUse 绑定 MCP 操作的 Scope。插件已加载或 MCP 工具可发现，都不能证明这些 Hook 已执行。

如果跳过或拒绝信任，进入 /hooks 检查 PowerContext 条目，按当前宿主提供的操作启用或信任它们。 如宿主要求开启新会话，按提示操作，在重新验收采集前再次检查 Hook。不同 Codex 版本的控件和提示可能不同。 如果找不到预期 Hook，按下文诊断安装与宿主支持情况；没有出现信任提示，不代表 Hook 已启用。

UserPromptSubmit 未启用时，不会自动召回或采集输入。MCP 连通是另一条路径，不能证明自动行为正常。 启用后发送一条含独特项目名的决定，确认它进入绑定 Scope 的 Source 日志，再按记忆验收检查后续结果。 提示词采集默认开启；如果曾主动关闭，先检查提示词采集配置。

安装与连接诊断

powercontext doctor codex --json 通过 mcp_tools 报告基础 MCP 连接，通过 mcp_full_profile 报告完整工具覆盖。 完整覆盖要求 Codex 集成 manifest 的 server-mcp 中声明的全部能力工具，包括 Memory 维护、Scope 管理和 Handoff 操作。缺失工具会按名称列出，并使结果降级；工具发现不代表模型就绪、Hook 已执行或具有写入权限。 Setup 会分别报告安装完成和诊断结果；基础 Memory 支持仍可使用时，doctor 可能单独报告 full 覆盖不完整。 鉴权或基础连接失败仍会使安装失败。

理解自动恢复、Memory 和 Handoff

插件通过两条路径访问同一个 Server：

• Prompt Hook 请求 Runtime 准备一个最终、有界的上下文值，然后独立地把用户提示词采集为 Source 证据；
• MCP 为 Codex 提供读取和维护 Memory 的显式工具，以及明确的 Handoff 工作流。

一句话交接当前工作

在已经安装插件且 PowerContext Server 可用的 Codex 会话中，直接输入：

交接

powercontext-project-context Skill 检查当前对话和仓库，整理目标、当前状态、已执行检查、遗漏和下一步， 然后在当前 Session Scope 中调用 handoff_current_work。普通交接返回接收方可以使用的完整临时 Handoff， 不会提交持久 Revision。交接当前工作 和 handoff this work 使用同一临时交接路径。

需要持久里程碑时，明确要求“保存持久交接里程碑”。Skill 准备边界后调用 commit_handoff，只有提交成功才报告精确 Revision； 已有明确授权无需再次确认。若只想检查内容而不写入，请说“预览交接，不要提交”；Skill 此时只在对话中渲染建议内容， 不调用写工具。讨论 Handoff 设计不授权写入。

Session 启动时，Codex 按以下顺序解析 Scope：显式的 POWERCONTEXT_CODEX_SCOPE_ID、已有 Session binding、 host 管理的 workspace binding、Server 默认 Scope。解析出的 Scope 会固定到当前 Session。仓库和目录身份只用于查找 binding，不生成 Scope ID。Prompt Hook 使用该 binding 完成召回和采集；PreToolUse 将同一 binding 注入 data-plane 工具，Agent 输入不能把读写重定向到其他 Scope。Session 切换工作边界时，应由 host 创建或绑定另一个 Scope。

已有 scope_id 时，把当前 Git 根登记到这个 Scope，供之后的新会话使用：

uv run --frozen --quiet --project "$PLUGIN_ROOT" python "$PLUGIN_ROOT/scripts/scope_binding.py" \
  --cwd "$PWD" --bind-scope "SCOPE_ID"

$PLUGIN_ROOT 是已安装 Codex 插件的根目录，与 Hook 使用的变量相同。在普通终端里把它换成实际目录，例如插件缓存中的 powercontext/powercontext/<version>，或本仓库的 integrations/codex/plugins/powercontext。命令写入 integration=codex、kind=workspace 的绑定，外部身份是 Git 根路径的 SHA-256。它不创建 Scope，也不从路径、远程地址或分支生成 scope_id。去掉 --bind-scope 再执行一次，可以打印该目录当前解析到的编号。--clear-scope 只删除这条 workspace binding，不删除 Scope 里的内容。

POWERCONTEXT_CODEX_SCOPE_ID 仍然优先于这条登记。已经开着的会话保持启动时写下的 Session binding；在该 Git 根新开一场会话后，没有显式变量、也没有更早的 Session binding 时，会使用这条 workspace binding。MCP 的 set_scope_binding 只改当前会话，不能代替这条命令。

Codex 开始分析提示词前，Hook 只调用一次 POST /v1/context/prepare，请求 8000-byte 总预算。它严格校验 powercontext.prepared-context.v1，并原样注入返回内容。召回 query 在构造请求前先定界：不超过 8192 个字符、 也不超过 8192 个 UTF-8 字节的 prompt 原样发送；更长的 prompt 改用最近的文本召回，先取末尾 8192 个字符、 再截到末尾 8192 字节。因此长 prompt 只会收窄 query，不会让召回失败；prompt 采集不受影响，仍按自身上限执行。 Runtime 负责把 Memory 内容标记为不可信历史、保留 精确 citation，并完成最终选择与渲染。显式搜索仍可通过 Client 和 MCP 使用，但不会成为第二次自动召回。自动注入的 内容和 Handoff 都是历史信息；Codex 在据此行动前仍应与当前代码、用户要求和系统指令核对。

Memory 用于长期保存可复用的决策、约束和状态；Handoff 用于临时移交当前任务，不能用几条 Memory 替代。概念边界见 理解 Memory 和 Handoff，操作步骤见在 Codex 中交接工作。

选择启用 Session 启动上下文

启动上下文默认关闭。若要在 Codex 的 startup、resume、clear、compact 或 fork 事件中，于第一条 prompt 前 加载一份小而确定的上下文包，请用以下环境启动 Codex：

export POWERCONTEXT_CODEX_BOOTSTRAP_CONTEXT=true
codex

固定 profile powercontext.scope-bootstrap.v1 最多包含 6 个显式标记为 bootstrap-context 的 active Atomic Memory Artifact；顺序是当前 Scope 优先，其次是最多 8 个直接 Context References。它不会扫描全部 Memory、Source、 transcript、pending Candidate 或生成的 instruction，也会排除类型类似 secret 的 Memory。所有历史文本都标记为 不可信，不能覆盖当前的用户、developer、system 或仓库指令。

默认总预算是 4096 UTF-8 bytes，可在 512 到 8192 之间调整：

export POWERCONTEXT_CODEX_BOOTSTRAP_MAX_BYTES=6144

系统不会自动选择 Handoff。若要加入当前 Scope 中一个 exact committed Handoff，请在启动 Codex 前提供其不可变身份：

export POWERCONTEXT_CODEX_BOOTSTRAP_HANDOFF='{"artifact_id":"HANDOFF_ID","revision":3}'

通过 Atomic Memory Artifact tag API，只把经过审阅、适合每个新 Session 的决策、约束、目标、已验证状态或 仓库指南标记为 bootstrap-context。不含正文的 delivery receipt 让重试保持幂等；成功注入后，第一条普通查询 会携带该 receipt，Runtime 仅排除正文已完整交付的 exact Atomic Memory revisions；启动时被截短的 Artifact 和 后续修订版本仍可正常召回。 准备、校验或回执失败时都会 fail open，不注入任何内容。 在新的生命周期包建立前发生失败（包括配置非法）时，还会清除之前保存的过期 receipt。

Experience 和 Skill 能力

除 Memory、Source 采集、上下文注入、Work Contract、Handoff、确认、Task Outcome 和候选审查外，MCP 还提供以下工具：

例如，可以要求 Codex“根据这些精确 Source 引用生成一个 Experience 候选”或“列出当前 Scope 已批准的 Skill”。 生成需要在 Server 配置对应模型；直接提交完整内容的 proposal 不需要模型。生成和提案的结果都进入待审候选， no_op 表示没有创建候选。只有明确的审查决定才会产生已批准 Artifact；读取或导入不会安装或执行 Skill。

外部 Skill 扫描读取 Server 所在主机 配置的目录，远程 Server 不能扫描 Codex 工作站的文件系统。 通过 POWERCONTEXT_SERVER_EXTERNAL_SKILLS 配置自定义目录和主机身份，详见 Agent Skill 目标。 启用访问控制时，扫描需要 server.admin，列出和解析需要 server.observe，导入需要绑定 Scope 的贡献权限。 从扫描或列表结果选择精确外部 Skill ID 和 fingerprint，再进行解析或导入。文件内容变化会使旧 fingerprint 失效。 mode: import 将精确包快照提交为待审候选，不需要生成模型；mode: fork 需要 Skill 生成模型。 详见 Experience 与 Skill 生命周期。

同时升级 Server 并刷新插件，然后开启新 Codex 会话以发现这些工具。新增 MCP 操作沿用 Session Scope 绑定和 Server 权限检查。Claude Code、WorkBuddy 共用该 MCP 工具集，因此也获得这些能力；full 描述能力覆盖范围， 不代表自动批准或保证模型已经配置。

选择标准上下文文本

在启动 Codex 前，将 POWERCONTEXT_CODEX_CONTEXT_ASSEMBLY 设置为 JSON 组装对象，即可选择 Memory/Experience 的输出类别、顺序、条数和展示信息。完整示例与输出规则见输出标准上下文文本。

控制提示词采集

默认开启提示词采集。如果当前工作不应被记录，请在启动 Codex 前关闭：

export POWERCONTEXT_CODEX_CAPTURE_PROMPTS=false
codex

采集的提示词会成为 Source 证据。开启采集并不保证自动生成 Memory；后者需要配置 generation model。 显式调用 remember_memory 不需要模型。

仅在测试时，可以让 Hook 等待 Source 处理完成：

export POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE=true

这会给每个提示词增加推理延迟，不适合作为日常交互配置。

连接启用鉴权的本地 Server

本地 Server 默认关闭认证，需要时可独立开启。首次本地配置向导默认不启用 Dashboard；选择启用 Dashboard 不要求配置 token。

从本地 secret manager 加载一个 token，然后启用鉴权并启动 Server：

export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
powercontext server run

在包含匹配 Authorization header 的环境中执行一次 setup：

export POWERCONTEXT_CODEX_AUTHORIZATION="Bearer $POWERCONTEXT_LOCAL_TOKEN"
powercontext setup codex
powercontext doctor codex

Windows PowerShell 中，通过以下方式为 setup 进程设置该值：

$env:POWERCONTEXT_CODEX_AUTHORIZATION = "Bearer $env:POWERCONTEXT_LOCAL_TOKEN"
powercontext setup codex
powercontext doctor codex

setup 会把 URL 绑定的凭据保存到 $CODEX_HOME/powercontext/credentials.json，默认位置为 ~/.codex/powercontext/credentials.json，并配置原生 MCP 的 http_headers_helper 读取同一份记录。 Linux、macOS 和 Windows 上的新 Codex 会话无需每次导出授权变量。Codex 需支持 http_headers_helper， 该路径已在 Codex CLI 0.153.4 上验证。helper 命令只包含本地路径；地址不匹配、存储格式错误或 POSIX 文件权限 不安全时，不会转发保存的凭据。Prompt Hook 读取同一记录，显式 POWERCONTEXT_CODEX_AUTHORIZATION 优先， 但不会修改保存的凭据。不要把 token 写入 .mcp.json、Server URL 或静态 MCP header。

Windows setup 还会维护当前用户的授权环境，以兼容 Desktop。环境变更不会传给已经运行的进程。 setup 后重启 Codex，让新进程加载更新后的插件配置。再次 setup 不提供 token 时保留凭据，提供新 token 时轮换凭据。 切换 Server 地址但未提供新 token 时，旧凭据仍绑定之前的地址，不会发送给新 Server。setup 和 doctor 会在不使用 该凭据的情况下验证新地址，因此关闭认证的 Server 可以正常连接。新 Server 需要认证时，在重新 setup 时通过 POWERCONTEXT_CODEX_AUTHORIZATION 或 POWERCONTEXT_CLIENT_API_TOKEN 提供它的 token；新 token 会替换保存记录， 并绑定本次选择的地址。

在 Linux 或 macOS 上可这样验证不依赖进程授权变量的新会话：

unset POWERCONTEXT_CODEX_AUTHORIZATION
powercontext doctor codex

doctor 应报告原生 MCP 工具发现成功。如果仍提示保存的凭据无法供宿主使用，升级 Codex，使用匹配的 PowerContext 插件重新 setup，再重启 Codex。旧版宿主可暂时从包含完整 POWERCONTEXT_CODEX_AUTHORIZATION header 的进程启动。

没有保存凭据或配置进程级覆盖，并且 Server 未启用鉴权时，插件行为与默认状态完全一致。如果 Server 已启用 鉴权，但有效凭据缺失或错误，Hook 会正常降级并写出 authentication_failed 诊断；MCP tools 不可用，但 不会阻塞 Codex 会话。

Server 不可用时，Hook 的恢复和采集会正常降级，不会阻塞 Codex。显式 Memory 工具会报告服务不可用。

正常空结果或召回失败时，Hook 会输出不含正文的 JSON 诊断。故障 outcome 通过成功 stdout Hook 响应顶层的 systemMessage 返回；empty 仍只作为本地诊断。outcome 包括 empty、authentication_failed、 version_mismatch、server_unavailable 和 invalid_response；事件不会包含 query、scope、prepared content、 citation、response body 或 authorization value。

使用生成的环境文件

如果已通过向导生成配置，在执行 setup 前加载 .env。 它提供 URL、Authorization 和选定的 Scope，不需要把 Server .env 中的模型 API key 传给 Agent：

set -a
. ./.env
set +a
powercontext setup codex

首次规划新 Scope 时，先执行 .env.next-steps.md 的创建请求，把响应的真实 scope_id 写入客户端文件的 POWERCONTEXT_CODEX_SCOPE_ID，再重新加载文件并开启新会话。规划标题不是 ID。未显式绑定时可能共用 Server 默认 Scope， 切换项目目录本身不会隔离数据。 发送普通 prompt 后，插件从绑定的 Scope 召回上下文，并将 prompt 采集为 Source。Server 的 Scheduler 按配置间隔处理新 Sources。

核对 Hook 和 MCP 连接

Hook 的 Server 地址从已安装插件 .mcp.json 派生，MCP 也读取同一文件。 本机默认是 http://127.0.0.1:8000；自定义端口、SSH 转发或 HTTPS 时，修改该文件使两条路径使用同一地址。 该配置优先于 POWERCONTEXT_CODEX_SERVER_URL，不能只靠导出此环境变量改变连接地址。 setup codex 会更新已安装插件的 MCP URL，并添加使用本次安装绝对路径的凭据 helper。 基础配置保留以下进程环境覆盖入口：

{
  "mcpServers": {
    "powercontext": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp/",
      "required": false,
      "env_http_headers": {
        "Authorization": "POWERCONTEXT_CODEX_AUTHORIZATION"
      }
    }
  }
}

使用 powercontext setup codex --server-url <server-url> 同时更新地址和 helper。手工编辑已安装文件时， 保留自动生成的 http_headers_helper；上面只展示基础配置。Token 不会被写死在 JSON 中。Scope 由 Hook 绑定，并注入 MCP 数据操作；不要把 规划标题或目录名当成 Scope ID。

桌面 App 不会继承已经运行的终端内部发生的环境变化。在 Windows 上，setup 会把值持久化到当前用户环境，但已 运行的 Desktop 仍需重启才能继承。运行 powercontext doctor codex，再分别确认 Hook 采集成功与 MCP 可用。 MCP 显示 connected 也不等于 Source 已采集。 最后完成Source、主题演进与新会话召回验收。

环境变量

Hook 默认允许环回 HTTP，远程 HTTP 需要显式同意，HTTPS 证书校验仍然启用。setup 会保存同意并更新已安装插件的 .mcp.json，Hook 和原生 MCP 都从该文件读取地址。只修改 Hook 的 URL 环境变量不会改变原生地址；升级覆盖 .mcp.json 后需重新运行 setup。Codex 自身的 MCP 策略仍然生效。参见连接远程 Server。

Codex Hook 外层超时为十秒。Server 不可用或拒绝鉴权时，恢复、采集和 flush 独立降级，不会阻塞 Codex。未显式指定 Scope 时，插件依次解析 Session binding、workspace binding 和 Server 默认 Scope。进程级配置必须存在于启动 Codex 的环境中；Windows setup 会把鉴权写入用户环境，但 Desktop 仍需重启才能继承。

自动输入隐私

本宿主的捕获默认值、关闭方式、凭据识别局限及独立只读查询行为见自动 prompt 隐私策略。识别到凭据的输入会跳过捕获，已接受的 Source 正文和事件身份不被改写。