RealRelay.ai
编码智能体

Pi 接入指南

在 models.json 中把 RealRelay.ai 添加为自定义提供商，将 Pi 编码智能体接入 RealRelay.ai：安装、添加提供商、检查连接，并选择模型和思考级别。

创建 API 密钥浏览目录
协议
OpenAI Chat Completions
基础地址
https://www.realrelay.ai/v1
官方文档
github.com
已对照工具官方文档核对
2026-10

概览

Pi 是一个小巧、可扩展的终端编码智能体。它会读取和编辑你项目中的文件，并运行命令。在它的 models.json 文件中添加一个自定义提供商，即可接入 RealRelay.ai。该提供商使用 OpenAI Chat Completions API（/v1/chat/completions）。

  • 一个从控制台的 API 密钥页面获取的 API 密钥。

  • 末尾带 /v1 的基础地址。Pi 会在后面拼上 /chat/completions。

  • 一个与 GET /v1/models 列出的完全一致的模型 ID，例如 z-ai/glm-5.2。请选择支持工具调用的模型。

Pi 在 earendil-works/pi 仓库中开发。Oh My Pi 是另一个独立项目，配置格式也不同；请参阅 Oh My Pi 接入指南。

安装

使用 Pi 的安装程序。它会在需要时安装 Node.js、锁定 Pi 的依赖版本，之后你可以用 pi update 更新。

macOS · Linux
curl -fsSL https://pi.dev/install.sh | shpi --version
Windows PowerShell
powershell -c "irm https://pi.dev/install.ps1 | iex"pi --version
npm (Node.js 22.19+)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

npm 方式需要 Node.js 22.19 或更高版本，并且不会锁定 Pi 的依赖版本。

如果 pi --version 输出了版本号，说明安装成功。如果提示找不到命令，请新开一个终端。

配置

  1. 1

    把密钥放进环境变量

    配置文件通过变量名引用密钥，所以密钥本身不会写进文件。把 sk-*** 替换成你的密钥。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    启动 Pi 之前，先运行 source ~/.zshrc，或者新开一个终端。

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    启动 Pi 之前，先关闭并重新打开终端。

  2. 2

    把 RealRelay.ai 添加到 models.json

    新建 ~/.pi/agent/models.json；如果文件已存在，就在 providers 对象中添加 realrelay 条目。

    ~/.pi/agent/models.json
    1{2  "$schema": "https://pi.dev/schemas/models.schema.json",3  "providers": {4    "realrelay": {5      "name": "RealRelay.ai",6      "baseUrl": "https://www.realrelay.ai/v1",7      "api": "openai-completions",8      "apiKey": "$REALRELAY_API_KEY",9      "compat": {10        "supportsDeveloperRole": false11      },12      "models": [13        {14          "id": "z-ai/glm-5.2",15          "contextWindow": 200000,16          "maxTokens": 3276817        }18      ]19    }20  }21}

    对于先思考再回答的模型，请使用这种写法，这样 Pi 的思考级别才能传到 RealRelay.ai。三项推理设置缺一不可；少了任何一项，你选的级别都不会被发送。

    ~/.pi/agent/models.json
    1{2  "$schema": "https://pi.dev/schemas/models.schema.json",3  "providers": {4    "realrelay": {5      "name": "RealRelay.ai",6      "baseUrl": "https://www.realrelay.ai/v1",7      "api": "openai-completions",8      "apiKey": "$REALRELAY_API_KEY",9      "compat": {10        "supportsDeveloperRole": false,11        "supportsReasoningEffort": true12      },13      "models": [14        {15          "id": "z-ai/glm-5.2",16          "contextWindow": 200000,17          "maxTokens": 32768,18          "reasoning": true,19          "thinkingLevelMap": { "xhigh": "high", "max": "high" }20        }21      ]22    }23  }24}

  • "$REALRELAY_API_KEY" 让 Pi 在发送请求时从该变量读取密钥。启动 Pi 的终端里必须设置了这个变量。

  • supportsDeveloperRole: false 让 Pi 使用标准的 system 角色发送指令。RealRelay.ai 上的许多模型会拒绝较新的 developer 角色。

  • contextWindow 和 maxTokens 默认分别为 128,000 和 16,384。RealRelay.ai 不会报告模型的限制，所以请按模型目录页设置。切勿设得高于真实上限；Pi 依据 contextWindow 决定何时压缩对话。

  • 在推理模型写法中，supportsReasoningEffort 允许 Pi 发送 reasoning_effort，thinkingLevelMap 则把 xhigh 和 max 级别按 high 发送，使这两个级别可用。

  • 如果想把 Pi 的文件放在 ~/.pi/agent 以外的位置，请设置 PI_CODING_AGENT_DIR。

验证

  1. 1

    直接调用端点

    用你的密钥运行这条命令。如果返回的 JSON 包含 choices 数组，说明地址、密钥和模型都没问题。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
  2. 2

    确认 Pi 识别到了模型

    --list-models 应在 realrelay 下列出你的模型。第二条命令会发送一条提示词，打印回答后退出。

    Terminal
    pi --list-models realrelaypi --provider realrelay --model "z-ai/glm-5.2" --print "Reply with OK"
  3. 3

    在项目中启动会话

    发一条简短消息。收到回复即说明整条链路畅通，该请求也会出现在控制台的用量日志中。

    Terminal
    cd /path/to/your/projectpi --provider realrelay --model "z-ai/glm-5.2"

模型

在 Pi 中，/model 会打开一个可搜索的列表。在某个模型上按 Ctrl+S 可将其设为新会话的默认模型，Ctrl+P 可在模型之间循环切换。打开 /model 还会重新加载 models.json，所以修改无需重启即可生效。

Pi 只提供你在提供商下列出的模型。每个模型加一个条目，各自设置限制：

~/.pi/agent/models.json → providers.realrelay.models
{ "id": "z-ai/glm-5.2", "contextWindow": 200000, "maxTokens": 32768 },{ "id": "deepseek/deepseek-v4-pro", "contextWindow": 200000, "maxTokens": 32768 }

对于推理模型，可在会话中用 /thinking、或在命令行中用 --thinking 选择级别。Pi 只提供该模型条目允许的级别。

Terminal
pi --provider realrelay --model "z-ai/glm-5.2" --thinking high

哪些模型适合智能体，请见选择模型。

故障排查

  • /model 中没有该模型。如果提供商没有可用的密钥，Pi 会隐藏它的模型。检查启动 Pi 的终端里是否设置了 REALRELAY_API_KEY，以及 models.json 是否为合法的 JSON。

  • 401，或者只在某一个终端里能用。那个终端里缺少该变量。修改 profile 后请新开一个终端，或用 echo $REALRELAY_API_KEY 检查。

  • 404。baseUrl 缺少 /v1，或者已经以 /chat/completions 结尾。

  • 400 并提到 developer 角色。在 compat 下添加 "supportsDeveloperRole": false。

  • 思考级别似乎不起作用。三项推理设置中缺了一项。请对照上面的推理模型写法检查你的条目。

  • 400 并提到 reasoning_effort。该模型不接受这个字段。请对它使用基础配置，不加推理设置。

  • 长会话中出现上下文报错。contextWindow 大于模型的真实上限。把它调低到模型目录页上的数值。