omp (Oh My Pi) + JoinGonka Gateway：带模型角色的代理

第 1 步：安装 omp。来自项目 README的官方方式：

# macOS and Linux
curl -fsSL https://omp.sh/install | sh

# Homebrew
brew install can1357/tap/omp

# via Bun (requires Bun 1.3.14 or newer)
bun install -g @oh-my-pi/pi-coding-agent

# Windows (PowerShell)
irm https://omp.sh/install.ps1 | iex

第 2 步：获取密钥。在 gate.joingonka.ai/register 注册，验证邮箱地址，然后在「API 密钥」页面创建一个以 jg- 为前缀的密钥。一个密钥和一个余额即可用于网络中的所有模型。

第 3 步：运行安装程序。

npx @joingonka/setup --tool omp

安装程序会询问密钥——密钥不会通过命令行参数传递，以免留在 shell 历史记录中——然后它会做四件事：

• 将提供商 joingonka 写入 ~/.omp/agent/models.yml：网关地址、openai-completions 协议、以字面量形式写入的密钥，以及网络的三个模型及其真实的上下文窗口和响应上限；该文件将获得 600 权限；
• 将默认模型——~/.omp/agent/config.yml 中的 modelRoles.default——设置为 DeepSeek V4 Flash，但仅当该角色为空或指向已从网络中下线的模型时才会这样做：它不会覆盖他人的选择，而是提示如何切换；
• 写入前会备份原文件，其余提供商、角色和注释保持原样；
• 最后向网关发送一个实时请求，并明确告知密钥、地址和模型是否被接受。

如需指定其他默认模型，可使用 --model 标志，支持简写 deepseek、glm 或 minimax——显式指定的模型总是会被写入。对于 dotfiles 和服务器，还提供了无交互模式，此模式下密钥从环境变量读取：

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool omp --model glm --non-interactive

安装程序会自动识别非标准的配置位置：命名配置文件（OMP_PROFILE）和迁移后的代理目录（PI_CODING_AGENT_DIR）。它会把遗留的 models.json 迁移到 models.yml，方式与 omp 自身完全相同——原有提供商不会丢失。而如果旁边存在旧的 settings.json 却没有 config.yml，安装程序不会创建 config.yml，以免 omp 跳过其自身的设置迁移：它会要求先运行一次 omp，然后重新执行该命令。

安装程序所做的一切都可以手动完成。只有两个文件，各司其职：models.yml 描述提供商和模型，config.yml 保存设置——包括哪个模型担任哪个角色。

# ~/.omp/agent/models.yml
providers:
  joingonka:
    baseUrl: https://gate.joingonka.ai/v1
    api: openai-completions
    apiKey: jg-your-key
    models:
      - id: deepseek-ai/DeepSeek-V4-Flash-0731
        name: DeepSeek V4 Flash (Gonka)
        input: [text]
        contextWindow: 380000
        maxTokens: 32768
        reasoning: true
      - id: zai-org/GLM-5.3-Flash
        name: GLM-5.3 Flash (Gonka)
        input: [text]
        contextWindow: 390000
        maxTokens: 8192
        reasoning: true
      - id: MiniMaxAI/MiniMax-M2.7
        name: MiniMax M2.7 (Gonka)
        input: [text]
        contextWindow: 200000
        maxTokens: 8192

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731

直接把密钥写成字面量是最省事的做法：omp 在任何环境下都能启动，你只需用 chmod 600 ~/.omp/agent/models.yml 把文件权限收紧即可。若想把密钥放在文件之外，就在 apiKey 中填入环境变量名，例如 JOINGONKA_API_KEY，并在启动 omp 的 shell 中导出它：项目文档中描述的正是这样的密钥解析顺序。

可选字段 cost（每百万 token 的价格）仅用于在 omp 界面中估算会话成本。安装程序会写入安装时网关的实时价格；在手动配置中该字段可以省略——这个估算与你的账单无关，实际用量以账户后台显示为准。

模型选择器写作 provider/model-id。提供商名称以第一个斜杠为界切分，因此自带斜杠的网络标识符按原样书写：joingonka/deepseek-ai/DeepSeek-V4-Flash-0731。除了修改 config.yml，你也可以在界面中指定角色——在会话内使用 /model 命令，或在 omp setup 向导中设置。

在 omp 中，模型不是为所有任务选择一个，而是按角色选择——这就是主要的调整杠杆。内置的对话角色包括：default, smol, slow, plan, commit, task, tiny, memory, advisor 和 vision。无需全部指定：未定义的 smol 和 slow 默认使用 default 角色的模型，没有 task 角色的子代理运行在当前会话模型上，commit 和 tiny 则紧随 smol 之后。单行配置 default 即可完全正常工作。

在网络模型之间分配角色并不是为了省钱——DeepSeek V4 Flash、GLM-5.3 Flash 和 MiniMax M2.7 的价格是一样的——而是为了控制行为和容量：推理模型规划能力更强，长响应模型写作更好，而后台小任务没必要与主任务排在同一个队列中。

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
  slow: joingonka/zai-org/GLM-5.3-Flash
  plan: joingonka/zai-org/GLM-5.3-Flash
  tiny: joingonka/MiniMaxAI/MiniMax-M2.7

retry:
  fallbackChains:
    default:
      - joingonka/zai-org/GLM-5.3-Flash

retry.fallbackChains 模块是高峰期的保险：当主模型持续返回 429 时，omp 会将剩余的任务交给链中的下一个条目，稍作停顿后再切回主模型。链的键可以是角色、具体模型或整个提供商（joingonka/*）。

对于单次运行，可以通过标志重写角色：omp --model slow 使用 slow 角色的模型启动会话，而 --smol, --slow 和 --plan 则会替换该角色本身的模型。在会话内部，Ctrl+P 可以滚动查看角色模型，/model 可以打开选择器；在“Roles”标签页中，可以指定角色及其备用模型。

你可以在角色值后附加推理级别——:low, :medium, :high。这是 omp 的语法，具体模型如何理解该级别取决于模型本身：例如，GLM-5.3 Flash 将其用作二进制开关——详情请参阅 模型概览。另一个有用的细节是：可以通过 <repo>/.omp/config.yml 文件并在其中包含相同的 modelRoles 块，为单个仓库重写角色。提供商和密钥仍保留在主目录中，因此密钥不会泄露到仓库中。

首先确认 omp 能看到该服务商：

omp models joingonka

返回的是一张三行表格，列出 models.yml 中的上下文窗口和输出上限，数值四舍五入到千位（输出有删减：omp 还有 thinking 和 images 两列）：

joingonka (3)
model                                context  max-out
deepseek-ai/DeepSeek-V4-Flash-0731      380K      33K
MiniMaxAI/MiniMax-M2.7                  200K     8.2K
zai-org/GLM-5.3-Flash                   390K     8.2K

接着做一次无界面的单次运行。往一个空目录里放一个带有明显错误的文件，然后让它找出来：

omp -p "Read calc.py and tell me in one sentence whether it has a bug."

智能体应当自行调用读取工具并给出实质回答——指出错误所在的那个表达式。在我们 2026 年 9 月 21 日的运行中，这一循环——请求、调用工具、返回结果、作答——被 DeepSeek V4 Flash 和 GLM-5.3 Flash 完整通过；MiniMax M2.7 的情况见下方表格最后一行。

第三项检查从网关侧进行：在控制台的「使用情况」里，该请求会出现在「按模型」细分中，而「按密钥」区块会更新最后一次请求的时间。如果那里是空的，说明 omp 走的是另一个服务商：用 omp config get modelRoles 看看各角色上挂的是什么。

如果出了问题，诊断信息通常可以直接从报错里读出来：

智能体工具消耗 token 的方式与聊天不同：omp 会在你的每一句话中加入系统提示词和工具描述，而且一个任务通常需要多个步骤。在我们的一次运行中，即使只启用了文件读取工具，每一步都会带来大约 3500 个输入 token；如果启用全套工具，消耗会更多。因此，token 价格在这里至关重要。

通过 JoinGonka Gateway，输入端 token 价格为 $0.0069/百万，输出端为 $0.021/百万 — 网络中所有模型的价格相同，并从实时源自动更新到此页面。

右侧估算基于 2026 年 9 月的价格。作为对比，以下是在 omp 中为模型付费的方式：

omp 状态栏显示会话成本估算。它是根据 models.yml 中的 cost 字段计算的：安装程序在安装时写入网关价格，由于网络中的美元价格会随 GNK 汇率波动，因此估算仅供参考。精确消耗和余额请查看仪表板中的“使用情况”和“账单”部分。关于为什么默认选择 DeepSeek V4 Flash，详细分析见模型综述。

确认模式。默认情况下 omp 运行在 yolo 模式下：读取、写入和执行命令都由它自己批准。在自己的项目上这很方便，但在别人的代码上，这正是收紧模式或转入容器的理由：

omp config set tools.approvalMode write

在 write 模式下，智能体只对执行命令请求许可；在 always-ask 模式下，写入也需要请求许可。单次运行可通过 --approval-mode 标志设置同样的行为。这是 omp 自身的属性，与模型提供商无关。

Pi 和 omp 是配置各异的近亲。一个工具的设置不会传递给另一个：它们的目录、格式和字段名各不相同。

多套环境。命名配置文件（omp --profile work 或 OMP_PROFILE 变量）会把所有设置迁移到 ~/.omp/profiles/<name>/agent——便于把工作密钥和个人密钥分开。当前智能体目录由 omp config path 打印。

如果需要在编辑器中运行智能体。omp 可以通过 ACP 协议在 Zed 内运行——同一个智能体、同一套设置，无需再次配置提供商和角色。