RealRelay.ai
编码智能体

nanobot 接入指南

把 RealRelay.ai 作为 OpenAI 兼容的自定义提供商接入 nanobot：安装、在 config.json 中添加提供商和模型预设、检查配置并切换模型。

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

概览

nanobot 是 HKUDS 推出的一个小巧的开源个人智能体。它运行在你自己的机器上，可以处理文件、记住偏好、执行定时任务，你可以在浏览器、终端或聊天应用中与它对话。你把 RealRelay.ai 添加为自定义提供商，它使用 OpenAI Chat Completions API（/v1/chat/completions）。

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

  • 末尾带 /v1 的基础地址。nanobot 不会为自定义提供商猜测 URL，所以这个字段必填。

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

nanobot 无法从 RealRelay.ai 读取模型的上下文窗口。请按“配置”一节所示，在模型预设中设置。本页介绍的是以 nanobot-ai 名称发布在 PyPI 上的 nanobot 智能体，而不是其他同名项目。

安装

nanobot 需要 Python 3.11 或更高版本。官方安装程序会为你选定一个隔离的 Python 环境，并在安装完成后打开设置。如果你已经在用 uv，也可以自己安装这个包。

macOS · Linux
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
Windows PowerShell
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
uv (Python 3.11+)
uv tool install nanobot-ainanobot onboard

安装程序会打印它用来运行 nanobot 的确切命令。请记下来：如果 nanobot 不在你的 PATH 中，下文所有地方都用那条命令代替。

配置

你可以在浏览器的 Settings → Models 中设置提供商：新建一个预设，在 Provider 菜单中选择 Add provider，然后填入连接信息。下面的步骤则是直接在文件中修改同样的设置。

  1. 1

    把密钥存进环境变量

    这样密钥就不会出现在配置文件里。完成后请新开一个终端。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"
    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")
  2. 2

    添加提供商和模型预设

    把下面这些配置块合并进 ~/.nanobot/config.json，保留文件中已有的其他设置。如果文件还不存在，请先运行 nanobot onboard。

    ~/.nanobot/config.json
    1{2  "providers": {3    "realrelay": {4      "apiKey": "${REALRELAY_API_KEY}",5      "apiBase": "https://www.realrelay.ai/v1"6    }7  },8  "modelPresets": {9    "primary": {10      "provider": "realrelay",11      "model": "z-ai/glm-5.2",12      "maxTokens": 8192,13      "contextWindowTokens": 20000014    }15  },16  "agents": {17    "defaults": {18      "modelPreset": "primary"19    }20  }21}
  3. 3

    重启 nanobot

    nanobot 在启动时填入密钥。如果 WebUI 或 gateway 已在运行，请先停止再重新启动。

  • realrelay 是你给提供商起的名字。它必须与预设中的 provider 一致，并且不能与 openai 等内置提供商重名。

  • ${REALRELAY_API_KEY} 会在启动时从环境中填入。该值永远不会写回文件。

  • 在这里显式设置 provider 很重要。设置之后，nanobot 会按原样发送 z-ai/glm-5.2。如果保持 auto，nanobot 可能会把斜杠前面的部分当成提供商名称。

  • contextWindowTokens 是模型的窗口，maxTokens 限制单次回复的长度。这里显示的值是安全下限；请使用模型目录页上的数值。

验证

  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

    检查 nanobot 的配置并发送一条消息

    nanobot status 只检查配置，不调用模型。它应在 Config 和 Workspace 旁显示对勾，显示 primary 预设，并显示该提供商已配置。第二条命令会发送一条消息。

    Terminal
    nanobot statusnanobot agent -m "Reply with OK"
  3. 3

    检查回复

    只要收到正常回答，就说明 nanobot 能加载配置并连通模型。该请求会出现在控制台的用量日志中。然后用 nanobot webui 在 WebUI 中再试一次。

模型

每个模型都是一个具名预设。每个 RealRelay.ai 模型加一个预设，各自设置限制：

~/.nanobot/config.json → modelPresets
1"claude": {2  "provider": "realrelay",3  "model": "anthropic/claude-sonnet-4-6",4  "maxTokens": 8192,5  "contextWindowTokens": 2000006}

用 /model 加预设名称，把当前会话切换到该模型。这个选择只对当前会话有效；新会话仍默认使用 agents.defaults.modelPreset。

nanobot chat
/model claude

不要把预设命名为 default，这个名称是保留的。如果希望请求失败时回退到另一个预设，请把它列在 agents.defaults.fallbackModels 中。适合智能体的模型列在选择模型中。

故障排查

  • nanobot 启动时停止，并提到 REALRELAY_API_KEY。启动 nanobot 的环境中没有设置该变量。设置它，新开一个终端，然后重新启动。

  • 401 或“invalid API key”。密钥有误、首尾带有空格，或者放在了与预设所用名称不同的提供商下。

  • 404。apiBase 缺少 /v1。把它加上。

  • 找不到模型。模型 ID 与 GET /v1/models 不完全一致，或者预设的 provider 为 auto，导致 nanobot 把请求发到了别处。把 provider 设为 realrelay。

  • “provider not found”。预设中的 provider 与 providers 下的键拼写不一致。

  • JSON 解析错误。合并配置块后漏了逗号或花括号。这里的示例只是文件的片段，不是完整文件。

  • 修改没有效果。你编辑文件时 nanobot 已在运行。请重启 WebUI 或 gateway。

  • 用 nanobot agent 正常，但在聊天应用中不行。模型配置没有问题。用 nanobot channels status 检查渠道设置。