tooluniverse-codex-plugin

为 OpenAI Codex 安装 ToolUniverse 插件

在 Codex 上一步安装：一个 MCP 服务，提供 1000+ 个科学工具和 130+ 个研究技能，全部自动配置。（Claude Code 版本请参阅 tooluniverse-claude-code-plugin。）

前置条件（检查一次即可）

uv --version     # provides `uvx`; if missing:  curl -LsSf https://astral.sh/uv/install.sh | sh
codex --version  # OpenAI Codex CLI; if missing: https://developers.openai.com/codex

安装（两条命令）

# 1. Register the ToolUniverse marketplace from GitHub
codex plugin marketplace add mims-harvard/ToolUniverse

# 2. Install the plugin from that marketplace
codex plugin add tooluniverse -m tooluniverse

重启 Codex。MCP 服务会在首次使用时通过 uvx tooluniverse 自动启动（软件包下载期间冷启动约需 30 秒，之后即可即时启动）。

mims-harvard/ToolUniverse 是 owner/repo 简写，因此 Codex 会将其记录为 Git 市场——这正是启用自动更新的方式（参见“更新”）。不要将其指向插件子文件夹或原始 URL。

验证是否成功

codex plugin list           # expect: tooluniverse (enabled)
codex plugin list --json    # the JSON includes the installed "version"

然后直接在 Codex 中自然地提问：

What are the top mutated genes in breast cancer?
Research the drug metformin.

研究技能会在问题匹配时自动激活，MCP 工具则会通过 find_tools → execute_tool 发现并运行——无需命令前缀。

你将获得什么

组件	功能	使用方式
MCP 服务	通过 find_tools、get_tool_info、execute_tool 提供 1000+ 个工具	自动加载；无需操作
130+ 项技能	结构化研究工作流——药物发现、变异解读、药物警戒、系统发育学、统计建模等	问题匹配时自动激活

与 Claude Code 插件不同，Codex 插件仅包含 MCP 工具和技能——没有斜杠命令。你只需自然地提问即可完成所有操作。

API 密钥（可选，但建议设置）

大多数工具无需密钥即可使用。若要提高速率限制或访问受限数据库，请在启动 Codex 的环境中设置所需密钥——MCP 服务（uvx tooluniverse）会继承这些密钥：

export NCBI_API_KEY="your_key"
export ONCOKB_API_TOKEN="your_token"
export SEMANTIC_SCHOLAR_API_KEY="your_key"
# ...then start codex from that same shell

导出的环境变量是更可靠的选择，因为它们在插件升级后仍会保留。（你也可以改为编辑缓存中已安装插件的 .mcp.json 里的 env 区块——见下文——但每次更新都会替换缓存副本。）

完整密钥列表：内置的 setup-tooluniverse 技能 → API_KEYS_REFERENCE.md。

更新

Codex 默认会在启动时自动升级 Git 市场。由于你已将 mims-harvard/ToolUniverse（owner/repo）作为 Git 市场添加，新发布的版本会在你下次启动 Codex时自动送达，无需进行任何操作。（没有 codex plugin update 命令——更新由市场驱动。）

如需按需刷新，而非等待自动更新：

codex plugin marketplace upgrade              # all configured Git marketplaces
codex plugin marketplace upgrade tooluniverse # just this one

在 TUI 中打开 /plugins，并在市场选项卡中按 Ctrl+U。

工具本身通过 uvx 从 tooluniverse PyPI 软件包获取，因此如果升级后工具似乎没有更新，请清除 uvx 缓存：

uv cache clean tooluniverse

固定工具版本（可选，确保可复现）

如需在长期分析中锁定工具行为，请编辑已安装插件的 .mcp.json 并固定软件包版本：

"args": ["[email protected]"]

将 1.3.0 替换为 https://pypi.org/project/tooluniverse/ 中的任意版本，然后重启 Codex。（可在 ~/.codex/plugins/cache/ 下找到该文件。）

卸载

codex plugin remove tooluniverse
codex plugin marketplace remove tooluniverse

其他安装方式（本地检出 / 隔离网络）

git clone https://github.com/mims-harvard/ToolUniverse.git
codex plugin marketplace add ./ToolUniverse
codex plugin add tooluniverse -m tooluniverse

通过本地路径添加的市场不会自动升级（只有 owner/repo Git 市场才会自动升级）。拉取新提交后，请重新运行 codex plugin marketplace upgrade 或重启 Codex。

故障排除

症状	解决方法
marketplace add 失败	使用 mims-harvard/ToolUniverse（所有者/仓库），不要使用指向插件子文件夹的路径或原始 URL。
uvx: command not found	安装 uv（参见先决条件），然后重新打开终端。
插件已安装，但没有工具	重启 Codex；首次启动时会下载软件包（约 30 s）。检查服务是否正常：在终端中运行 uvx tooluniverse。
MCP 服务无法启动	如果在普通终端中运行 uvx tooluniverse 也失败，那就是 uv/Python 问题，而不是 Codex 的问题。
requires-python >= 3.10	uv python install 3.12
更新后工具看起来过时	运行 uv cache clean tooluniverse，然后重启 Codex。
一直没有收到更新	自动升级仅适用于 Git 市场（所有者/仓库）。如果添加的是本地路径，请运行 codex plugin marketplace upgrade。
工具运行的是旧版本	uv tool list | grep tooluniverse — 全局 uv tool install tooluniverse 会覆盖 uvx。解决方法：运行 uv tool uninstall tooluniverse，然后重启。

仍未解决？请访问：https://github.com/mims-harvard/ToolUniverse/issues

自动诊断与修复

将此技能交给 Agent — “阅读 tooluniverse-codex-plugin 技能，并诊断和修复我的 Codex 插件” — 或依次运行以下命令。这些命令安全且幂等；对失败的项目应用相应的 FIX，然后重启 Codex。

# 1. Is uv/uvx installed?  (most common cause of "no tools at all")
command -v uvx || echo "FIX: curl -LsSf https://astral.sh/uv/install.sh | sh"

# 2. Can the MCP package resolve + run?  (non-hanging proxy for the server)
uvx --from tooluniverse tu --version || echo "FIX: uv/Python issue — see steps 1 and 6"

# 3. Is the plugin installed + enabled?
codex plugin list | grep -q tooluniverse || echo "FIX: codex plugin add tooluniverse -m tooluniverse"

# 4. Running an OLD version even after updating?  (a global install shadows uvx)
uv tool list | grep -q tooluniverse \
  && echo "FIX: uv tool uninstall tooluniverse" \
  || echo "ok: nothing shadowing uvx"

# 5. Pull the latest plugin version now (don't wait for next startup)
codex plugin marketplace upgrade tooluniverse

# 6. Python too old (requires >= 3.10)?
uv python install 3.12

# 7. Force a fresh tool package
uv cache clean tooluniverse        # or one-shot: uvx --refresh tooluniverse --version

面向插件维护者

此技能介绍的是面向用户的安装流程。Codex 插件源代码位于 plugins/tooluniverse/，其中包含自己的 .codex-plugin/plugin.json、.mcp.json 和 skills/。仓库根目录下的 .agents/plugins/marketplace.json 使 codex plugin marketplace add mims-harvard/ToolUniverse 命令能够正常运行——它将插件列为 "source": {"source": "local", "path": "./plugins/tooluniverse"}（此路径位于克隆的市场仓库内部，而非外部）。

• 技能是生成的副本 — 请编辑规范的 skills/ 树，然后运行 plugin/sync-skills.sh。该脚本会重建 Claude 和 Codex 的技能集，并应用 Codex 专属的规范化处理（移除 Codex 会忽略的 disable-model-invocation 标记，并精简超出 Codex 1024 字符限制的描述）。
• Codex 插件版本位于 plugins/tooluniverse/.codex-plugin/plugin.json 中；scripts/release-plugin.sh 会同时更新该版本和 Claude 清单中的版本，确保两个插件都遵循 <package MAJOR.MINOR>.<plugin revision> 版本格式。
• Codex 通过 git push 提供更新（启动时自动升级），与版本字符串无关 — 但更新版本号可以保持两个插件版本一致，并用于 Codex 的版本缓存。