Grok 插件 Codex

grok-plugin-codex 通过一个捆绑的 Node/TypeScript MCP 服务器，向 Codex 暴露本地安装的 Grok CLI。Codex 仍然负责作用域、工作区状态、验证、git 和最终判断；Grok 是一个有限的第二平面。

当前版本为 0.3.0。它规范了 Grok 的停止原因词汇（end_turn 和 EndTurn 视为同一事实），正确分类超时和配额耗尽，将调度工具默认设为后台并附带按种类的时限预算，在每一个非完整结果上返回恢复句柄，拒绝将在没有一次工具调用的情况下得出的判断报告为已完成审查，并新增了 grok_finalize —— 一种单轮、无工具的方式来恢复已存在的答案。有关完整的合约变更，请参阅 CHANGELOG.md。版本 0.2 引入了私有中央工作进程架构和类型化的 MCP 信封。

仓库: https://github.com/handong66/grok-plugin-codex 文档: https://han-dong.link/en/work/grok-plugin-codex

要求

• Node.js >=22

• npm

• macOS 或 Linux

• Codex 本地插件市场支持

• 已安装并认证的 Grok CLI

请分别检查三个运行时层面：

grok --version   # CLI can be discovered
grok --help      # installed flags/capabilities
grok models      # authentication and model listing

一个列出的模型未必已完成实际调用。grok_check 保留这一区别。

Related MCP server: chatgpt-codex-local-mcp

安装

npm install
npm run check
codex plugin marketplace add .
codex plugin add grok-plugin-codex --marketplace grok-plugin-codex

安装或升级后，启动一个新的 Codex 任务。现有任务会保留其在启动时加载的 MCP 服务器和技能快照。如果一个新的 Codex Desktop 任务看到了更新的技能但未看到更新的 MCP 工具，请重启 Codex Desktop 并创建另一个任务；Desktop 进程可能在重新安装后仍保留其 MCP 注册表。

安装的捆绑包包含以下两项：

plugins/grok-plugin-codex/dist/server.js
plugins/grok-plugin-codex/dist/job-worker.js

能力范围

• grok_check、grok_models：CLI/能力、认证、授权和模型诊断。authenticated 和 entitled 的取值是 true、false 或 "unknown"——永远不会是 null。

• grok_run、grok_continue：显式提示执行和已知会话的延续。

• grok_finalize：单轮、无工具、完整答案——用于恢复因超时、达到轮数限制、取消或被权限阻止的运行。

• grok_rescue、grok_review、grok_adversarial_review：强制只读、无子代理的第二轮审查。每个都需要一个 target（或 problem），同组的插件名称 prompt 也被接受。grok_adversarial_review 接受可选的 threatModel；超出该模型的发现仅作为建议，不会阻止。

• grok_sessions、grok_export：显式工作区的会话检查和 Markdown 导出。

• grok_status、grok_result、grok_cancel：仅通过 jobId 管理的私有中央后台任务生命周期。grok_status 返回廉价的进度（textChars、eventCounts、lastEventAt、toolCallCount、deniedToolCalls），并接受可选的 waitMs（≤ 30 秒）服务端等待；grok_result 通过 finalTextOffset/finalTextMaxChars 分页返回 finalText。

当前 MCP 的 listTools 模式对精确参数具有权威性。仓库的冒烟测试锁定了已发布范围并拒绝偏离。

结果合约

成功操作返回：

{ "ok": true, "data": {}, "error": null, "warnings": [] }

业务失败设置 MCP isError: true 并返回：

{
  "ok": false,
  "data": null,
  "error": { "code": "typed_code", "message": "actionable message", "retryable": false },
  "warnings": []
}

输入模式违规是 SDK 生成的工具错误（isError: true），不带插件业务信封；客户端必须检查已解析的工具结果，而不是仅依赖 promise 拒绝。每个工具都发布输出模式，插件处理的 JSON 文本反映了 structuredContent。

工作区和提示边界

工作区操作需要 cwd。服务器规范化符号链接，并要求解析后的目录必须位于活跃的 MCP 工作区根目录内。私有 Codex 路径（如 ~/.codex）被阻止，除非用户明确授权该风险。

提示会短暂地暂存在私有的 0600 文件中，以便分离的工作进程能在 MCP 服务器退出后存活。工作进程在 Grok 运行前读取并删除暂存文件，然后通过随机 0700 目录中的 0600 FIFO 提供提示。Grok 仅通过原生的 --prompt-file 接收该私有路径名；启动器在 Grok 打开它后立即取消链接，然后再写入任何提示字节。提示文本不会放入子进程参数列表或任务记录中。GROK_BIN 是唯一支持的自定义可执行配置，并且必须来自受信任的 MCP 环境。

后台任务

后台任务在分离的工作进程中运行，并在 MCP 服务器重启后存活。状态存放在以下位置：

1. 当显式配置时：$GROK_PLUGIN_STATE_DIR

2. $XDG_STATE_HOME/grok-plugin-codex

3. ~/.local/state/grok-plugin-codex

显式状态目录必须与每个活跃的工作区根目录不重叠：既不能在一个根目录内部，也不能是其祖先目录。它必须为空、携带插件的所有权标记、或匹配严格的私有预标记任务布局；插件不会认领或 chmod 一个已有的共享目录。这些检查在创建或更改仓库本地状态之前会失败关闭。

目录使用 0700；记录、日志、提示暂存文件、取消标记、心跳和所有者令牌跨进程锁使用 0600。记录写入是原子性的，终端状态是单调的。取消操作通过由所属工作进程消费的标记线性化。每个进程组由一个私有启动器引导，其命令标识包含任务 ID 和随机任务令牌；过期工作进程的协调仅在所有三个匹配时终止持久组，启动器在退出前会移除残留的后代进程。

调度工具（grok_run、grok_review、grok_adversarial_review、grok_rescue）默认 background: true；grok_continue 默认为前台。保存 data.job.id，然后使用 jobId 调用任务工具。前台调用（background: false）最多阻塞 timeoutMs 加上 10 秒宽限期，然后返回带有该任务 ID 的 foreground_wait_timeout。省略的 timeoutMs 按种类默认——run/continue 为 180000，review/rescue 为 240000，adversarial_review 为 300000——显式值在任何方向上都不会被截断；两个有效值都会作为 effectiveTimeoutMs/effectiveMaxTurns 返回。对于后台任务，推荐的节奏是先调用一次 grok_status 带上 waitMs，然后调用一次 grok_result，而不是轮询循环。只有以下组合是最终的：

data.resultComplete === true

在内部，完整性还需要非空的最终文本和正常结束事件，并且对于 grok_review 和 grok_adversarial_review，需要至少一次工具调用，因为一个未打开任何内容的审查者得出的判断只是意见（no_evidence_review）。只读种类以计划模式运行，其中 shell 执行会被自动拒绝：将审查所需的差异或命令输出内联到目标中，而因为 shell 命令需要批准而被取消的运行会报告为 permission_denied_headless，而不是作为过宽的目标。停止原因按大小写和分隔符不敏感的方式规范（end_turn 和 EndTurn 是同一事实），原始值保留在 outputSummary.stopReason 中，调用方不应自己进行字符串匹配。取消的结束返回为 cancelled_output。在真实文本后出现无法识别的停止原因时，会被接受并带有 stopReasonRecognised: false 加一个警告，而不是被丢弃。

每一个非完整结果都带有一个恢复句柄——前台失败调用上的 error.details.recovery，grok_result 上的 data.recovery——其形式为 { jobId, grokSessionId, partialTextChars, suggested: { tool: "grok_finalize", args }, fallback: { tool: "grok_continue", args } }。该句柄按原样可执行：suggested 是单次调用的恢复，而 fallback 是面向仅支持 grok_continue 的调用者的相同表达（maxTurns: 1 加上 grok_finalize 提示）。两者都不要求缩短答案。对于 max_turns_reached 以及被取消或超时的运行，补救措施是使用该任务 ID 调用 grok_finalize，或者手动执行相同调用：以 maxTurns: 1 继续同一会话，并附带一条提示，告诉 Grok 停止使用工具并立即输出最终答案。不要缩小目标、提高 maxTurns 或重新运行任务——部分答案永远不会被销毁，error.details.finalTextRef 是任务 ID，并且 grok_result 会返回完整的捕获文本，无论 resultComplete 如何。

resultComplete 本身处理了截断问题：outputTruncated 仅表示共享捕获窗口溢出（通常是工具调用回显），而 textTruncated 表示答案文本被丢弃，这是否决完整性的标志。过大的工具负载在捕获时会被省略，available_commands 负载会被丢弃；设置 GROK_PLUGIN_RAW_CAPTURE=1 以保留供应商流的原文用于插件开发。

请使用 data.finalText。部分状态仅用于诊断，原始逐令牌日志尾部仅在调用 grok_result 并设置 includeRawTail: true 时返回。工作进程将答案保存在追加写入的 <id>.final.txt 账本中，流事实保存在 <id>.summary.json 中，因此 grok_result 从该账本中回答，而不是重新解析原始流，并且 grok_status 从同一文件中读取进度。终端任务工件保留七天，并会被机会性地清理。

从 0.1 升级

• 升级前，请完成或取消 0.1 的后台任务。

• 0.2 不会扫描或信任旧的 <workspace>/.grok-plugin-codex/jobs 记录。

• 旧的工作区目录不会自动删除，因为它们属于用户的工作区。

• 已移除每次调用的可执行选择、调用者选择的导出文件、隐式审查目标以及任务控制的 cwd。

隐私边界

该插件不会将隐藏的 Codex 上下文、系统/开发者消息、推理、任意工具输出、秘密或凭据复制到提示中。它无法删除调用者显式提供的敏感文本。请参阅 docs/privacy.md。

开发

npm install
npm run check
git diff --check

可选的身份验证调用：

npm run smoke:live-grok

运行时模式和测试具有权威性。捆绑的 README/技能文件是安装后的用户合约；test/contract-drift.test.ts 和 MCP 冒烟测试防止已移除的参数或版本不匹配重新出现。

请参阅 docs/development.md 和 docs/verification.md。

项目政策

• 隐私政策

• 使用条款

• 安全政策

• 贡献指南