将 Pi 与您本地的模型搭配使用

Pi 是 earendil-works 开发的一款开源且支持 BYOK（“自带 API 密钥”）的终端编码代理。它遵循 OpenAI 的聊天补全协议，并从 JSON 配置文件中读取可用的提供商信息。因此您可以将 Tokios 设为自定义提供商，将 baseUrl 指向 https://api.tokios.com/v1，进而调用连接器后端的任意模型，而无需对外暴露该模型的端口。

前置条件

已启动的 Tokios 连接器以及与之配套的本地模型——详情参见连接器安装
已注册的部署实例——详情参见模型注册
有效的 Tokios API 密钥（sk-tok-…）——详情参见 API 密钥管理
已安装 Pi——npm install -g @earendil-works/pi-coding-agent

确定您的部署实例名称

Pi sends the deployment name — the public name you registered in the console — not the upstream model id your local backend uses. The 2 are often different strings, and confusing them is the most common cause of a 404. 列出您的 API 密钥可访问的所有部署实例：

curl https://api.tokios.com/v1/models \
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

curl.exe https://api.tokios.com/v1/models `
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

响应内容中的所有 id 均为可在 models.json 中使用的有效值。

即便您的模型本身已能输出 Playground 格式内容，也请务必执行此操作。由于 Playground 依赖您当前登录的浏览器会话进行身份验证，因此该处的测试成功并不能证明您的 sk-tok-… 令牌具备合法权限且适用于当前部署环境。而 GET /v1/models 才是真正调用该令牌的首次操作。

Pi 存储配置信息的位置

Pi reads 2 files from a dot-prefixed .pi directory in your home folder:

文件	用途说明
`.pi/agent/models.json`	各类服务提供商及其所提供的上游模型 ID
`.pi/agent/settings.json`	预设的默认服务提供商与模型

~/.pi/agent/models.json

C:\Users\<you>\.pi\agent\models.json

若相关目录或文件尚未存在，请手动创建。

该文件夹名称即为 .pi，且必须以点号开头。若您在 pi/agent/models.json 路径下手动创建文件，Pi 将无法识别——此时程序会按常规流程启动，只是您的服务提供商信息不会出现在 /model 列表中。

自定义服务提供商的配置方法

请将以下内容粘贴至 models.json 文件中，并替换其中的 2 占位符数值。此内容为一个完整文件而非片段。由于 Pi 的配置架构可能随版本更新而变动，请务必对照您当前安装的版本确认各键名的正确性（参见 pi.dev/docs）。

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        {
          "id": "gemma-tunnel",
          "input": ["text"]
        }
      ]
    }
  }
}

一个提供商配置块即可服务于您账户下的所有部署。针对每个部署，请在 models 数组中添加一条记录。

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        { "id": "gemma-tunnel", "input": ["text"] },
        { "id": "qwen3-coder-tunnel", "input": ["text"] }
      ]
    }
  }
}

将 gemma-tunnel 替换为来自 GET /v1/models 的部署名称——该名称并非后端服务（Ollama、llama.cpp、vLLM 或 LM Studio）所使用的具体上游模型 ID，亦非连接器配置中的 Routes[].Model 值。随后将 sk-tok-YOUR_KEY 替换为您自己的 API 密钥，切记切勿将含有真实密钥的 models.json 内容提交至版本控制系统。

baseUrl 的值必须包含 /v1，且末尾不可带有斜杠。Pi 的 openai-completions 提供商正是基于该 URL 构建请求路径，若使用 https://api.tokios.com 则无法正确访问 Tokios 的 API 接口，而 https://api.tokios.com/v1/ 则会导致路径中出现重复的斜杠分隔符。

设置上下文窗口大小（可选）

Pi 会根据模型上下文窗口的大小来调整提示词长度。Ollama、llama.cpp、LM Studio 以及 vLLM 所呈现的上下文长度均为模型实际加载后的数值，而非理论上的最大值，因此请务必将真实数值告知 Pi：

{ "id": "gemma-tunnel", "input": ["text"], "contextWindow": 32768 }

若设置值过大，Pi 生成的提示词长度可能超出本地服务器的承载极限，此时错误信息虽由 Tokios 返回，但其根源实属本地端问题。篇幅较短的提示词往往不会暴露此类不匹配现象，直至 Pi 开始发送完整文件时才会显现。请务必核对您所用版本对应的具体参数名称。

设为默认配置（可选）

若希望每次启动 Pi 时自动连接至您的 Tokios 部署而无需手动选择，可在 ~/.pi/agent/settings.json 中设定默认配置。

~/.pi/agent/settings.json

{
  "defaultProvider": "tokios",
  "defaultModel": "gemma-tunnel"
}

若未执行上述操作，则需在 Pi 的 TUI 界面中通过 /model 命令手动指定提供商与模型。

需要调用 Anthropic 接口吗？（可选）

Pi also speaks the Anthropic messages protocol. To route through Tokios’s Anthropic surface instead, set api to anthropic-messages and drop the /v1 from baseUrl — Anthropic-style clients use the root base. Confirm the exact api value your Pi version expects.

"api": "anthropic-messages",
"baseUrl": "https://api.tokios.com"

请挑选具备相应工具调用能力的模型

Pi 的智能体借助工具调用功能来读取文件、执行命令以及编辑代码。不过并非所有本地模型都能稳定支持工具调用，因此在让 Pi 执行实际编辑操作前，请务必选择那些具备出色工具调用能力的模型进行部署。关于如何挑选适合智能体编程任务的模型，可参阅按任务选择模型一文获取指导。

故障排查

Tokios 并未出现在 /model 列表中

Pi 无法读取您指定的文件。请确认该文件位于 ~/.pi/agent/models.json 路径下，该目录名称为 .pi 且以点号开头；在 Windows 系统中该路径对应 C:\Users\<you>\.pi\agent\models.json。另外还需确认文件内容符合 JSON 格式：其中 providers 字段的值应为以各提供商名称为键的字典结构，而 models 字段的值则应为数组形式。

401 错误

Pi 发送的 API 密钥缺失、格式有误或已被撤销。请确认 apiKey 字段中存储的是完整的 sk-tok-… 令牌内容且不含多余空白字符，随后前往 Keys 标签页查看该令牌的当前状态。即便 Playground 会话能够正常运行，也不能排除此问题存在的可能，因为 Playground 本身并不使用您所配置的 API 密钥。

404 错误

模型 id 在 models 中的名称与已注册的部署名称不匹配。请运行 GET /v1/models 并完整复制返回的 id 内容。常见的错误是误用了连接器配置中的上游模型 ID Routes[].Model 而非实际的部署名称。

403 错误

该令牌虽已存在，但其权限范围并未覆盖您当前配置的部署环境，或者您的账户已被暂时停用。请前往 Keys 标签页查看该令牌所适用的模型范围。

503 错误

对应部署所使用的连接器处于离线状态或已达到并发处理上限。请查看 Connectors 标签页：该连接器状态应显示为 Online，同时运行该连接器的服务器也必须处于正常运行且可访问的状态。

长时间会话会失败，短时间会话则能正常运作。

Pi 发送的上下文内容超出了后端所能承载的容量。请在模型设置项中将 contextWindow 的值设为服务器实际可处理的上下文长度，随后在 Ollama、llama.cpp、LM Studio 或 vLLM 中确认该配置值是否生效。

后续步骤

omp（oh-my-pi）

更倾向于使用功能完备的分支版本吗？只需按相同方式将 omp 与 Tokios 进行关联即可。

依据任务需求挑选模型

在将本地模型用于 Pi 之前，请先确认它是否契合自主编程任务的需求。

硬件与适配

服务与连接运行时

连接客户端或应用

对比

将 Pi 与您本地的模型搭配使用

前置条件

确定您的部署实例名称

Pi 存储配置信息的位置

自定义服务提供商的配置方法

设置上下文窗口大小（可选）

设为默认配置（可选）

需要调用 Anthropic 接口吗？（可选）

请挑选具备相应工具调用能力的模型

故障排查

后续步骤

omp（oh-my-pi）

依据任务需求挑选模型

​前置条件

​确定您的部署实例名称

​Pi 存储配置信息的位置

​自定义服务提供商的配置方法

​设置上下文窗口大小（可选）

​设为默认配置（可选）

​需要调用 Anthropic 接口吗？（可选）

​请挑选具备相应工具调用能力的模型

​故障排查

​后续步骤

omp（oh-my-pi）

依据任务需求挑选模型

前置条件

确定您的部署实例名称

Pi 存储配置信息的位置

自定义服务提供商的配置方法

设置上下文窗口大小（可选）

设为默认配置（可选）

需要调用 Anthropic 接口吗？（可选）

请挑选具备相应工具调用能力的模型

故障排查

后续步骤