RealRelay.ai
程式碼代理

Factory Droid 設定指南

在 ~/.factory/settings.json 中新增自訂模型,將 Factory 的 Droid CLI 接上 RealRelay.ai:安裝、加入模型、檢查連線並選擇模型。

建立 API 密鑰瀏覽模型目錄
協定
OpenAI Chat Completions · Anthropic Messages · OpenAI Responses
基礎位址
https://www.realrelay.ai/v1
官方文件
docs.factory.com
已對照工具官方文件核對
2026-10

概覽

Droid 是 Factory 推出的終端機程式碼代理(另有桌面應用程式)。它會讀取你的程式碼庫、提出 diff,並等你核准後才進行編輯。它的自帶金鑰自訂模型可以使用三種協定。大多數模型請使用通用的 Chat Completions 供應商與 RealRelay.ai 的 /v1/chat/completions 端點。Claude 模型可使用 /v1/messages,而少數只支援 Responses 的模型則使用 /v1/responses。

  • 一組 API 金鑰,在主控台的 API 金鑰頁面取得。

  • Chat Completions 與 Responses 供應商使用含 /v1 的基礎位址,Anthropic 供應商則使用不含 /v1 的位址。

  • 一個模型 ID,完全依照 GET /v1/models 列出的寫法,例如 z-ai/glm-5.2。

Factory 表示,它只在官方 API 上完整測試 Anthropic 與 OpenAI 的模型,不保證每個自訂模型都能開箱即用。你的金鑰只留在你的電腦上;自訂模型可在 Droid CLI 與桌面應用程式中使用,但不能用於 Factory 的網頁版或行動應用程式。

安裝

請使用 Factory 提供的任一種安裝方式。在 Linux 上,Factory 還需要 xdg-utils 套件。

macOS · Linux
curl -fsSL https://app.factory.ai/cli | sh
Homebrew
brew install --cask droid
Windows PowerShell
irm https://app.factory.ai/cli/windows | iex
npm
npm install -g droid

在專案資料夾中執行 droid。如果它要求登入,請先在瀏覽器中完成 Factory 帳戶的登入。

設定

  1. 1

    把金鑰放進環境變數

    設定檔以變數名稱參照金鑰,所以金鑰本身永遠不會出現在檔案中。請把 sk-*** 換成你的金鑰。

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

    執行 source ~/.zshrc,或開啟新的終端機。

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

    完成後請關閉並重新開啟終端機。

  2. 2

    新增自訂模型

    在 ~/.factory/settings.json 的 customModels 陣列中新增一個項目。如果檔案中已有其他設定或自訂模型,請把該項目合併進去,不要整個取代檔案。Droid 不需重新啟動就會套用變更。

    ~/.factory/settings.json
    1{2  "customModels": [3    {4      "model": "z-ai/glm-5.2",5      "displayName": "RealRelay",6      "baseUrl": "https://www.realrelay.ai/v1",7      "apiKey": "${REALRELAY_API_KEY}",8      "provider": "generic-chat-completion-api",9      "maxContextLimit": 200000,10      "maxOutputTokens": 3200011    }12  ]13}
    ~/.factory/settings.json
    1{2  "customModels": [3    {4      "model": "anthropic/claude-sonnet-4-6",5      "displayName": "RealRelay Claude",6      "baseUrl": "https://www.realrelay.ai",7      "apiKey": "${REALRELAY_API_KEY}",8      "provider": "anthropic",9      "authMode": "bearer",10      "maxContextLimit": 200000,11      "maxOutputTokens": 3200012    }13  ]14}
    ~/.factory/settings.json
    1{2  "customModels": [3    {4      "model": "openai/gpt-5.3-codex",5      "displayName": "RealRelay Codex",6      "baseUrl": "https://www.realrelay.ai/v1",7      "apiKey": "${REALRELAY_API_KEY}",8      "provider": "openai",9      "maxContextLimit": 200000,10      "maxOutputTokens": 3200011    }12  ]13}

  • provider 決定協定。generic-chat-completion-api 是 Chat Completions,anthropic 是 Anthropic Messages,openai 則是 Responses API。凡不是 OpenAI 或 Anthropic 自家 API 的服務,Factory 都建議使用通用供應商。

  • "apiKey": "${REALRELAY_API_KEY}" 會讓 Droid 從同名的環境變數讀取金鑰。

  • authMode: "bearer" 會讓 Anthropic 供應商以 Authorization: Bearer 送出金鑰,與 RealRelay.ai 其他所有端點相同。

  • maxContextLimit 與 maxOutputTokens 用來告訴 Droid 模型的上限,因為它無法從 RealRelay.ai 讀取這些資訊。詳情見「模型」一節。

  • 你也可以改在 Droid 中新增同樣的項目:執行 /settings 並開啟 Custom models,或執行 /model 並選擇 Manage custom models。在桌面應用程式中則是 Settings → Custom Models。

驗證

  1. 1

    直接呼叫端點

    在已設定金鑰的終端機中執行這段指令。若收到含 choices 陣列的 JSON 回覆,就代表位址、金鑰與模型都沒問題。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer $REALRELAY_API_KEY" \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

    執行單一提示詞

    droid exec 以 custom:、把空格換成連字號的顯示名稱,以及它在 customModels 中從 0 起算的位置來指稱自訂模型。如果 RealRelay 不是你的第一個自訂模型,請修改那個數字。

    Terminal
    droid exec --model "custom:RealRelay-0" "Reply with OK"
  3. 3

    在工作階段中選取模型

    啟動 droid,執行 /model,然後在 Custom Models 底下選擇 RealRelay。送出一則簡短訊息;收到回覆,且主控台的用量日誌中出現該請求,即確認整條路徑暢通。

    Droid
    cd /path/to/your/projectdroid/model

模型

你想使用的每個 RealRelay.ai 模型,都是 customModels 中各自獨立的項目,並有自己的 displayName。請以 /model 在它們之間切換。

請把 maxContextLimit 設為模型目錄頁面上的上下文視窗;如果該視窗也計入輸出,請再減去 maxOutputTokens。如果省略這個值,而 Droid 又不認得該模型,它會假設為 250,000 token 或你的壓縮上限(取兩者中較高者),這對較小的模型來說太大了。Droid 會壓縮對話,讓它保持在這個範圍內。不過,設定較大的值並不會讓 Droid 較晚才壓縮:壓縮預設仍從 250,000 token 開始,要調高請到 /settings(並保持低於 maxContextLimit)。範例中的數值對這裡提到的模型都是安全的。

Factory 指出,參數量低於約 30B 的模型在代理式程式開發上的表現差很多。請選擇支援工具呼叫、上下文視窗夠大的模型;請參閱選擇模型。

疑難排解

  • 模型沒有出現在 Custom Models 底下。settings.json 不是有效的 JSON,或缺少必要欄位(model、baseUrl、provider)。

  • 「Invalid provider」。provider 必須完全是 generic-chat-completion-api、anthropic、openai 或 bedrock-converse 其中之一。

  • 401 或其他驗證錯誤。啟動 Droid 的環境中沒有設定 REALRELAY_API_KEY,或金鑰錯誤。請開啟新的終端機,再重新啟動 Droid。

  • 404。基礎位址形式與供應商不符:Anthropic 供應商使用不含 /v1 的網站位址,另外兩種則需要它。

  • 使用 openai 供應商時出現指名該模型的錯誤。該供應商使用 Responses,而 RealRelay.ai 只為少數模型提供 Responses。其他所有模型,包括一般的 openai/gpt-5.x,請使用 generic-chat-completion-api。

  • 圖片被忽略。Droid 預設會關閉通用供應商的圖片輸入。只有在模型接受圖片時,才設定 "noImageSupport": false。