omp如何自定义模型

oh-my-pi 自定义模型教程

本教程涵盖 Windows 和 Linux 下通过 models.yml 为 oh-my-pi (omp) 添加自定义模型提供商的完整方法。

1. 配置文件位置

oh-my-pi 从以下路径加载自定义模型配置（优先级从高到低）：

操作系统	路径
Linux	`~/.omp/agent/models.yml`
Linux（旧版）	`~/.omp/agent/models.yaml`
Windows	`%USERPROFILE%\.omp\agent\models.yml`
Windows（旧版）	`%USERPROFILE%\.omp\agent\models.yaml`

注意：如果两个都不存在但存在 models.json，omp 会自动迁移到 models.yml。建议直接用 models.yml。

如果 .omp/agent/ 目录不存在，手动创建即可：

Linux / macOS：

mkdir -p ~/.omp/agent

Windows (PowerShell)：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.omp\agent"

2. 基础结构：添加一个自定义 Provider

models.yml 最简结构如下：

providers:
  <provider-id>:          # 自定义 ID，全局唯一
    baseUrl: <API 地址>
    apiKey: <密钥或环境变量名>
    api: <协议类型>
    authHeader: true      # 是否注入 Authorization: Bearer 头
    models:
      - id: <模型 ID>
        name: <显示名称>
        contextWindow: <上下文窗口>
        maxTokens: <最大输出 token>
        input: [text]     # 输入类型：text / image

字段说明

字段	必填	说明
`provider-id`	是	自定义标识符，如 `my-gateway`。在 `/model` 中显示为 provider 名
`baseUrl`	是	API 基础地址。OpenAI 协议自动追加 `/v1/chat/completions` 或 `/v1/responses`
`apiKey`	条件必填	环境变量名或明文 key。`auth: none` 时可省略
`api`	是	API 协议。见下方协议类型
`authHeader`	否	`true` 时注入 `Authorization: Bearer <key>` 请求头。OpenAI 兼容代理通常需要
`auth`	否	`none` 表示免认证（本地模型），默认 `apiKey`
`disableStrictTools`	否	`true` 禁用 Anthropic strict 工具 schema。三方代理通常需要
`models[].id`	是	模型标识符。选择时用 `provider-id/model-id`
`models[].name`	否	显示名，不填用 `id`
`models[].contextWindow`	是	上下文窗口大小（token）
`models[].maxTokens`	是	单次最大输出 token
`models[].reasoning`	否	`true` 表示支持推理/思考模式
`models[].input`	是	`[text]` 或 `[text, image]`

支持的 API 协议类型

`api` 值	实际端点	适用场景
`openai-completions`	`/v1/chat/completions`	标准 OpenAI Chat API 代理
`openai-responses`	`/v1/responses`	OpenAI Responses API 代理
`anthropic-messages`	`/v1/messages`	Anthropic Messages API 代理
`google-generative-ai`	Gemini API	Google Gemini API
`google-vertex`	Vertex AI API	Google Cloud Vertex AI

3. 常见场景

3.1 OpenAI 兼容代理（Chat Completions）

适用：大多数三方 API 代理，端点形如 POST /v1/chat/completions。

providers:
  my-proxy:
    baseUrl: https://api.example.com/v1
    apiKey: MY_PROXY_API_KEY        # 环境变量名
    api: openai-completions
    authHeader: true
    models:
      - id: gpt-4o
        name: GPT-4o (Proxy)
        contextWindow: 128000
        maxTokens: 16384
        input: [text]

3.2 OpenAI 兼容代理（Responses API）

适用：端点走 /v1/responses 的代理（如某些 Codex 兼容网关）。

providers:
  rawchat:
    baseUrl: https://rawchat.cn/codex/v1
    apiKey: RAWCHAT_API_KEY
    api: openai-responses
    authHeader: true
    models:
      - id: gpt-5.6-sol
        name: GPT-5.6 Sol
        contextWindow: 200000
        maxTokens: 16384
        input: [text]
        reasoning: true

Responses API 特殊性：支持 previous_response_id 链式多轮续接；部分代理不兼容时可忽略，omp 自动降级。

3.3 Anthropic 兼容代理

适用：端点形如 POST /v1/messages 的 Anthropic 协议代理。

providers:
  claude-proxy:
    baseUrl: https://proxy.example.com
    apiKey: CLAUDE_PROXY_API_KEY
    api: anthropic-messages
    authHeader: true
    disableStrictTools: true         # 大多数三方代理不支持 strict 字段
    models:
      - id: claude-sonnet-4-20250514
        name: Claude Sonnet 4 (Proxy)
        contextWindow: 200000
        maxTokens: 16384
        input: [text, image]
        reasoning: true

3.4 本地模型（Ollama / llama.cpp / LM Studio / vLLM）

方式 A：自动发现（推荐）

omp 内置了三个本地引擎的自动发现，只要引擎在运行就能自动拉取模型列表，无需手写 models.yml：

引擎	默认地址	环境变量覆盖
Ollama	`http://127.0.0.1:11434`	`OLLAMA_BASE_URL` 或 `OLLAMA_HOST`
llama.cpp	`http://127.0.0.1:8080`	`LLAMA_CPP_BASE_URL`
LM Studio	`http://127.0.0.1:1234/v1`	`LM_STUDIO_BASE_URL`

启动引擎后重启 omp，/model 即可看到发现的本地模型。

方式 B：手写配置

如果自动发现不满足需求（比如需要自定义 contextWindow 或使用 vLLM 等非内置引擎）：

Ollama 自定义：

providers:
  ollama:
    baseUrl: http://127.0.0.1:11434
    auth: none
    api: openai-responses
    discovery:
      type: ollama

vLLM：

providers:
  vllm:
    baseUrl: http://127.0.0.1:8000/v1
    auth: none
    api: openai-completions
    discovery:
      type: openai-models-list

手写本地模型（不依赖发现）：

providers:
  local:
    baseUrl: http://127.0.0.1:1234/v1
    auth: none
    api: openai-completions
    models:
      - id: qwen-coder-32b
        name: Qwen 2.5 Coder 32B
        contextWindow: 32768
        maxTokens: 8192
        input: [text]

3.5 覆盖内置 Provider（改路由/改名/改参数）

不需要创建新 provider，直接覆盖已有 provider 的设置：

providers:
  openrouter:
    baseUrl: https://my-proxy.example.com/v1   # 换代理地址
    headers:
      X-Team: platform                         # 加自定义请求头
    modelOverrides:
      anthropic/claude-sonnet-4:
        name: Sonnet 4 (Corp)                  # 改显示名
        compat:
          openRouterRouting:
            only: [anthropic]                  # 强制走 anthropic 路由

modelOverrides 可覆盖的字段：name、reasoning、thinking、input、supportsTools、cost、premiumMultiplier、contextWindow、maxTokens、omitMaxOutputTokens、headers、compat、contextPromotionTarget。

4. API Key 安全最佳实践

⚠️ 绝对不要把 API key 明文写在 models.yml 中并提交到 Git！

推荐方式：环境变量

Linux / macOS：

# 写到 ~/.omp/agent/.env（omp 自动加载）
echo 'RAWCHAT_API_KEY=sk-xxxxxxxxxxxxxxxx' >> ~/.omp/agent/.env

Windows (PowerShell)：

Add-Content -Path "$env:USERPROFILE\.omp\agent\.env" -Value "RAWCHAT_API_KEY=sk-xxxxxxxxxxxxxxxx"

然后 models.yml 中用环境变量名：

apiKey: RAWCHAT_API_KEY    # omp 先查环境变量，找不到才当明文

.env 文件加载优先级

omp 按以下顺序加载 .env（先匹配到的生效）：

优先级	路径	说明
1 (最高)	进程已有环境变量	shell 里 `export` 过的
2	`<项目目录>/.env`	项目级，仓库隔离
3	`~/.omp/agent/.env`	omp 用户级
4	`~/.omp/.env`	omp 全局
5 (最低)	`~/.env`	用户全局

动态密钥（从命令行获取）

apiKey 以 ! 开头时，omp 执行后面的命令并用 stdout 作为 key（10s 超时）：

apiKey: "!op read op://dev/openai/api-key"     # 1Password CLI
apiKey: "!bw get password omp-key"              # Bitwarden CLI

5. 模型角色绑定（config.yml）

在 ~/.omp/agent/config.yml（Linux）或 %USERPROFILE%\.omp\agent\config.yml（Windows）中为快捷角色绑定模型：

modelRoles:
  smol: rawchat/gpt-5.6-sol      # @smol 快速任务
  slow: anthropic/claude-opus     # @slow 复杂任务
  vision: openai/gpt-5.2         # 视觉任务
  default: rawchat/gpt-5.6-sol   # 默认模型

角色别名：

别名	含义
`@smol`	快速/轻量任务
`@slow`	复杂/推理任务
`@vision`	图片理解
`@plan`	架构规划
`@task`	子 agent
`@tiny`	极轻量后台任务（标题生成等）

也可以通过 TUI 中的 /model 命令交互式设置，或用 /settings 调整 modelRoles。

6. 验证与调试

检查模型是否加载

# 列出所有已加载模型（按 provider 分组）
omp models

# 搜索特定模型
omp models find gpt-5.6

# 查看归一化视图
omp models canonical

验证 YAML 语法

# Python 验证（Linux）
python3 -c "import yaml; yaml.safe_load(open('$HOME/.omp/agent/models.yml'))" && echo "OK"

# Windows PowerShell
python -c "import yaml; yaml.safe_load(open('$env:USERPROFILE/.omp/agent/models.yml'.replace('\', '/')))" ; Write-Host "OK"

查看运行日志

# 启动 omp 时开启调试输出
omp --debug

7. 常见问题排查

`/model` 看不到自定义模型

确认文件路径正确：

# Linux
ls -la ~/.omp/agent/models.yml
# Windows PowerShell
Get-Item "$env:USERPROFILE\.omp\agent\models.yml"

检查 YAML 语法：缩进必须用空格（不能 tab），层级要对齐。
检查必填字段：每个自定义 provider 必须有 baseUrl、api，每个 model 必须有 id、contextWindow、maxTokens。
查看错误信息：omp models find <关键词> 会显示 Schema 错误。
重启 omp：models.yml 只在启动时加载，修改后需重启。

模型加载了但无法使用

API Key 未解析：确认环境变量名正确，或 .env 文件路径正确。
authHeader 未设置：大多数代理需要 authHeader: true。

网络不通：用 curl 测试端点：

curl -H "Authorization: Bearer $RAWCHAT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}]}' \
     https://rawchat.cn/codex/v1/chat/completions

连接成功但返回错误

协议不匹配：确认代理实际端点。openai-completions 走 /v1/chat/completions，openai-responses 走 /v1/responses。
baseUrl 多/少 /v1：有的代理要求 https://api.example.com/v1，有的要求 https://api.example.com（自己追加 /v1）。两种都试试。
Anthropic 代理 strict 报错：加 disableStrictTools: true。

本地引擎（Ollama 等）发现不到模型

确认引擎正在运行：

curl http://127.0.0.1:11434/api/tags    # Ollama
curl http://127.0.0.1:8080/v1/models    # llama.cpp

如果配置了自定义的 ollama/llama.cpp/lm-studio provider，它覆盖了内置自动发现。要恢复自动发现就删掉自定义条目，或确保自定义条目包含 discovery 配置。

完整示例汇总

示例 1：OpenAI Chat Completions 代理

providers:
  openai-proxy:
    baseUrl: https://api.example.com/v1
    apiKey: OPENAI_PROXY_KEY
    api: openai-completions
    authHeader: true
    models:
      - id: gpt-4o
        name: GPT-4o (Proxy)
        contextWindow: 128000
        maxTokens: 16384
        input: [text]

示例 2：OpenAI Responses API 代理

providers:
  codex-gateway:
    baseUrl: https://gateway.example.com/v1
    apiKey: GATEWAY_KEY
    api: openai-responses
    authHeader: true
    models:
      - id: gpt-5.6-codex
        name: GPT-5.6 Codex
        contextWindow: 200000
        maxTokens: 32768
        input: [text]
        reasoning: true

示例 3：本地 Ollama

providers:
  ollama:
    baseUrl: http://127.0.0.1:11434
    auth: none
    api: openai-responses
    discovery:
      type: ollama

示例 4：Anthropic 三方代理

providers:
  anthropic-proxy:
    baseUrl: https://proxy.example.com
    apiKey: ANTHROPIC_PROXY_KEY
    api: anthropic-messages
    authHeader: true
    disableStrictTools: true
    models:
      - id: claude-sonnet-4-20250514
        name: Claude Sonnet 4
        contextWindow: 200000
        maxTokens: 16384
        input: [text, image]
        reasoning: true

示例 5：覆盖现有 Provider 部分配置

providers:
  deepseek:
    baseUrl: https://my-deepseek-proxy.com/v1
    apiKey: DEEPSEEK_KEY
    modelOverrides:
      deepseek-chat:
        name: DeepSeek V3 (Custom)
        compat:
          supportsForcedToolChoice: false

可用配置

providers:
  rawchat:
    baseUrl: https://rawchat.cn/codex/v1
    apiKey: xx
    api: openai-responses
    authHeader: true
    models:
      - id: gpt-5.6-sol
        name: GPT-5.6 Sol
        contextWindow: 200000
        maxTokens: 16384
        input: [text]
        reasoning: true

posted @ 2026-07-27 14:06 小满三岁啦阅读(491) 评论(0) 收藏举报

刷新页面返回顶部

小满三岁啦