Omnigent（omni）使用说明

面向本机当前环境（Omnigent 0.5.1 ，以第三方 API 为主）的安装、配置与日常 CLI 用法。

重点包括：第三方 Provider（DeepSeek / Minimax 等） 、以及通过 ACP 接入的 Reasonix / Grok。

1. 是什么

Omnigent（命令入口 omni / omnigent）是多 harness 编排层：

概念	含义
Harness	实际跑任务的编码代理（Claude / Codex / Pi / Hermes / OpenCode / Kimi / ACP 自定义...）
Provider	给 harness 供模型的密钥与 endpoint（DeepSeek、Minimax、OpenRouter...）
ACP Agent	通过 Agent Client Protocol 接入的外部 CLI（如 Reasonix、Grok），在 `omni setup` 里显示为「ACP · ...」

常见误解：Grok / xAI 不是 Omnigent 内置 harness 。本机是用 自定义 ACP 把 grok 挂进 Omnigent；模型可走 Grok 自带的第三方配置（如 DeepSeek）。

2. 安装

2.1 推荐：uv tool

复制代码

# 安装 uv（若尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 Omnigent（可选 cursor 额外能力）
uv tool install 'omnigent[cursor]'

# 确认
which omni
omni --version

本机实际路径示例：

可执行文件：~/.local/bin/omni
包与环境：~/.local/share/uv/tools/omnigent/

2.2 升级 / 检查更新

复制代码

omni update          # 升级到 PyPI 最新版
omni update --check  # 只检查是否有新版本

2.3 依赖的外部 CLI（按需）

用途	命令	说明
Claude	`claude`	Claude Code
Codex	`codex`	OpenAI Codex CLI
Cursor	`cursor-agent`	Cursor Agent
OpenCode	`opencode`	本环境建议钉在 1.17.x（Omnigent 对 1.18.x 可能不兼容）
Hermes	`hermes`	Hermes Agent
Pi	`pi`	Pi coding agent
Kimi Code	`kimi`	`kimi login` 后使用
Reasonix	`reasonix`	多模型 coding agent；Omni 通过 ACP 调用
Grok	`grok`	Grok Build TUI；Omni 通过 ACP 调用

3. 首次配置与持久化

3.1 交互配置（推荐）

复制代码

omni setup

在 Configure harnesses 里为各 harness 选 Provider / 登录 / 装 CLI。

第三方场景常见组合（与本机一致）：

Harness	本机状态示例
Claude	Minmax（gateway）
Codex	Minmax 默认；也可挂 DeepSeek
Pi	DeepSeek 默认；也可挂 Minmax
Hermes	自有配置（如小米 MiMo / Kimi 等，在 `~/.hermes`）
OpenCode	自有 auth（如智谱 coding plan）
Reasonix	ACP · `reasonix acp --model ...`
Grok	ACP · `grok agent ... stdio`

3.2 配置落盘位置（重启电脑不会丢）

路径	内容
`~/.omnigent/config.yaml`	Provider、ACP agents、默认模型等
`~/.omnigent/secrets.json`	API Key（配合系统 keyring）
项目内 `.omnigent/config.yaml`	可选，覆盖用户级默认（类似 `.git/config`）

会丢的是运行时临时目录（如 /tmp/omnigent-*/），不影响正式配置。

3.3 查看当前生效配置

复制代码

omni config list

本机示例摘要：

复制代码

Claude  → gateway minmax / MiniMax-M2.7-highspeed（默认）
Codex   → minmax 默认；另有 deepseek
Pi      → deepseek-v4-flash 默认；另有 minmax
OpenCode 默认模型 → zhipuai-coding-plan/glm-5.2

4. 第三方 Provider（核心）

Omnigent 把「谁提供模型」和「哪个 harness 在跑」拆开。

第三方 = 用厂商自己的 base_url + API Key，而不是官方 Anthropic/OpenAI 订阅。

4.1 内置可一键配置的 key 类厂商

在 omni setup → 某 harness → 添加 key 时常见：

Provider ID	默认 base_url	典型模型
`deepseek`	`https://api.deepseek.com`	`deepseek-v4-flash` 等
`xai`	`https://api.x.ai/v1`	`grok-3` 等（需账号有额度）
`openrouter`	`https://openrouter.ai/api/v1`	按 OpenRouter 目录
`groq` / `mistral` / `together_ai` / `fireworks_ai`	各自 OpenAI 兼容端点	按厂商目录

另有 gateway 形态（本机 Minimax）：同时配 OpenAI 兼容与 Anthropic 兼容表面，供 Claude / Codex / Pi 共用。

4.2 本机当前第三方配置（摘录）

~/.omnigent/config.yaml：

复制代码

providers:
  deepseek:
    kind: key
    default: pi
    openai:
      api_key_ref: keychain:deepseek
      base_url: https://api.deepseek.com
      models:
        default: deepseek-v4-flash
      wire_api: chat

  minmax:
    kind: gateway
    default: true
    openai:
      api_key_ref: keychain:minmax
      base_url: https://api.minimaxi.com/v1
      models:
        default: MiniMax-M2.7-highspeed
      wire_api: chat
    anthropic:
      api_key_ref: keychain:minmax
      base_url: https://api.minimaxi.com/anthropic
      models:
        default: MiniMax-M2.7-highspeed

密钥存在 Omnigent secret store（keychain:deepseek / keychain:minmax），不要把明文 key 写进聊天或公开仓库。

4.3 手工改 Provider 的注意点

base_url 必须是该厂商自己的地址，不能误用 api.openai.com。
多数第三方走 Chat Completions （wire_api: chat），不是 OpenAI Responses API。
改完 config.yaml / 密钥后，已跑着的本地 server 可能要重启；omni stop 后再开会话最省事。
Codex 若报 context window 元数据警告，可在 ~/.codex 配 model catalog（本机曾为 MiniMax 加过）。

4.4 与「各 CLI 自己的第三方」的关系

工具	自己的配置目录	与 Omnigent 的关系
Hermes	`~/.hermes/.env`、`config.yaml`	`omni hermes` 启动时用 Hermes 自己的模型/Key
OpenCode	`~/.config/opencode/`	`opencode_model` 可在 Omnigent 里设默认
Grok CLI	`~/.grok/config.toml`	ACP 用的模型/Key 以 Grok 配置为准
Reasonix	`reasonix.toml` / 其 `.env`	ACP 用的模型以 Reasonix 为准
Omnigent Provider	`~/.omnigent/`	主要喂给 Claude / Codex / Pi 等「吃 provider」的 harness

5. 日常 CLI

入口等价：omni ≈ omnigent。

5.1 总览

复制代码

omni --help
omni --version

常用子命令：

命令	作用
`omni setup`	配置 harness / Provider / ACP
`omni config list`	查看默认与凭据
`omni config set KEY=VALUE`	改默认项
`omni run ...`	通用启动会话
`omni polly`	多 agent 编排（Polly）
`omni claude` / `codex` / `pi` / `cursor` / `hermes` / `opencode` / `kimi` ...	直接开对应 TUI
`omni session`	管理会话
`omni stop`	停掉本机 Omnigent 相关进程
`omni update`	升级 CLI

5.2 `omni run`（通用）

复制代码

# 指定 harness
omni run --harness codex
omni run --harness pi -p "审查最近一次提交"

# 指定模型（在 harness 支持时）
omni run --harness codex --model MiniMax-M2.7-highspeed -p "写一个 hello"

# 跑 agent YAML / 目录
omni run path/to/agent.yaml
omni run path/to/agent_dir

# 接本地或远程 server
omni run --server ""                    # 自动起本地持久 server
omni run --server http://127.0.0.1:6767

# 恢复会话
omni run -c                             # 继续最近一次
omni run -r                             # 交互选择
omni run --resume conv_xxx

5.3 直接开各 harness TUI

复制代码

omni claude
omni codex
omni pi
omni hermes
omni opencode
omni cursor
omni kimi

# 带首条消息
omni codex -p "解释当前目录的项目结构"
omni pi --model deepseek-v4-flash

5.4 Polly（多 worker 编排）

复制代码

omni polly
omni polly -p "用多个 worker 审查并修掉 lint"
omni polly --server http://127.0.0.1:6767

Polly 会按 roster 调度已安装且可用的 worker（claude_code / codex / opencode / cursor / hermes / pi / reasonix / grok ...）。

改完 ACP / agents 后，请新开 Polly 会话，旧 bundle 可能仍是旧名单。

5.5 用 ACP harness 单跑（Reasonix / Grok）

配置写在 ~/.omnigent/config.yaml 的 acp.agents 后，harness id 为：

Reasonix → acp:reasonix
Grok → acp:grok

omni run --harness acp:reasonix -p "在当前仓库里找入口文件并说明"
omni run --harness acp:grok -p "用一句话总结 README"

也可在 omni setup 里点对应 ACP 行做管理 / 删除；用 Add custom ACP agent 可再加别的 ACP CLI。

6. Reasonix

6.1 独立使用（不经过 Omni）

复制代码

reasonix                         # 交互 TUI
reasonix --model deepseek/deepseek-v4-flash
reasonix run "实现某某功能"
reasonix review --base main
reasonix setup                   # 写 reasonix.toml / .env
reasonix doctor

ACP（给 IDE / Omnigent 用）：

复制代码

reasonix acp --model deepseek/deepseek-v4-flash
# 等价：reasonix --acp

6.2 挂进 Omnigent（本机已配）

复制代码

# ~/.omnigent/config.yaml
acp:
  agents:
    - name: Reasonix
      command: reasonix acp --model deepseek/deepseek-v4-flash
      model: deepseek/deepseek-v4-flash

要点：

凭据与模型目录在 Reasonix 自己的配置 里，Omnigent 只负责拉起 command。
Polly worker 名：reasonix，harness：acp:reasonix。
omni setup 列表里应看到：Reasonix ✓ ACP · reasonix acp --model ...

6.3 从 Omni / Polly 调用

复制代码

# 单 worker
omni run --harness acp:reasonix -p "EXPLORE：这个仓库用什么包管理器？"

# 编排里让 Polly 派 reasonix（自然语言即可）
omni polly -p "用 reasonix 探索项目结构，再用 codex 实现小改动"

7. Grok（Grok Build CLI）

7.1 独立使用（不经过 Omni）

Grok 没有 Omnigent 一等 harness；本机 CLI：

复制代码

grok                             # 交互 TUI
grok models                      # 看当前可用模型
grok -p --model deepseek-reasoner "Reply with OK"   # 单轮（具体 flag 以 grok --help 为准）

配置目录：~/.grok/config.toml。

本机当前默认是第三方 DeepSeek（不是 xAI 官方额度）：

复制代码

[models]
default = "deepseek-reasoner"

[model.deepseek]
model = "deepseek-v4-flash"
base_url = "https://api.deepseek.com/v1"
# api_key = "..."

[model.deepseek-reasoner]
model = "deepseek-reasoner"
base_url = "https://api.deepseek.com/v1"
# api_key = "..."

ACP：

复制代码

grok agent --model deepseek-reasoner --always-approve stdio

说明：--always-approve 适合被 Omni/Polly 无头调度，避免卡在权限确认。

7.2 挂进 Omnigent（本机已配）

复制代码

# ~/.omnigent/config.yaml
acp:
  agents:
    - name: Grok
      command: grok agent --model deepseek-reasoner --always-approve stdio
      model: deepseek-reasoner

要点：

setup 列表里应看到：Grok ✓ ACP · grok agent ...
Polly worker：grok，harness：acp:grok
不要指望在「Claude / Codex」那种内置行里出现「Grok」------它只能以 ACP 行出现
若改回 xAI：在 ~/.grok 配 xAI 模型与 XAI_API_KEY，并改 ACP 的 --model；需 console 有 credits

7.3 从 Omni / Polly 调用

复制代码

omni run --harness acp:grok -p "REVIEW：只读检查最近 diff 风险点"

omni polly -p "用 grok 做探索，用 reasonix 做实现"

8. 推荐工作流（第三方为主）

复制代码

1. uv tool install 'omnigent[cursor]'
2. 安装需要的 CLI：codex / pi / hermes / opencode / reasonix / grok ...
3. omni setup
   - Claude / Codex → Minmax（或 DeepSeek）
   - Pi → DeepSeek
   - Add custom ACP → Reasonix / Grok（若尚未写入 config）
4. omni config list   # 确认
5. 日常：
   omni codex / omni pi / omni hermes ...
   omni run --harness acp:reasonix ...
   omni run --harness acp:grok ...
   omni polly         # 多 worker

9. 故障速查

现象	处理
setup 看不到 Grok	正常：需 ACP 注册；确认 `acp.agents` 有 Grok，或用 Add custom ACP
ACP 行是红叉 / 起不来	`command -v reasonix` / `command -v grok`；本地先跑一遍 ACP 命令
第三方 401/403	Key、base_url、账号额度；xAI 无 credits 会 403
OpenCode 版本不对	钉 1.17.x
Polly 不派 reasonix/grok	新开 Polly 会话；确认 roster 含对应 worker
改完配置像没生效	`omni stop` 后重开；勿依赖 `/tmp/omnigent-*` 里的旧 session home
重启后配置「消失」	正式配置在 `~/.omnigent/`，一般不会丢；检查是否改错文件或装了另一套 omni

10. 本机速查（当前）

复制代码

omni --version
# omnigent 0.5.1

omni config list
# Claude/Codex → Minmax；Pi → DeepSeek ...

# ACP
grep -A20 '^acp:' ~/.omnigent/config.yaml

# 独立 CLI
reasonix version
grok --version
grok models

ACP 当前条目：

名称	Harness	命令	模型
Reasonix	`acp:reasonix`	`reasonix acp --model deepseek/deepseek-v4-flash`	DeepSeek（Reasonix 侧）
Grok	`acp:grok`	`grok agent --model deepseek-reasoner --always-approve stdio`	DeepSeek（`~/.grok`）

11. 给 Polly 写 Prompt（含 Git / 同一目录）

在网页（如 http://127.0.0.1:6767）或 omni polly -p "..." 里，用自然语言指挥即可，不用写调度代码。Polly 会自己 spawn 子代理。

11.1 写法原则

目标具体：要改什么、成功标准是什么
明确分工：谁实现、谁审查（尽量跨厂商）
划清范围：目录/文件写死，避免并行互相踩
交付物说清：各自开 PR，你来 merge；Polly 不写业务代码、不 merge
说清 Git 策略：用 worktree 并行，还是同一目录串行（见下）

11.2 为什么提示词里要写「独立 git worktree」

独立 git worktree ≠ 再 clone 一份仓库。

还是同一个 Git 仓库 （同一个 .git），再检出一份独立工作目录 + 独立分支，让多个代理同时改代码时互不踩脚。

	普通同一目录	git worktree
仓库	1 个 `.git`	还是这 1 个
工作目录	只有主目录一份	主目录 + `.worktrees/<任务>/`
并行改代码	易互相覆盖、测试乱套	各改各的分支与目录
合并	难拆开	各自开 PR，你再审再合

示例：

复制代码

~/pros/yijing                    ← 主工作区
~/pros/yijing/.worktrees/opt-a   ← 任务 A（分支 polly/opt-a）
~/pros/yijing/.worktrees/opt-b   ← 任务 B（分支 polly/opt-b）

好处（写进 prompt 时可强调）：

多 worker（Claude / Codex / OpenCode / Cursor / Reasonix / Grok）可并行
失败可整棵 worktree 丢掉，不影响主目录
每个任务一条分支、一个 PR，审查边界清晰
仍是同一项目、同一 remote，不是多仓库分叉

Polly 默认 fanout 就会：git worktree add .worktrees/<task_id> -b polly/<task_id>。

11.3 项目已在「同一个 Git」、且坚持同一目录时怎么写

项目本来就在一个 git 里------这和 worktree 不冲突 （worktree 仍挂在这个 git 上）。

若你不想建 worktree 、只想在当前仓库目录 干活，必须在 prompt 里写死串行，禁止并行改同一批文件：

复制代码

仓库：当前目录就是唯一工作区（同一个 git，不要再 clone）。

Git 策略（强制）：
- 先不要创建 git worktree；
- 按顺序串行：一个子代理做完、提交并开 PR 后，再派下一个；
- 全程在当前仓库目录操作；
- 禁止两个实现代理同时改同一批文件；
- 若必须改到重叠文件，后一个先 pull / rebase 前一个分支，或等前一个 PR 合完再开干。

其余流程仍要：跨厂商 cross-review；你（polly）只编排，不写业务代码，不 merge。

对照：

场景	Prompt 里怎么写
要并行、多 worker	「每个任务独立 git worktree + 各自开 PR」
同一目录、一个 git	「不要 worktree；串行；同一仓库目录」
范围	「只动 `app/` / `fletApp/` ...」写清楚

11.4 可直接粘贴：并行 + worktree（推荐）

复制代码

目标：优化本仓库性能（先分析再改）。

仓库说明：这是同一个 git 仓库；请用独立 git worktree 做并行（同仓库、多工作区、多分支），不要重新 clone。

请按 fanout + cross-review 执行：

1) 先调查（pi / reasonix / grok，purpose=investigate）：
   - 找出最热路径 / 明显瓶颈
   - 输出：问题列表 + 预期收益 + 涉及文件

2) 把优化拆成互不重叠的子任务（共享文件不要并行），每个任务：
   - 独立 git worktree（.worktrees/<task_id>）
   - 一个实现子代理（轮流：claude_code / codex / opencode / cursor / reasonix / grok）
   - 自己开 PR
   - 验收：相关测试通过；说明度量或前后对比方式

3) 每个 PR 必须跨厂商 cross-review（审查方 ≠ 实现方）：
   - 审查只报 blocking / non-blocking，不直接改代码

4) 你（polly）不要写业务代码；不要 merge；最后给我：
   - 任务表、各 PR 链接、谁实现/谁审查、blocking 摘要

范围：先从 <目录，例如 app/ 或 fletApp/> 开始。
不要无证据的大重构。某 CLI 不可用则跳过并告诉我。

11.5 可直接粘贴：同一目录串行

复制代码

目标：<一句话目标>。

仓库：当前目录，同一个 git。不要 clone，也不要创建 worktree。

执行方式（强制串行）：
1) 先用 pi 或 reasonix 做 investigate，列出改动点与文件范围。
2) 一次只派一个实现代理（如 codex 或 claude_code），在当前目录改完、测绿、开 PR。
3) 再用另一厂商做 cross-review（只审不改）。
4) 前一个 PR 流程结束后，再开下一个任务。
5) 你（polly）只编排，不写业务代码，不 merge。

范围：<目录>。最后汇总 PR 链接与审查结论。

11.6 更短版

并行（worktree）：

复制代码

优化本仓库最明显的问题。拆成可并行任务，每个独立 git worktree，
分别派给 claude_code / codex / opencode / cursor / reasonix / grok 实现并各自开 PR；
每个 PR 用另一厂商 cross-review。你只编排，不写代码，不 merge；最后汇总 PR 和审查结论。

串行（同一目录）：

复制代码

在当前同一 git 目录串行完成：先调查，再派一个代理实现并开 PR，再跨厂商审查；
不要 worktree、不要并行改同一批文件。你只编排，不 merge；最后给 PR 链接。

11.7 子代理名字对照（写进 prompt）

你说的	提示词里写
Claude	`claude_code`
Codex	`codex`
OpenCode	`opencode`
Cursor CLI	`cursor`
Hermes	`hermes`
Pi	`pi`
Reasonix	`reasonix`
Grok	`grok`

12. 安全提示

API Key 只放 ~/.omnigent/secrets.json / 各工具自己的 .env，权限建议 600。
勿把 Key 贴进聊天、截图或公开 git。
若 Key 曾泄露，到对应控制台轮换。

文档根据本机 Omnigent 0.5.1 与当前 ~/.omnigent/ Reasonix / Grok 配置整理。升级 CLI 后若菜单文案有差异，以 omni --help与 omni setup为准。

Omnigent（omni）使用说明

1. 是什么

2. 安装

2.1 推荐：uv tool

2.2 升级 / 检查更新

2.3 依赖的外部 CLI（按需）

3. 首次配置与持久化

3.1 交互配置（推荐）

3.2 配置落盘位置（重启电脑不会丢）

3.3 查看当前生效配置

4. 第三方 Provider（核心）

4.1 内置可一键配置的 key 类厂商

4.2 本机当前第三方配置（摘录）

4.3 手工改 Provider 的注意点

4.4 与「各 CLI 自己的第三方」的关系

5. 日常 CLI

5.1 总览

5.2 omni run（通用）

5.3 直接开各 harness TUI

5.4 Polly（多 worker 编排）

5.5 用 ACP harness 单跑（Reasonix / Grok）

6. Reasonix

6.1 独立使用（不经过 Omni）

6.2 挂进 Omnigent（本机已配）

6.3 从 Omni / Polly 调用

7. Grok（Grok Build CLI）

7.1 独立使用（不经过 Omni）

7.2 挂进 Omnigent（本机已配）

7.3 从 Omni / Polly 调用

8. 推荐工作流（第三方为主）

9. 故障速查

10. 本机速查（当前）

11. 给 Polly 写 Prompt（含 Git / 同一目录）

11.1 写法原则

11.2 为什么提示词里要写「独立 git worktree」

11.3 项目已在「同一个 Git」、且坚持同一目录时怎么写

11.4 可直接粘贴：并行 + worktree（推荐）

11.5 可直接粘贴：同一目录串行

11.6 更短版

11.7 子代理名字对照（写进 prompt）

12. 安全提示

5.2 `omni run`（通用）