# Codex

推荐使用独立的 XMemo Skill 连接 Codex CLI 和 Desktop，并以直接 MCP 作为受支持的备选方案。

- Canonical: https://docs.xmemo.dev/zh/docs/mcp/codex
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 509a4d640bcac1076020015dcc2e3ca09db14ea5c7d405058a07ddf2bdd426b6
- Edition-Digest: c7e27b230be1072e2a36a29286fcc8aa32d0c7c8e30df5f087f50e00dabd33ac
- Source-Revision: sha256:99af2f1e8dcd76b03aa4019faeb9d18995ed91ee2d0633430737af760cbcfdbf

## 前置条件

使用支持 Streamable HTTP MCP 和 Skill 执行的 OpenAI Codex CLI 或 Codex Desktop：

- 具体接口：Codex CLI 和 Codex Desktop (codex)。
- 运行时要求：独立 Skill 运行器需要 Node.js 22.22.0 或更高版本。
- 账户：在 https://xmemo.dev 拥有有效的 XMemo 账户。
- MCP 前置条件：在 ~/.codex/config.toml 中支持 bearer_token_env_var。

## 安装 / 设置

推荐路径使用所有者选择的提示词将独立的 XMemo Skill 安装到 Codex 的 skills 目录中。要求 Codex 中的智能体执行安装：

- 提示词：Install the standalone XMemo Skill into your skills directory: run the installer from https://xmemo.dev/skill/install (on Windows, https://xmemo.dev/skill/install.ps1) with XMEMO_SKILL_DIR set to your skills directory plus /xmemo-memory. Run the doctor command it prints to verify the installation, then reload your skills and follow the Skill's first-run steps. Follow your normal safety checks and do not use elevated privileges.
- 默认安装路径：~/.codex/skills/xmemo-memory。
- 替代路径：使用 bearer_token_env_var 在 ~/.codex/config.toml 中配置直接 MCP 配置文件。

## 设置凭据

在运行操作之前配置您的凭据。在用于启动 Codex 的环境中设置 XMEMO_KEY。bearer_token_env_var 会读取该值而无需将令牌放入 config.toml 中。如果使用带有 --allow-plaintext 的交互式设备登录，请注意此标志会在此计算机上未加密存储凭据：

```bash
export XMEMO_KEY='<your-xmemo-token>'
# Interactive alternative (stores credential unencrypted on this machine):
# node ~/.codex/skills/xmemo-memory/scripts/xmemo-skill.mjs login --allow-plaintext
```

## 生成 / 确认 XMEMO_AGENT_INSTANCE_ID

客户端配置映射此安装的稳定实例身份。确认 env_http_headers 映射了 XMEMO_AGENT_INSTANCE_ID，并在各会话之间重复使用相同的非机密值。

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'
# Persist and reuse this value for the same local install
```

## 保留现有配置块

使用经过审查的 Codex 配置块。保留 bearer_token_env_var 和 XMemo URL；切勿将密钥直接粘贴到 config.toml 中：

```toml
[mcp_servers.xmemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"
```

## 重启客户端

在写入配置文件、修改环境变量或安装 Skill 后重启 Codex，以便检测到新组件。

## 使用真实的召回调用进行测试

在写入数据之前，请先发出只读请求以验证连接性。此检查不会修改记忆状态。

```text
recall({ query: "connection check", limit: 1 })
```

## 预期响应（字面形态）

成功的调用将返回以下公开的排序文本形态；引用和内容是来自授权记忆空间的真实值。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## 首个实用任务：合成记忆生命周期

跨保存、会话转换、召回和修正演练完整的合成记忆任务：

- 1. 保存合成事实：node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions" (或 MCP remember 工具)。
- 2. 无状态转换：打开一个新的 Codex 终端会话以验证跨会话的持久性。
- 3. 带溯源归属的召回：node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" (或 MCP recall 工具)。在返回的输出中验证 Reference 和 Location。
- 4. 修正记忆：node scripts/xmemo-skill.mjs update --id <active-memory-id> --content "Demo project timestamps use UTC with ISO 8601 formatting." (或 MCP update_memory 工具)。
- 5. 可选清理：node scripts/xmemo-skill.mjs forget --id <active-memory-id> --confirm (或 MCP forget 工具)。

## 功能与配置文件工具

Codex 可以访问 MCP 文档契约中为 generic-public 配置文件定义的限定工具：

- 核心记忆工具：remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context。
- 工作区工具：get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger。

## 限制与边界

Codex 的操作边界与约束：

- 工作区隔离：操作严格限制在已登录用户的工作区内。
- 密钥处理：务必使用 bearer_token_env_var；切勿在 config.toml 中硬编码令牌。
- 分发范围：Codex 的非标准或第三方分支仍标记为未测试。

## 常见错误

使用以下恢复步骤排查常见的 Codex 问题：

- 401 invalid_token — XMEMO_KEY 缺失、已过期或无效：验证启动 Codex 的环境并重启。
- 403 insufficient_scope — 令牌缺少 memory:read 权限：生成具有所需范围的令牌。
- 错误的安装目标 — 验证 XMEMO_SKILL_DIR 是否已设置为 ~/.codex/skills/xmemo-memory。
- 需要重新加载 Skill — 重启 Codex 以确保内存中的 skills 重新加载。

## 更新与移除

Codex 的维护流程：

- 更新：重新运行安装程序命令以获取最新的 Skill 版本，或更新 MCP 端点 URL。
- 移除：删除 ~/.codex/skills/xmemo-memory 目录，或从 ~/.codex/config.toml 中移除 [mcp_servers.xmemo]。

## Codex

Direct client: Codex reads XMEMO_KEY through bearer_token_env_var and sends non-secret identity headers. Run npx @xmemo/client mcp add codex --write to generate the stable XMEMO_AGENT_INSTANCE_ID automatically.

```
[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

[mcp_servers.XMemo.http_headers]
X-Memory-OS-Agent-ID = "codex"

[mcp_servers.XMemo.env_http_headers]
X-Memory-OS-Agent-Instance-ID = "XMEMO_AGENT_INSTANCE_ID"

```