跳转到内容
NoviaHub 文档

命令行 Agent

Pi

在 Pi 的 models.json 里把 NoviaHub 添加为兼容接口：安装、配置、验证、切换模型。

Pi（pi.dev）是一个在终端里运行的 Agent，可以读写你电脑上的文件、执行命令。除了内置的模型服务商，它还支持在配置文件 models.json 里添加 OpenAI、Anthropic 或 Google 兼容的接口，用来接入 NoviaHub。

前提条件

Section titled “前提条件”
  • 一把 NoviaHub API 密钥，见 API 密钥；账户里有余额，见 钱包与充值。
  • 用 npm 安装时需要 Node.js 22.19 或更新版本。

安装

Section titled “安装”
终端窗口
curl -fsSL https://pi.dev/install.sh | sh

安装后运行 pi --version 确认安装成功。

配置 NoviaHub

Section titled “配置 NoviaHub”

  1. 把 API 密钥存进环境变量 NOVIAHUB_API_KEY。

    终端窗口
    # macOS 默认用 zsh；Linux 用 bash 的话把 ~/.zshrc 换成 ~/.bashrc
    echo 'export NOVIAHUB_API_KEY="sk-..."' >> ~/.zshrc
    source ~/.zshrc

  2. 编辑配置文件 ~/.pi/agent/models.json（没有就新建），写入下面的内容：

    ~/.pi/agent/models.json
    {
      "providers": {
        "noviahub": {
          "baseUrl": "https://noviahub.com/v1",
          "api": "openai-completions",
          "apiKey": "${NOVIAHUB_API_KEY}",
          "models": [
            {
              "id": "deepseek-v4-flash",
              "name": "deepseek-v4-flash",
              "contextWindow": 1000000,
              "maxTokens": 384000
            },
            {
              "id": "gpt-6-sol",
              "name": "gpt-6-sol",
              "contextWindow": 1050000,
              "maxTokens": 128000
            }
          ]
        }
      }
    }

    各字段的含义：

    字段 说明
    noviahub 服务商 ID，可以自己起名，选模型时写成 noviahub/模型ID。
    baseUrl 用 openai-completions 或 openai-responses 时填 https://noviahub.com/v1（带 /v1）。
    api 协议。openai-completions 对应 OpenAI Chat Completions，2026-09-28 NoviaHub 上所有文本模型都支持。
    apiKey ${NOVIAHUB_API_KEY} 表示从环境变量读取密钥，也可以写成 $NOVIAHUB_API_KEY。
    models 要用的模型列表。id 是 NoviaHub 上的模型 ID，要和 模型&价格 里的写法逐字一致；name 是显示名。
    contextWindow / maxTokens 模型的上下文长度和最大输出长度。可以不写，但不写时 Pi 按 128,000 和 16,384 处理（见 Pi 源码），而 NoviaHub 上很多模型的上下文远大于 128,000，所以建议按实际填写。示例里的数值取自 2026-09-28 的「模型&价格」页，请以页面上的「上下文」「最大输出」为准。
    input 可选，示例里没写。不写时 Pi 把模型当作只接受文字；想发图片，给「输入类型」里包含图片的模型加上 "input": ["text", "image"]。

  3. 进入项目目录，运行：

    终端窗口
    pi --model noviahub/deepseek-v4-flash

用 Anthropic 协议调用 Claude 模型（可选）

Section titled “用 Anthropic 协议调用 Claude 模型（可选）”

openai-completions 也能调用 Claude 模型，但会经过协议转换，部分特性会丢失，见 协议转换。想让 Claude 模型走 Anthropic Messages 协议，可以在 providers 里再加一个服务商 noviahub-claude。注意它的 baseUrl 不带 /v1，因为 Pi 的 Anthropic 客户端会自己加上 /v1/messages。加好后的完整文件如下：

~/.pi/agent/models.json
{
  "providers": {
    "noviahub": {
      "baseUrl": "https://noviahub.com/v1",
      "api": "openai-completions",
      "apiKey": "${NOVIAHUB_API_KEY}",
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "deepseek-v4-flash",
          "contextWindow": 1000000,
          "maxTokens": 384000
        },
        {
          "id": "gpt-6-sol",
          "name": "gpt-6-sol",
          "contextWindow": 1050000,
          "maxTokens": 128000
        }
      ]
    },
    "noviahub-claude": {
      "baseUrl": "https://noviahub.com",
      "api": "anthropic-messages",
      "apiKey": "${NOVIAHUB_API_KEY}",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "claude-sonnet-5",
          "contextWindow": 1000000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

之后用 pi --model noviahub-claude/claude-sonnet-5 启动。模型详情里要有 Anthropic 端点标签才能这样调用。

验证

Section titled “验证”
终端窗口
# 列出可用模型，可以加关键词筛选
pi --list-models deepseek

能看到 noviahub 下的模型后，启动 Pi 问一句话。能收到回复，并且 NoviaHub 的 使用日志 里出现这次调用，就说明配置成功。

切换模型

Section titled “切换模型”
  • 在 Pi 里输入 /model 搜索并选择模型；在某个模型上按 Ctrl+S，会把它保存为新会话的默认模型。
  • 按 Ctrl+P 在可用模型之间轮换。
  • 启动时指定：pi --model noviahub/gpt-6-sol。

新模型要先加进 models.json 的 models 列表。打开 /model 时 Pi 会重新读取 models.json，不用重启。

常见问题

Section titled “常见问题”

/model 里看不到 models.json 里配置的模型 官方说明：Pi 要能拿到密钥，自定义模型才会出现在 /model 里。环境变量必须在启动 Pi 的那个终端里生效。在同一个终端里运行 echo $NOVIAHUB_API_KEY（PowerShell 用 echo $env:NOVIAHUB_API_KEY），确认能打印出密钥。

换一个终端就用不了 同上，新终端里没有读到环境变量。按「配置 NoviaHub」第 1 步把变量写进 ~/.zshrc / ~/.bashrc，或在 Windows 上用 setx 永久保存。

返回 401 Invalid token（无效的令牌） 密钥写错了，或者这把密钥已被禁用、已过期、额度已用完。到「API 密钥」页检查状态，见 API 密钥 · 密钥的四种状态。

返回 403 insufficient_user_quota 账户余额不足，先充值。

参考资料

Section titled “参考资料”

以下资料查阅于 2026-09-28 至 2026-09-29：