跳转到主要内容
omp(oh-my-pi)是一款功能完备的开源终端编程智能体,它是 Pi 的分支版本,新增了 LSP 集成、基于 DAP 的调试功能、子智能体协同机制以及跨 40 多个服务提供商的按角色模型路由能力。与 Pi 类似,它同样从配置文件中读取服务提供商信息,因此您可轻松添加 Tokios 作为自定义提供商,将 baseUrl 指向 https://api.tokios.com/v1,进而调用连接器后端的任意模型,且无需对外暴露该模型的端口。

前置条件

  • 确保 Tokios 连接器与本地模型均正常运行——详情参见 连接器安装
  • 已成功完成模型部署——详情参见 模型注册
  • 已获取 Tokios API 密钥(sk-tok-…)——详情参见 API 密钥管理
  • 已安装 omp:

确定您的部署名称

omp 发送的是部署名称——即您在控制台中注册的公共名称——而非本地后端使用的上游模型 ID。这 2 者通常是不同的字符串,混淆它们是最常见的 404 错误原因。 查看当前 API 密钥可访问的所有部署列表:
响应内容中的所有 id 均为您可在 models.yml 中使用的有效值。
即便您的模型本身已能以 Playground 格式输出结果,也请务必执行此操作。由于 Playground 依赖您当前登录的浏览器会话进行身份验证,因此即便测试成功,也无法确保您的 sk-tok-… 令牌具备相应权限或适用于该部署环境。而 GET /v1/models 才是真正调用该令牌的首次操作。

OMP 存储配置信息的路径

omp 从主目录中以点号开头的 .omp 目录中读取 2 个文件:
若相关文件夹或文件尚未创建,请手动创建。
该文件夹名称为 .omp,且必须以点号开头。若您在 omp/agent/models.yml 路径下手动创建文件,OMP 将无法识别该文件;此时程序会正常启动,只是您的服务提供商信息不会出现在 /model 列表中。

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

请将以下内容粘贴至 models.yml 文件中,并替换其中的 2 占位符数值。此内容为一个完整的配置文件,而非片段。
models.yml
一个提供商配置块即可服务于您账户下的所有部署。请针对每项部署在 models 下添加相应条目。
models.yml
将 gemma-tunnel 替换为 GET /v1/models 中的某个部署名称——该名称并非后端服务(Ollama、llama.cpp、vLLM 或 LM Studio)所使用的具体上游模型 ID,亦非连接器配置中的 Routes[].Model 值。随后将 sk-tok-YOUR_KEY 替换为您自己的 API 密钥,切记切勿将含有真实密钥的 models.yml 内容提交至版本控制系统。
baseUrl 的值必须包含 /v1,且末尾不可带有斜杠。由于 omp 的 openai-completions 提供商是基于该 URL 构建请求路径的,若使用 https://api.tokios.com 则无法正确访问 Tokios API,而 https://api.tokios.com/v1/ 则会导致路径中出现重复分隔符。
omp 的配置架构在不同版本间可能有所变动,因此请参照您当前安装的版本确认确切的键名(参见 omp.sh/docs)。建议先采用上文所示的最小化配置块;待 omp 在 /model 中成功列出您的模型后,再添加下文提到的可选字段即可。

将特定角色指向您的模型(可选)

OMP 可将命名后的角色分别映射到对应的模型,每个模型还可设置可选的回退链。在 settings.yml 处使用 provider/model 语法将某个角色指向您的 Tokios 提供商即可:
settings.yml
若无需此步骤,也可在 omp 的 TUI 界面中通过 /model 命令在运行时指定提供商与模型。
由于角色名称均以 provider/model 形式书写,选用简短、全小写且以连字符连接的部署名称可确保配置无误——此命名规则与 注册模型 中的建议一致。若某个部署名称本身已包含 / 字符,则建议通过 /model 方式指定该部署,而非将其直接绑定至特定角色。

设置上下文窗口大小(可选)

omp 会根据模型所具备的上下文窗口大小来组织输入提示内容。Ollama、llama.cpp、LM Studio 与 vLLM 实际提供的上下文长度均为模型加载时所设定的数值,而非理论上的最大值,因此您需向 omp 提供该真实数值。
若设置值过大,omp 生成的提示内容可能超出本地服务器的承载范围,此类错误虽由 Tokios 返回,实则源于本地环境。短提示内容往往不会暴露此问题,因此通常仅在 omp 开始发送完整文件时才会显现异常。

需要调用 Anthropic 接口吗?(可选)

omp 也可以使用 Anthropic 消息协议。若要通过 Tokios 的 Anthropic 接口进行路由,请将 api 设为 anthropic-messages 并去掉 /v1,因为 baseUrl 仅使用根路径。

选择具备工具调用能力的模型

omp的智能体功能依赖工具调用来读取文件、执行命令以及编辑代码。并非所有本地模型都能稳定实现工具调用功能,因此在正式启用omp进行代码编辑前,请务必选择一款在工具调用方面表现优异的模型进行部署。关于如何根据具体任务挑选合适模型,可参阅 按任务选择模型 一文获取指导。

故障排查

omp无法读取您指定的文件。请确认该文件位于 ~/.omp/agent/models.yml 路径下,该目录名称为 .omp 且以点号开头;在Windows系统中该路径对应 C:\Users\<you>\.omp\agent\models.yml。此外还需确保文件格式为有效的YAML格式:providers 应为以提供商名称为键的映射结构,而 models 则应为列表形式。
omp发送的API 密钥缺失、格式有误或已被撤销。请确认 apiKey 中存储的 sk-tok-… 密钥内容完整且不含多余空白字符,随后前往 Keys 页面检查该密钥的实际状态。即便Playground功能可正常运行,也不能排除此问题存在的可能,因为Playground本身并不调用您的API 密钥。
模型 id(位于 models 下)与已注册的部署不匹配。请运行 GET /v1/models 并从响应中精确复制一个 id。一个常见的近似错误是使用连接器 Routes[].Model 中的上游模型 ID 而非部署名称。
该密钥虽已存在,但并未被配置为适用于您当前部署环境的权限范围,或者您的账户目前处于被暂停状态。请前往 Keys 页面查看该密钥所适用的模型范围。
对应部署所使用的连接器处于离线状态,或者已达到并发上限。请查看 Connectors 选项卡,确保连接器状态显示为 Online,同时运行该连接器的机器也处于正常运行且可访问状态。
omp 发送的上下文内容超出了后端所能承载的容量。请在模型设置页面将 contextWindow 的数值调整为服务器实际可处理的上下文长度,随后在 Ollama、llama.cpp、LM Studio 或 vLLM 中确认该配置是否生效。

后续操作指引

Pi

omp 是 Pi 的分支版本,其上游代理与 Tokios 的连接方式也完全相同。

依据具体任务挑选合适的模型

在将本地模型投入 omp 使用之前,请先验证其是否适配智能编程相关的任务需求。