codex-narp-runtime

Codex NARP Runtime

使用这个 skill 时，目标不是让用户自己准备 PATH 或手改配置，而是把 Codex 接成 NextClaw 统一 runtime registry 里的正式会话类型。

首选产品路径固定为：

• runtime entry id: codex
• runtime entry label: Codex
• runtime type: narp-stdio
• wire dialect: acp
• runtime launcher: nextclaw-codex-narp
• route ownership: NextClaw -> RuntimeRoute(model/apiBase/apiKey/headers) -> Codex NARP wrapper -> Codex SDK/CLI

不要把 Codex 做成核心系统里的 provider 特判。NextClaw 核心、kernel、service 只感知 narp-stdio，不感知 codex。

安装边界

始终区分三层：

• 这个 NextClaw marketplace skill：负责用户接入流程、检查、修复和冒烟。
• Codex NARP wrapper：@nextclaw/nextclaw-narp-runtime-codex-sdk，提供 nextclaw-codex-narp。
• Codex SDK/CLI：由 wrapper 调用，真实执行 agent loop。

安装这个 skill 不等于 Codex runtime 已经可用。skill 必须自己检测 launcher，缺失时安装或修复 wrapper，并生成 NextClaw 可稳定调用的绝对路径 shim。

这个 Skill 负责什么

• 解释 Codex 通过 NARP stdio 接入的正确心智模型。
• 发现、安装、显式更新或修复 nextclaw-codex-narp。
• 在 ${NEXTCLAW_HOME:-~/.nextclaw}/bin 下生成稳定 shim。
• 写入或修复 agents.runtimes.entries.codex。
• 运行 runtime probe。
• 运行真实 Codex 首条消息冒烟；需要能力验收时继续覆盖工具调用和思考事件。
• 对常见失败给出有界诊断，不把问题推给用户自己猜。

禁止事项

• 不要告诉用户“先把 nextclaw-codex-narp 放到 PATH 里”作为完成条件。
• 不要要求用户手工编辑 config.json，除非当前 agent 没有文件写权限。
• 不要修改通用 NARP stdio client 来识别 Codex。
• 不要在 core/kernel/service 注入 Codex 默认 entry 或 provider 分支。
• 用户没有明确要求“更新”“升级”或指定目标版本时，不要查询最新版或改动一个已经可用的 wrapper。
• 显式更新不能用“现有 launcher 能运行”或“源码仓库里有 dist”代替版本升级。
• 没有 probe 和真实模型回复时，不要声称已经完成接入。

Setup 流程

当用户要求“接入 Codex”“安装 Codex runtime”“doctor Codex runtime”或类似目标时，按下面顺序执行。

1. 确认工作目录和数据目录

先确定 NextClaw 数据目录：

NEXTCLAW_HOME="${NEXTCLAW_HOME:-$HOME/.nextclaw}"

需要写入：

• $NEXTCLAW_HOME/bin/nextclaw-codex-narp
• $NEXTCLAW_HOME/config.json

如果这是首次接入，先说明 Codex runtime 会读取本机工作区并可能执行本地工具；涉及删除、发送、提交、发布等外部可见动作时仍需用户确认。

2. 解析可用 launcher

按优先级解析真实 launcher：

1. 如果当前在 NextClaw 源码仓库，并且存在已构建文件： packages/extensions/nextclaw-narp-runtime-codex-sdk/dist/controllers/codex-narp.controller.js
2. 如果源码存在但 dist 不存在，先构建： pnpm --filter @nextclaw/nextclaw-narp-runtime-codex-sdk build
3. 如果系统已有 nextclaw-codex-narp，可作为真实 launcher 来源。
4. 否则安装 wrapper 包到 NextClaw 管理目录：