📦 OrcaReplay 详细部署教程

OrcaReplay 是一个“时间旅行”工具，用于记录、回放、复现和调试 AI 代理（Agent）的运行过程。它能让你精确地重现代理的任何一次运行，并在任意步骤切换到不同模型进行比较，从而高效定位问题、验证修复和评估模型性能。

⚙️ 部署前准备

OrcaReplay 是一个 Node.js 命令行工具，部署过程非常轻量。

环境要求

Node.js：版本 20 或更新版本。你可以通过 node --version 检查。
网络：安装和首次使用需要联网，后续核心功能（回放）可离线运行。
（可选）Git：用于部分代理（如 Claude Code）的自动工作区管理。

🚀 安装 OrcaReplay

通过 npm 全局安装是官方推荐的方式：

1	npm i -g orcareplay

安装完成后，运行以下命令验证并检查环境：

1	orca doctor

此命令会检查 Node、Git 版本以及系统上可识别的代理（如 Claude Code、Codex CLI）。

从源码安装（用于开发或尝鲜）

如果你想尝试最新未发布的功能：

git clone https://github.com/Continuum-AI-Corp/OrcaReplay.git
cd OrcaReplay
npm ci && npm run build
npm install -g ./packages/cli

这会将 orca 命令安装到全局。

🚀 核心概念与快速上手

OrcaReplay 的核心工作流是：记录 → 回放 → 复现 → 比较。

1. 记录 (Record) 一次代理运行

在项目根目录下，使用 orca record 命令启动你的代理（以 Claude Code 为例）：

1	orca record claude

然后正常使用 Claude Code 执行你的任务。OrcaReplay 会透明地捕获所有交互、模型响应、工具调用、文件更改和 Shell 命令。记录会保存在项目目录下的 .orca/runs/ 中。

注意：如果要记录一个通过终端提示词启动的会话 (-p "任务描述")，可以使用：
1
orca record claude -- -p "请修复登录页面的样式问题"
这对于精确回放至关重要。

2. 回放 (Replay) 上一次运行

录制完成后，你可以离线、免费地重放整个运行过程：

1	orca replay last

这会重放最近一次录制的会话，不产生任何 API 费用。运行结束后会显示与原始记录是否一致（reused、divergences 等）。

3. 复现 (Fork) 并从中间步骤切换模型

这是 OrcaReplay 最强大的功能。你可以从记录的第 N 步开始，将后续的模型调用切换到一个不同的模型：

1 2	# 从第4步开始，换成 Claude Haiku 模型继续执行 orca replay last --from 4 --model claude-haiku-4-5

这让你能精确对比：在相同的代码、相同的对话上下文下，不同的模型会产生怎样不同的结果。

4. 在图形界面中查看

启动内置的 Web 界面来可视化浏览运行过程：

1	orca replay last --ui

或直接：

orca ui

这会打开一个独立的 HTML 页面，可以按时间线查看每一步的详细信息。

⚙️ 配置模型网关 (可选，用于模型比较)

要比较不同模型的输出，你需要配置一个能访问多种模型的网关。OrcaReplay 默认使用其团队开发的 OrcaRouter 服务，但你也可以配置任何 OpenAI 兼容的网关。

1	orca setup

脚本会询问：

网关 URL：默认是 https://api.orcarouter.ai，你也可以修改。
API Key：输入你的网关密钥。密钥会以 0600 权限安全存储。

配置后，你可以列出可用模型：

1	orca models

之后进行模型比较时，就无需重复指定模型列表和密钥了。

🔍 调试与故障排查

查看详细运行日志

1	orca show last

这会以文本形式输出整个运行时间线，包括每个模型请求、工具调用、返回码和文件变更等。

生成因果图

1	orca graph last

这会显示事件之间的因果关系（哪个工具调用导致了哪个文件变更）。这对于理解代理行为背后的“原因”非常有用。

导出为可分享的文件

1	orca export last -o bug.html

这会生成一个单页 HTML 文件，包含完整的运行信息，你可以离线查看或分享给其他人。

📌 支持的主流 AI 代理

OrcaReplay 通过适配器支持多种主流编码代理，无需修改代理本身：

代理	捕获方式	备注
Claude Code	`ANTHROPIC_BASE_URL`	已验证，运行稳定
Codex CLI (API Key)	`OPENAI_BASE_URL`	使用 Responses API
Codex CLI (ChatGPT 登录)	`--tls-intercept`	通过 TLS 拦截捕获
OpenAI Agents SDK	`OPENAI_BASE_URL`	使用 Responses API
Vercel AI SDK	fetch hook	通过 `orca record node -- node app.mjs`
Grok CLI	`GROK_BASE_URL` + hooks	包括其子代理
OpenClaw	`orca record openclaw`	通过钩子捕获其启动的子代理
通用代理	`orca record generic-openai -- <cmd>`	如果它读取 base-URL 环境变量
硬编码 URL 的代理	`orca record exec --tls-intercept -- <cmd>`	通过 TLS 拦截捕获

对于不在此列表中的代理，OrcaReplay 提供了通用捕获机制 (generic-openai, node, exec)，并支持通过 ORCA_BASE_URL_VARS 环境变量指定自定义的 base URL 变量名。

❓ 常见问题

Q: 回放需要联网吗？
- A: 不需要。orca replay 完全离线，不消耗任何 API 额度。
Q: 代理的 API 密钥会泄露吗？
- A: OrcaReplay 在写入记录时会自动屏蔽认证头信息和已知模式的密钥，用占位符替换。但记录文件本身仍属于敏感信息，请妥善保管。
Q: 记录文件保存在哪里？
- A: 所有记录都保存在项目根目录下的 .orca/runs/ 文件夹中。该目录已被自动添加到 .gitignore，防止敏感数据被意外提交。
Q: 如何删除旧的记录？
- A: 可以手动删除 .orca/runs/ 下的目录，或使用 orca gc --older-than 7d 命令清理。
Q: 能否在 CI/CD 中使用？
- A: 可以。OrcaReplay 支持 --json 输出，便于脚本解析。你可以用它来验证代理修复是否引入了回归。
Q: Windows 支持如何？
- A: OrcaReplay 是跨平台的，但 Shell 捕获功能在 Windows 上需要 Git Bash 等 POSIX 环境。orca doctor 会检查并提示。