> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> 组合 UserPromptSubmit Hook、HTTP MCP 与 project-context Skill，实现自动召回和显式 Handoff。

> [!NOTE]
>
> 当前集成有契约与 HTTP 服务链 coverage。正式最低 Codex 版本尚未声明；完整的真实 Codex 宿主进程端到端验证仍是 **Not validated**。

## 成熟度与安装

完整的 Codex 安装需要插件的三个部分：

* `UserPromptSubmit` Hook，用于自动召回、提示词采集与可选刷新；
* HTTP MCP Server，用于显式操作；
* 内置 `project-context` Skill，用于 Scope、Handoff 与 write-intent 规则。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext setup codex --source oceanbase/powercontext --ref master
powercontext server run
powercontext doctor codex
```

安装配置会让 Codex 添加插件市场与插件，然后验证已安装条目。与 Claude Code 安装配置不同，当前 Codex 安装程序 不会打印不写入预览 计划，也没有事务式回滚。这里的安装配置预览/回滚契约属于 **Unsupported**，不能当成所有宿主共享的能力。

## 最小用法

新开一个 Codex 会话。在 `/hooks` 查看 `UserPromptSubmit`，再到 `/mcp` 确认 PowerContext Server。之后分别试三条路径：

1. 提一个普通仓库 question。Hook 可以注入召回的上下文，但只会把这条提示词采集为 Source。
2. 让 Codex 搜索或维护 Memory。内置 Skill 会引导它使用 MCP 工具。
3. 确实想在同一轮次准备并提交持久 Handoff 时，说 `handoff this work`。

只有 Hook 的插件可以召回，却没有显式操作范围和使用规则。只有 MCP 而没有 Skill，则缺少宿主专用约束。受支持的组合是 Hook + MCP + Skill。

## 执行流程

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
UserPromptSubmit
→ isolated uv/Python hook
→ derive API base from plugin .mcp.json
→ resolve shared project Scope
→ expected recall failures fail open, then capture prompt
→ optional flush through captured Source position
→ hook stdout additionalContext
```

Hook 是 short 进程，不会在轮次之间保留对话 object，也不会采集 Codex 最终响应。

## Scope 与 Workstream 绑定

Scope 解析器按以下顺序检查：

1. 如果设置了 `POWERCONTEXT_CODEX_SCOPE_ID`，优先使用它；
2. Git 私有 Workstream 绑定；
3. 规范化的 Git 远程仓库标识，再回退到规范化的项目路径。

Binding 存在检出的 Git 目录下，因此跟随本地检出，又不会进入提交。Codex 与 Claude Code 使用同一套绑定和远程规范化。这样，两边读写的是同一个项目 Memory，而不是各自产生平行 Scope。

在持久 Handoff 或没有精确 Workstream 的 `latest` 继续之前，如果 `select_handoff_workstream` 可用，Skill 会先调用它。存在多个候选时，必须由用户选择。Codex 随后绑定返回的 `scope_id`，重新解析，并在 Handoff 写入前要求精确 match。Picker 本身是只读。

## 注入与 API 基础地址推导

Hook 从已安装插件的 `.mcp.json` 读取 `powercontext` HTTP MCP URL，要求它是安全且无歧义的 `/mcp` URL，再移除该路径得到 HTTP API 基础。自动 HTTP calls 与 MCP 因此始终使用同一端点，不存在另一份可能与 MCP 配置漂移的 Hook URL。

已准备上下文通过模式检查和大小上限后，才会作为 `additionalContext` 写到 Hook 标准输出。Empty 结果不输出内容。未知模式、重定向、超限响应、认证失败、Server 错误或实际耗时截止时间都采用 fail-open，并只留下不含内容诊断信息。授权信息绝不会跨重定向转发。

## 采集与刷新

自动采集只把当前提示词写入 `/v1/sources/content`，Source ID 使用稳定的 `codex-user-prompt:` 前缀，并保留来源信息。它不采集助手最终响应，也不创建 Task Outcome。

预期召回失败会被隔离，因此采集仍可继续。但意外召回异常可能到达 outer fail-open handler，并跳过这次采集，所以不能声称两者无条件独立。设置 `POWERCONTEXT_CODEX_CAPTURE_PROMPTS=false` 可关闭采集。设置 `POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE=true` 可启用可选刷新；`POWERCONTEXT_CODEX_FLUSH_MAX_CALLS` 限制尝试次数。只有 `current_cursor >= position` 后，Hook 才结束等待。若游标始终追不上，轮次仍继续，但不能声称已经生成 Memory。

已采集提示词只是 Source 证据。超过 200,000 字符的提示词会跳过。Codex 采集没有 DSH 的窄匹配 secret-marker 过滤器；提示词不应持久化时，请关闭采集。调度器/刷新处理可能生成 Candidate，Review 最终可以提交 Memory，也可以无变更。

## MCP、Skill、Handoff 与权限

MCP 提供显式 Memory 维护、工作契约（Work Contract）、Handoff、确认、结果与 Review 操作。`POWERCONTEXT_CODEX_AUTHORIZATION` 可以通过 `.mcp.json` 的 `env_http_headers` 提供完整授权信息值；公开本地 Server 可以不设置。远程端点必须使用 HTTPS。

Skill 为 `handoff this work` 定义单轮次语义。Codex 检查当前对话与仓库，只调用一次 `handoff_current_work` 并使用 unique `source_id`，在同一轮次将返回的 `handoff` 原样传给 `commit_handoff`，并且只在拿到精确 Revision 后报告成功。明确命令已经授权 Handoff 时，不会再索要第二次确认。

预览边界很明确。Handoff 问题、设计讨论、draft 请求或 `preview and make no writes` 都不授权写入。Codex 只在对话中展示拟议字段，不能调用 `handoff_current_work`，因为准备本身就会记录边界 Source。已准备 Handoff 可以不提交，但它不是 zero-write 预览。

显式持久修改操作失败必须可见。MCP 工具 annotations 会描述读取/写入、destructive 与 幂等 意图，但工具 visibility 本身不是授权信息边界。宿主权限 UI 与 enforcement 属于 **Host-gated** 和 **Not validated**；不要从其他适配器借用更强的无界面保证。

## Unsupported 与 Not validated

| 状态 | 能力 | 实际影响 |
| - | - | - |
| **Unsupported** | 自动助手最终响应采集 | 需要通过 MCP 显式持久化最终结果。 |
| **Unsupported** | 自动 Task Outcome | 在真实边界调用 `record_task_outcome`。 |
| **Unsupported** | 通过 `handoff_current_work` 做 zero-write 预览 | 只在对话展示预览字段，不调用该工具。 |
| **Unsupported** | Codex 安装配置不写入 计划 与事务式回滚 | 运行前自行检查命令；部分完成 失败后可能需要手动清理。 |
| **Not validated** | 正式最低 Codex 版本 | 不要把开发中测试过的版本写成支持下限。 |
| **Not validated** | 完整真实 Codex 宿主进程端到端验证 | 契约与 HTTP 服务链测试不能证明完整宿主生命周期。 |
| **Not validated** | 真实宿主执行 one-turn Handoff 与预览不写入策略 | 这些是内置 Skill 规则，底层 MCP primitives 已存在，但还没有完整 Codex behavioral 验收测试。 |
| **Not validated** | 精确 Codex 权限 UI 与 enforcement | MCP annotations 只表达 意图；授权信息行为由宿主负责。 |

托管 Skill 导出支持 Codex，但已导出托管 Skill 与内置插件 Skill 是不同对象。安装其中一个，不能替代另一个。

## 负向实验

* 停掉 Server 后提交普通提示词。Codex 应继续运行；显式写入应报告失败。
* 触发预期召回失败，确认采集仍运行。再单独注入意外召回异常，确认整个 Hook 仍 fail-open；这次采集可能被跳过。
* 把 MCP URL 改成 unsafe、ambiguous 或非 `/mcp` 值。设置应拒绝，而不是猜测 API 基础。
* 让 Hook 请求重定向。授权信息不得到达目标端。
* 返回 未知 模式或超限响应。不得发生注入。
* 让刷新用完 attempt/截止时间预算，同时游标始终落后。轮次应继续，且不能谎报 Memory。
* 让 Handoff 准备成功、提交失败。报告边界 Source 已写入、持久里程碑不存在；不要为了重试再创建第二个边界。
* 请求 `preview and make no writes`。确认没有 PowerContext 调用写入 Source 或 Handoff。
* 用 old Citation 修订或停用 Memory。应返回冲突；刷新头版本，不能盲目覆盖。

## 配置默认值

Hook 从插件 `.mcp.json` 推导 API 基础，默认连到 `http://127.0.0.1:8000/mcp`。其余行为由 `POWERCONTEXT_CODEX_` 环境变量控制：

| 键 | 默认值 | 含义 |
| - | - | - |
| MCP `url` | `http://127.0.0.1:8000/mcp` | 写在插件 `.mcp.json`，不要改成带凭证的 URL |
| `POWERCONTEXT_CODEX_SCOPE_ID` | 未设置 | 显式 Scope；未设置则按 Workstream / Git / 路径推导 |
| `POWERCONTEXT_CODEX_AUTHORIZATION` | 未设置 | 完整 Bearer 请求头；Hook 和 MCP 都读它 |
| `POWERCONTEXT_CODEX_CAPTURE_PROMPTS` | `true` | 采集当前用户提示词为 Source |
| `POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE` | `false` | 测试用：采集后等待刷新 |
| `POWERCONTEXT_CODEX_REQUEST_TIMEOUT_SECONDS` | `1` | 单次 HTTP 超时 |
| `POWERCONTEXT_CODEX_HTTP_BUDGET_SECONDS` | `4` | 一轮准备/采集总预算 |
| `POWERCONTEXT_CODEX_FLUSH_MAX_CALLS` | `4` | 刷新最多调用次数；允许 `1–16` |
| 召回预算 | `8000` | Hook 发给 `prepare_context` 的 `max_bytes`；没有对应环境变量 |
| Hook 超时 | `10` | Codex 外层 Hook 超时，单位秒 |

插件 `.mcp.json` 至少要有这些字段。令牌只写环境变量名，不写值：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "powercontext": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "required": false,
      "env_http_headers": {
        "Authorization": "POWERCONTEXT_CODEX_AUTHORIZATION"
      }
    }
  }
}
```

新会话里对照：

1. `/hooks` 列出 PowerContext `UserPromptSubmit`。提示信任时再信任。
2. `/mcp` 看到名为 `powercontext` 的 Server。Server 已启动时应是 已连接。
3. `/mcp` 工具列表里有 `remember_memory`，没有 `prepare_context`。

`POWERCONTEXT_CODEX_SERVER_URL` 会被忽略。`server_url` 只来自插件 `.mcp.json`。不要把令牌写进 `.mcp.json`、Server URL 或静态 MCP 请求头。当前工作不能落成 Source 时：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POWERCONTEXT_CODEX_CAPTURE_PROMPTS=false
codex
```

## 在这个宿主上做完统一题

> 修改 OpenAPI 契约后，下一步应该做什么？

1. 在固定 Scope 里用 MCP `remember_memory` 保存答案。不要只靠自动采集。
2. 开一个新 Codex 会话，用 `/mcp` 确认仍连着 Server，再问同一句。
3. 召回必须带 Citation，并且只出现在 `UserPromptSubmit` 的 `additionalContext`。
4. 停掉 Server 后再问普通编码问题。Hook 可以 fail-open，编码应继续。
5. 再调用 MCP `remember_memory`。失败必须可见，不能假装保存成功。

## 完成检查表

只有以下结果都能直接观察时，才算完成：

* `powercontext doctor codex` 能找到已安装/已启用插件。
* Server 存活状态/就绪状态由单独的 `powercontext doctor` 检查。
* `/hooks` 显示 `UserPromptSubmit`。
* `/mcp` 显示 PowerContext Server。
* 内置 `project-context` Skill 与 Hook、MCP 同时存在。
* Hook 从 MCP 使用的同一个 `.mcp.json` URL 推导 API 基础。
* Codex 与 Claude Code 对同一仓库/Workstream 解析出一个 Scope。
* 自动 Source 只包含用户提示词，不包含助手最终响应。
* 必须保持私密的提示词已关闭采集。
* 可选 刷新有明确上限，并在成功前证明 `current_cursor >= position`。
* `preview and make no writes` 不产生写入。
* Imperative Handoff 在一轮次内完成，并返回精确已提交 Revision。
* 显式写入失败保持可见。
* 自动召回/采集失败仍 fail-open。
* 上面的 **Unsupported**、**Not validated** 与 **Host-gated** 状态始终分开，包括真实宿主的 Handoff、预览与权限校验。

下一页是 [Claude Code](https://powercontext.mintlify.site/zh/coding-agents/claude-code.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.