RealRelay.ai
程式碼代理

Crush 設定指南

把 RealRelay.ai 設為 Charm Crush 的 OpenAI 相容供應商:安裝、在 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。

  • 一個模型 ID,完全依照 GET /v1/models 列出的寫法,例如 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

    直接呼叫端點

    用你的金鑰執行這段指令。若收到含 choices 陣列的 JSON 回覆,就代表位址、金鑰與模型都沒問題。

    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 可開啟模型選單,在你註冊過的模型之間切換。要新增模型,請再加一行含 ID 與上限的 model add,然後重新啟動 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 大於模型的實際視窗。請調低到目錄頁面上的數值。

  • 代理描述了要做的修改,卻沒有實際動手。模型沒有呼叫工具。請挑選支援工具呼叫的模型。