RealRelay.ai
编码智能体

Crush 接入指南

把 RealRelay.ai 作为 OpenAI 兼容的提供商接入 Charm Crush：安装、在 crushrc 中添加提供商和模型、检查连接并切换模型。

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

概览

Crush 是 Charm 推出的终端编码智能体。它在你的项目中工作，经你许可后编辑文件、运行命令。你把 RealRelay.ai 添加为它的 openai-compat 提供商后，它会把请求发到 Chat Completions 端点 /v1/chat/completions。

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

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

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

本指南使用 crushrc，这是 Crush 自 v0.88 起采用的配置格式。旧的 crush.json 仍能加载，但已被弃用，不会再获得新选项。如果 Crush 不认识 provider 命令，请先更新它。

安装

使用 Crush README 中列出的任一包管理器安装。

Homebrew (macOS · Linux)
brew install charmbracelet/tap/crush
npm
npm install -g @charmland/crush
Windows PowerShell
1winget install charmbracelet.crush2# or3scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git4scoop install crush
Arch Linux · Nix · FreeBSD
yay -S crush-binnix run github:numtide/nix-ai-tools#crushpkg install crush

如果 crush --version 输出了版本号，说明安装成功。

配置

  1. 1

    把密钥存进环境变量

    配置从 REALRELAY_API_KEY 读取密钥，这样文件本身不含任何机密。

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

    运行 source ~/.zshrc，或者新开一个终端。

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

    关闭并重新打开终端，让它读到新变量。

  2. 2

    在 crushrc 中添加提供商和模型

    如果文件不存在，就新建一个。Windows 上的全局文件是 %USERPROFILE%.config\crush\crushrc。如果只想对单个项目生效，就把同样的内容写进项目根目录的 .crushrc；项目文件优先于全局文件。

    ~/.config/crush/crushrc
    1provider add realrelay \2  --name "RealRelay.ai" \3  --type openai-compat \4  --base-url "https://www.realrelay.ai/v1" \5  --api-key "${REALRELAY_API_KEY:?set REALRELAY_API_KEY}"67model add realrelay/z-ai/glm-5.2 \8  --name "z-ai/glm-5.2" \9  --context-window 200000 \10  --default-max-tokens 320001112model large realrelay/z-ai/glm-5.213model small realrelay/z-ai/glm-5.2

  • crushrc 是一个包含 Crush 命令的 Bash 脚本。Crush 用自己内置的 shell 执行它，所以同一个文件在 Windows 上也能用。

  • --type openai-compat 是 Crush 文档中为 OpenAI 以外的 OpenAI 兼容服务指定的类型。不要使用 openai。

  • 如果变量未设置，${REALRELAY_API_KEY:?…} 会给出明确提示并停止，而不是发送空密钥。

  • model add 会注册模型及其上下文窗口和默认输出上限。RealRelay.ai 的模型列表不包含这些数值，所以 Crush 无法自行得知。

  • model large 是 Crush 启动时使用的模型。model small 负责轻量的后台任务；把它也指向 RealRelay.ai，所有请求就都走同一个密钥。

验证

  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

    确认 Crush 识别到了模型

    第一条命令应在 realrelay 下列出该模型。第二条会发送一条消息并打印回复。

    Terminal
    crush models realrelaycrush run -m "realrelay/z-ai/glm-5.2" "Reply with OK"
  3. 3

    在项目中启动 Crush

    在项目目录中运行 crush，发一条简短消息。该请求会出现在控制台的用量日志中。

模型

在 Crush 中按 ctrl+l 打开模型选择器，在已注册的模型之间切换。要添加模型，就再加一行 model add，写上它的 ID 和限制，然后重启 Crush。

~/.config/crush/crushrc
1model add realrelay/<another-model-id> \2  --name "<another-model-id>" \3  --context-window 128000 \4  --default-max-tokens 16000

这些示例中的数值是安全的起始值。请把 --context-window 和 --default-max-tokens 设为模型目录页上的真实限制。要更改 Crush 启动时使用的模型，修改这两行槽位配置：

~/.config/crush/crushrc
model large realrelay/<model-id>model small realrelay/<faster-model-id>

如果你一个模型都不注册，Crush 会自行从 GET /v1/models 填充列表。但那个列表不含限制信息，所以最好还是注册你要用的模型。适合智能体的模型请见选择模型。

故障排查

  • Crush 提示“set REALRELAY_API_KEY”并停止。启动 Crush 的终端里没有设置该变量。export 它，或者设置后新开一个终端。

  • 401。密钥有误或已被吊销。在 API 密钥页面新建一个，并更新该变量。

  • 404。基础地址缺少 /v1，或者已经以 /chat/completions 结尾。请使用以 /v1 结尾的地址。

  • 找不到模型。realrelay/ 之后的部分必须与 GET /v1/models 返回的 ID 完全一致，包括它自身的前缀，例如 z-ai/。

  • 修改 crushrc 后没有效果。项目中的 .crushrc 或 crushrc 会覆盖全局文件，而同一目录下残留的 crush.json 也会被合并进来。修改后请重启 Crush。开启调试日志运行，可以看到实际加载了什么：

    Terminal
    crush --debugcrush logs --tail 200

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

  • 智能体只描述修改，却不实际执行。该模型没有调用工具。请选择支持工具调用的模型。