编码代理与终端 · session · 验证于 2026-08-31 ✓ 实测验证

oh-my-pi

已验证 2026-08-31CLI + VS Code 扩展安装实测通过；接入 IDE 的编码 agent（Claude Code/Codex 类工作流）。

接入 IDE 的编码 agent（CLI + VS Code 扩展；Claude Code/Codex 类工作流）

详细版 → 所属问题域：编码代理与终端 遇到问题？去问题空间 →

你会遇到什么

这个工具解决什么问题：一个 IDE 原生的编码 Agent（CLI + VS Code 扩展），工作流对标 Claude Code / Codex：在终端或编辑器里给它任务，它读代码、改代码、跑命令、给你结果。 什么时候用：

  • 你要在 IDE/终端里跑一个编码 Agent（非插件形态，独立 CLI）；
  • 你要多项目/多供应商隔离（--profile + --alias）；
  • 你要解包它的内置子代理（agents unpack）扩展能力。

什么时候别用：你已经固定在某个 Agent 插件上、不需要再引一个二进制时；或没有可用 API key（完整编码会话需要）。 注意事项：重档条目——单二进制 183MB；运行即写 ~/.omp/logs/；完整编码会话需 API key（ANTHROPIC_API_KEY 等，本环境未实测）。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：单二进制 omp（Linux x86_64，gh-proxy 下载）。CLI 面：--model/--provider/--profile/--mode/--print 等 flags + 环境变量面（OMP_PROFILE / PI_CODING_AGENT_DIR）+ 工具清单（read/bash/edit/write/task/browser 等）。非交互单轮用 --print；子代理用 agents unpack 导出；profile 隔离 auth/sessions/settings/caches。 关键概念：

  • --print：非交互单轮输出（文本模式）；
  • agents unpack：导出内置子代理到 ~/.omp/agent/agents；
  • --profile + --alias：多项目/多供应商隔离（如 omp-work 别名）。

装完它动哪里：~/.omp/（logs/agent 等；运行即写）；项目内 .omp/（子代理项目形态）。

快速修复（不想看讲解，直接跑）

note: release 二进制（本环境实测，gh-proxy 加速）；国内 GitHub 直连慢必须加速
curl -sL -o omp https://gh-proxy.com/https://github.com/can1357/oh-my-pi/releases/download/v18.0.11/omp-linux-x64
chmod +x omp
./omp --version

预期输出: omp/18.0.11

一步步来

第 1 步：装二进制（为什么 gh-proxy：国内 GitHub 直连慢）

讲解：单二进制 183MB，下载走 gh-proxy 前缀（国内直连慢）。chmod +x 即用，无运行时依赖。装完 --version 验证。

curl -sL -o omp https://gh-proxy.com/https://github.com/can1357/oh-my-pi/releases/download/v18.0.11/omp-linux-x64
chmod +x omp
./omp --version

预期输出: omp/18.0.11

装好确认：

  • --version 输出 omp/18.0.11；
  • omp --help 能看到完整 flags 与工具清单。

卡住怎么办：

  • 下载慢/失败 → 确认网络到 gh-proxy；换网络重试；
  • 想全局用 → 放入 PATH（如 /usr/local/bin，注意 183MB 单文件）。

第 2 步：非交互单轮（--print，需 API key；本环境未实测——无 key）

讲解：--print 是文本模式单轮调用，适合脚本/管道。需要 API key（--model 指定模型）。

omp --print "explain this repo in one sentence" --model gpt-5.2

预期输出: 模型回复（文本模式）

装好确认：

  • 输出模型回复，无 key 报错。

卡住怎么办：

  • 报缺 key → 设置 ANTHROPIC_API_KEY 等环境变量，或 --provider 指定供应商。

第 3 步：解包子代理 + profile 隔离（按需）

讲解：agents unpack 导出内置子代理（命令来自 --help，未实测）；--profile work --alias omp-work 创建隔离别名（auth/sessions/settings/caches 分开），适合多项目/多供应商。

omp agents unpack

预期输出: 导出内置子代理到 ~/.omp/agent/agents（项目形态用 --project → ./.omp/agents）

omp --profile work --alias omp-work

预期输出: 创建 shell 别名 omp-work（隔离 auth/sessions/settings/caches）

卡住怎么办：

  • agents unpack 报错 → 命令来自 --help（本环境未实测），以官方文档为准；
  • 别名没生效 → 确认 shell 配置文件已加载（新开终端或 source）。

怎么确认修好了

第 1 步：确认命令与帮助面

讲解：omp --version 输出 omp/18.0.11、omp --help 能看到完整 flags 与工具清单，说明二进制完整、可执行。

./omp --version
./omp --help

预期输出: omp/18.0.11；完整 flags 与工具清单

卡住怎么办：

  • 版本对不上 → 重新下载（注意 183MB 单文件完整性）；
  • 命令找不到 → 确认路径与 chmod +x。

第 2 步：确认调用链路（需 API key，本环境未实测）

讲解：--print 能拿到模型回复，说明二进制 + provider 链路都通；报缺 key 则是环境变量没配。

omp --print "explain this repo in one sentence" --model gpt-5.2

预期输出: 模型回复（文本模式；本环境无 API key 未实测）

卡住怎么办：

  • 报缺 key → 设置 ANTHROPIC_API_KEY 等环境变量，或 --provider 指定供应商；
  • 想隔离多项目 → 用 --profile work --alias omp-work 创建隔离别名（auth/sessions/settings/caches 分开）。

其它环境的表现（常见变体）

  • 非 Linux x86_64：官方提供对应平台二进制（本机未实测，命令面一致）；单二进制无运行时依赖。
  • 想全局用：放入 PATH（如 /usr/local/bin，注意 183MB 单文件）。
  • 写面：运行即写 ~/.omp/（logs/agents）；项目形态写项目内 .omp/——专属目录，与常用工具不重叠。
  • 运行时：完整编码会话需要 API key；--print 文本模式适合脚本/管道。

日常使用

启动与入口

CLI 直接调用；入口 omp --help。

常用操作

操作一：查看命令面（本环境实测）

omp --help

预期输出: USAGE + FLAGS（--model/--provider/--profile/--mode/--print 等）+ 环境变量面（OMP_PROFILE/PI_CODING_AGENT_DIR）+ 工具清单（read/bash/edit/write/task/browser 等）

操作二：非交互单轮（--print，需 API key；本环境未实测——无 key）

omp --print "explain this repo in one sentence" --model gpt-5.2

预期输出: 模型回复（文本模式）

操作三：解包子代理（本环境未实测——命令来自 --help）

omp agents unpack

预期输出: 导出内置子代理到 ~/.omp/agent/agents（项目形态用 --project → ./.omp/agents）

操作四：Profile 隔离（多项目/多供应商切换）

omp --profile work --alias omp-work

预期输出: 创建 shell 别名 omp-work（隔离 auth/sessions/settings/caches）

数据与目录

  • 日志/子代理：~/.omp/（logs/agent/agents；运行即写）；
  • 项目形态：./.omp/agents（--project 时）。

卸载与清理

note: 单二进制删除；~/.omp 专属目录自动删；项目内 .omp/ 按需手动清理
rm -f /usr/local/bin/omp ~/.local/bin/omp
rm -rf ~/.omp
command -v omp >/dev/null 2>&1 && echo '残留: omp 仍存在' || echo 'oh-my-pi removed: OK'

预期输出: oh-my-pi removed: OK

依赖警告

  • 版本：[18.0.11, 18.0.11] 锁定（2026-08-31 升级重测：gh-proxy 下载 185.5MB + --version 自报 18.0.11 + --help 命令面完整，证据）；完整会话未运行（需 provider 与账号，零账号纪律，与收录口径一致）。
  • 环境：Linux x86_64；无运行时依赖；单二进制 183MB。
  • 网络：GitHub 直连慢，必须 gh-proxy 前缀（实测路径）。
  • 写面：~/.omp/（logs/agents；运行即写）；项目内 .omp/。
  • 运行时：完整编码会话需 API key（ANTHROPIC_API_KEY 等）。
  • 共装：冲突矩阵对子见矩阵页（~/.omp 专属写面，与常用工具不重叠）。

FAQ（常见问题）

  • 问：二进制太大（183MB）？答：单二进制自包含（无运行时依赖）；下载走 gh-proxy 前缀。
  • 问：--print 报缺 key？答：设置 ANTHROPIC_API_KEY 等环境变量，或 --provider 指定供应商。
  • 问：多项目怎么隔离？答：--profile + --alias（如 --profile work --alias omp-work），auth/sessions/settings/caches 分开。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。
验证证据
  • 实测：实测记录（本地留存）（2026-08-28，release 二进制下载 + version/help 冒烟）。
  • 未实测：完整编码会话（无 API key）；agents unpack 与 profile 别名（命令来自 --help）。

引用：oh-my-pi · 验证于 2026-08-31 · v18.0.11~18.0.11

相关问题（问题域）

出问题了？排障方案

排障手册：oh-my-pi

症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：维护者 检索素材（Qiita kai_kou / issue #36 / CHANGELOG v17.1.x / demand 样本 omp-compact#8）+ 本市场实测（2026-08-28 本地项目隔离安装 + 命令面）。
采集纪律：零账号匿名检索；未碰 GitHub。check-words HARD 0。

基本信息

  • 条目名称：oh-my-pi（can1357/oh-my-pi，MIT，v18.0.7 收录；实测装到最新 18.0.9）
  • 求助信号：help=55 / recent3m=52 / trend=up（demand 基线 demand-signal-20260828）
  • 角色：anchor；分类：session
  • 本市场安装路径：bun install -g @oh-my-pi/pi-coding-agent（国内建议 BUN_CONFIG_REGISTRY=https://registry.npmmirror.com，npm 官方源直连卡解析）；验证 omp --version；卸载 bun remove -g @oh-my-pi/pi-coding-agent
  • 命令名：omp（package.json bin 实读：{'omp': 'dist/cli.js'}）

症状 → 原因 → 解法 → 验证证据

1. 安装成功但 omp --version 报 SyntaxError（旧版 bun）

症状

bun install -g @oh-my-pi/pi-coding-agent 显示安装成功，但执行 omp --version 报 SyntaxError（或直接无声失败，无版本输出）。

原因

package.json engines 要求 bun >=1.3.14（本市场实测实读 engines 字段确认）；bun 1.3.11 及更早版本运行该包时解析新语法失败，报 SyntaxError 且不提示版本不兼容（来源：Qiita kai_kou，2026-08 检索；OrcaRouter 中文文档同标 bun >=1.3.14，相互印证）。

解法

  1. 升级 bun 到 >=1.3.14：curl -fsSL https://bun.sh/install | bash（或包管理器升级），验证 bun --version。
  2. 升级后重跑 omp --version 确认输出 omp/<版本>。

验证证据

  • 本市场实测（2026-08-28，bun 1.4.0）：本地项目安装 @oh-my-pi/pi-coding-agent@18.0.9 后 omp --version 输出 omp/18.0.9；package.json engines 实读为 {'bun': '>=1.3.14'}。
  • 旧 bun 1.3.11 复现（2026-08-28 补完）：bun 1.3.11 前置 PATH 执行 omp --version → SyntaxError: Unexpected identifier 'u'（cli.js:159:1），与 Qiita 症状一致；对照 bun 1.4.0 → omp/18.0.9 正常（实测复现日志（2026-08-28））。

2. 命令混淆：omp install 与 omp plugin install

症状

用户按网上教程执行 omp install <插件名> 失败或行为不符预期；正确姿势是 omp plugin install <插件名>。

原因

npm 页面曾给出错误指令 omp install（来源：issue #36）；在 18.0.9 中 omp install 已被实现为 omp plugin install 的别名（帮助文本明示 alias of plugin install/plugin link），但旧文档/旧教程仍以错误姿势传播，新旧混用造成混淆。

解法

  1. 显式使用 omp plugin install <name>（最不易歧义）。
  2. 不确定时先 omp --help 自查子命令（install / plugin 均会列出）。

验证证据

  • 本市场实测（2026-08-28）：omp --help 输出同时含 install（标注 alias of plugin install/plugin link）与 plugin 子命令。

3. Windows/ARM release 二进制加载外部扩展失败

症状

独立 omp 安装加载外部扩展报 @oh-my-pi/pi-* is not host-provided（Windows），或扩展加载静默失败（darwin-arm64）；典型求助样本：omp-compact#8（2026-08-28 demand 捕获）。

原因

CHANGELOG v17.1.0 到 v17.1.5：Windows 编译二进制加载外部扩展失败（bare @oh-my-pi/pi-* 值导入问题）；darwin-arm64 release 二进制扩展静默失败（import.meta.dir 处理 bug）。均于 v17.1.5 修复。

解法

升级到 >=17.1.5（当前最新 18.0.9 已含修复）：bun install -g @oh-my-pi/pi-coding-agent@latest（或按你的安装方式升级）。

验证证据

  • 素材引用：CHANGELOG v17.1.0/v17.1.5 + demand 样本 omp-compact#8（维护者 检索核验）。
  • 本环境为 Linux/WSL，Windows/ARM 二进制未实测——如实标注；Linux 侧扩展加载不在该症状范围。

4. 名称混淆：oh-my-pi（omp）vs pi-mono（pi）

症状

搜索/阅读资料时把 oh-my-pi 与 pi-mono 混为一谈，安装后命令名对不上（pi vs omp）。

原因

oh-my-pi（can1357/oh-my-pi）是硬 fork，命令名为 omp；pi-mono 为原项目，命令名为 pi。两者同源不同命令，文档与教程混用导致装错/查错。

解法

  1. 按命令名认项目：装完执行 omp --version 的是 oh-my-pi；pi --version 的是 pi-mono。
  2. 查文档认准仓库：can1357/oh-my-pi（manifest 签名），勿混用 pi-mono 教程的安装命令。

验证证据

  • 本市场实测（2026-08-28）：安装包 @oh-my-pi/pi-coding-agent 的 bin 名实读为 omp（package.json bin: {'omp': 'dist/cli.js'}），omp --version 输出 omp/18.0.9。

未能实测项（如实标注）

  • Windows / darwin-arm64 二进制扩展（Linux/WSL 无对应资产）；真实编码会话（需 API key）；VS Code 扩展形态。
  • 环境机制发现：bun 1.4.0 的全局安装目录绑定 ~/.bun（设置 HOME 不生效），无法按手册 §5 隔离；本卡改用本地项目安装验证，系统全局已清理还原（详见反馈 oh-my-pi.@codex-ci.md）。

矩阵暂无该工具对子。

← 返回工具货架 ｜ 遇到其它问题？去 问题空间 提交求助卡 ｜ 预检与证据记录由维护流程本地留存，仅公开结论与来源