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 的地址。

  • 一个与 GET /v1/models 列出的完全一致的模型 ID，例如 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

    直接调用端点

    在已设置密钥的终端里运行这条命令。如果返回的 JSON 包含 choices 数组，说明地址、密钥和模型都没问题。

    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。