pi-custom-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pi custom / variant model

Pi 自定义/变体模型

When to use

使用场景

Pi's saved default only loads if the exact

provider/id

exists in its model registry. Pi ships a static bundled list per provider — so OpenRouter routing-shortcut variants (

:nitro

= sort by throughput,

:floor

= cheapest,

:exacto

= quality tool-use) and any brand-new slug are NOT in it. When the default doesn't resolve, Pi silently falls through to its built-in per-provider default (for openrouter that's

moonshotai/kimi-k2.6

) — looking like Pi "reset" your model. Fix = register the slug as a custom model so

find(provider, id)

matches.

只有当精确的

provider/id

存在于模型注册表中时，Pi保存的默认模型才会加载。Pi为每个提供商提供静态内置模型列表——因此OpenRouter的路由快捷变体（

:nitro

=按吞吐量排序，

:floor

=最便宜，

:exacto

=高质量工具调用）以及任何全新的标识都不在该列表中。当默认模型无法匹配时，Pi会自动回退到其内置的提供商默认模型（对于OpenRouter来说是

moonshotai/kimi-k2.6

）——看起来就像Pi“重置”了你的模型。解决方法是将该标识注册为自定义模型，使

find(provider, id)

能够匹配到。

Files (global)

全局文件

~/.pi/agent/settings.json

—

defaultProvider

defaultModel

defaultThinkingLevel

```
~/.pi/agent/models.json
```
— custom models, keyed by provider
```
~/.pi/agent/auth.json
```
— provider credentials (check the provider key exists)

~/.pi/agent/settings.json

— 存储

defaultProvider

、

defaultModel

、

defaultThinkingLevel

```
~/.pi/agent/models.json
```
— 存储自定义模型，按提供商分类
```
~/.pi/agent/auth.json
```
— 存储提供商凭证（需确认提供商密钥存在）

Steps

操作步骤

Confirm the slug is real before adding it (e.g. check the OpenRouter model/variant exists). A typo'd id also silently falls back.
Confirm auth. The provider must have a key in
```
auth.json
```
(or an env var like
```
OPENROUTER_API_KEY
```
). No auth → the model is registered but unavailable → still falls back.

Add the model to
models.json
under

providers.<provider>.models

. For a built-in provider (openrouter, anthropic, etc.) you only supply metadata —

api

baseUrl

, and auth are inherited from the bundled defaults. Example:

json

{
  "providers": {
    "openrouter": {
      "models": [
        {
          "id": "z-ai/glm-5.2:nitro",
          "name": "Z.ai: GLM 5.2 (nitro)",
          "reasoning": true,
          "thinkingLevelMap": { "xhigh": "xhigh" },
          "input": ["text"],
          "cost": { "input": 0.95, "output": 3, "cacheRead": 0.18, "cacheWrite": 0 },
          "contextWindow": 1048576,
          "maxTokens": 32768,
          "compat": { "supportsDeveloperRole": false, "thinkingFormat": "openrouter" }
        }
      ]
    }
  }
}

Copy

cost

contextWindow

compat

from the base model (the variant shares them) — find the bundled entry in

<pi-pkg>/node_modules/@earendil-works/pi-ai/dist/providers/<provider>.models.js

. Don't hardcode generic 128k/16k if the real model is bigger.

Set the default in

settings.json

defaultProvider

defaultModel

= the exact id. Leave

defaultThinkingLevel

as the user has it.

Verify:

pi --list-models | grep <id>

shows it, and JSON parses. Optionally smoke-test:

pi --provider <p> --model "<id>" "which model are you?"

确认标识有效：添加前先确认模型标识真实存在（例如检查OpenRouter的模型/变体是否存在）。输入错误的标识也会导致自动回退。
确认权限：提供商必须在
```
auth.json
```
中有密钥（或环境变量如
```
OPENROUTER_API_KEY
```
）。无权限的话，模型虽已注册但无法使用，仍会回退到默认模型。

将模型添加到
models.json
：在

providers.<provider>.models

下添加模型。对于内置提供商（如openrouter、anthropic等），只需提供元数据——

api

、

baseUrl

和权限会继承自内置默认配置。示例：

json

{
  "providers": {
    "openrouter": {
      "models": [
        {
          "id": "z-ai/glm-5.2:nitro",
          "name": "Z.ai: GLM 5.2 (nitro)",
          "reasoning": true,
          "thinkingLevelMap": { "xhigh": "xhigh" },
          "input": ["text"],
          "cost": { "input": 0.95, "output": 3, "cacheRead": 0.18, "cacheWrite": 0 },
          "contextWindow": 1048576,
          "maxTokens": 32768,
          "compat": { "supportsDeveloperRole": false, "thinkingFormat": "openrouter" }
        }
      ]
    }
  }
}

从基础模型中复制

cost

contextWindow

compat

字段（变体模型共享这些配置）——可在

<pi-pkg>/node_modules/@earendil-works/pi-ai/dist/providers/<provider>.models.js

中找到内置配置条目。如果真实模型的上下文窗口更大，不要硬编码通用的128k/16k值。

在
settings.json
中设置默认模型：将
```
defaultProvider
```
和
```
defaultModel
```
设置为精确的模型标识。保留用户原有的
```
defaultThinkingLevel
```
设置。
验证：执行
```
pi --list-models | grep <id>
```
命令可查看模型是否已注册，同时确保JSON格式正确。可选冒烟测试：执行
```
pi --provider <p> --model "<id>" "which model are you?"
```
。

Quirks

注意事项

Exact match only.
```
find()
```
is exact
```
provider
```
+
```
id
```
— no fuzzy/colon-stripping for the saved default path. The slug in
```
settings.json
```
and
```
models.json
```
must be byte-identical.
Silent fallback. Pi prints no error when the default doesn't resolve; it just shows a different model in the footer. That's the tell.
Don't edit
settings.json
alone. Setting
```
defaultModel
```
to an unregistered slug does nothing —
```
models.json
```
is the actual fix.
enabledModels
(optional) pins the model picker so Ctrl+P cycling can't drift back:
```
"enabledModels": ["<provider>/<id>:<thinking>"]
```
.
Project override. A repo's
```
.pi/settings.json
```
overrides global. If a default reverts only inside one project, check that file first.
Restart Pi fully — the registry loads at startup.

仅精确匹配：
```
find()
```
方法会精确匹配
```
provider
```
+
```
id
```
——对于保存的默认模型路径，不支持模糊匹配或去除冒号。
```
settings.json
```
和
```
models.json
```
中的标识必须完全一致。
自动回退无提示：当默认模型无法匹配时，Pi不会打印错误信息，只会在底部显示另一个模型。这是判断问题的关键特征。
不要仅修改
settings.json
：将
```
defaultModel
```
设置为未注册的标识无效——真正的解决方法是修改
```
models.json
```
。
enabledModels
（可选）：固定模型选择器，避免Ctrl+P切换时回退到其他模型，配置示例：
```
"enabledModels": ["<provider>/<id>:<thinking>"]
```
。
项目级覆盖：仓库中的
```
.pi/settings.json
```
会覆盖全局配置。如果仅在某个项目中默认模型自动恢复，先检查该文件。
完全重启Pi——模型注册表在启动时加载。