安装

安装 Ouroboros

默认路径是 Claude Code 插件：登录、装插件、ooo setup、验证，四步。文末另有不依赖 Claude Code 的独立命令行装法。

1. 装之前先确认

装好并且支持插件的 Claude Code。
主机上要有 uv。插件的 MCP 描述符用 uvx 拉起服务，技能那边也拿它当 Python ≥ 3.12 的兜底。用 pipx install uv、pip install --user uv 或者 brew install uv 都行。
Windows 上请在 WSL 2 里按 Linux 的步骤走。Git Bash 不是 WSL 2，在里面装容易失败，WSL 装不上的话看故障排查指南。

你不需要单独准备一个全局 Python 环境，但 uv 是要的。

在终端开一个 Claude Code 会话：

claude

然后在会话里登录：

/login

预期结果：浏览器认证之后，会话显示已登录。没登录的话，后面的 ooo 命令不会工作。

3. 装插件

下面这条在普通终端里跑，不是在 Claude Code 里面。

claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros

预期结果：claude plugin list 里能看到 ouroboros@ouroboros 处于 enabled。

4. `ooo setup` — 把 Core 通过 MCP 接上

在你要干活的项目目录里开一个 Claude Code 会话，输入：

ooo setup

ooo setup 是挑一个 runtime 配置，把选择写进 ~/.ouroboros/config.yaml，顺带可以往项目的 CLAUDE.md 里加一段命令摘要。MCP 服务的注册归第 3 步装的插件管，所以 ooo setup 不会动 ~/.claude/mcp.json。

预期结果：列出检测到的 runtime，显示 Setup complete! 和配置保存位置（~/.ouroboros/config.yaml）。MCP 连没连上，看第 5 步的 /mcp。setup 完请把 Claude Code 完全关掉再重开。

5. 验证

在 Claude Code 会话里跑：

ooo help

预期结果：列出命令，里面应该有 interview、seed、run、evaluate。

6. 更新

ooo update

预期结果：比较当前版本和最新版本，按你的安装方式更新。更新完重开 Claude Code 会话。

7. 算装好了的标准

claude plugin list 里 ouroboros@ouroboros 是 enabled。
ooo help 能打印出命令列表。
Claude Code 的 /mcp 里 ouroboros 服务显示为已连接。

不用 Claude Code，直接装命令行

独立命令行需要 Python 3.12 或更新版本，在普通终端里装：

pip install ouroboros-ai
ouroboros setup

这条装的是基础包。如果你要的是 MCP 服务本身（比如接 Kiro 这类运行时），装带 extra 的版本：

pipx install 'ouroboros-ai[mcp]'   # 或者：uv tool install 'ouroboros-ai[mcp]'

其他运行时用 ouroboros setup --runtime codex 这样选，装好之后本指南里的 ooo 命令在那边的会话里一样能用，例子只是站在 Claude Code 对话框的角度写的。各运行时的完整说明在中文 README 里。

装不上的时候

如果插件起不来、报 Failed to reconnect to plugin:ouroboros:ouroboros: -32000，先确认版本。0.51.1 修了这个启动失败：在那之前，已有环境里的 mcp 可能盖掉 [mcp] profile 需要的 mcp==2.0.0。修法是让随包发布的启动器走 uvx --isolated。用 ooo update 升到最新版再试。

这一页是对着当前的 README 和源码逐条核过的，不是从英文版直译的。发现对不上的地方，欢迎到 GitHub Issues 说一声。