Grok Build

TIP

用 skill 自动配置

安装 ModelFold skill 后，可以直接对 Agent 说“把 Grok Build 配置成使用 ModelFold”，由它按本页步骤完成配置；也可以照本页手动配置。

npx skills add https://ai.modelfold.online/

Grok Build 在 api_backend = "responses" 时说的是 Responses 协议,ModelFold 的 Grok 模型正是按这个协议提供的。Grok Build 通过 config.toml 里的 [model.*] 表连过来。

重要规则

1. 通过 GET https://ai.modelfold.online/xai/v1/models 发现模型,不要凭记忆或训练数据写模型名。 这个接口给出的才是 Grok Build 在这个前缀上能跑的那份列表。
2. 用 Authorization: Bearer 认证。 ModelFold 的所有接口都靠这一个请求头携带 API key,列模型接口也一样。名字就叫 apikey 的请求头会被 401 拒掉。
3. 必须设 api_backend = "responses"。 Grok Build 的默认后端是 chat_completions,会往 /v1/chat/completions 发。ModelFold 在 /xai/v1/responses 上提供这些模型。
4. model 字段要填 listing 里的 id。 这才是发给 ModelFold 的名字,既不是表名 [model.<name>],也不是 Grok Build 自带的拼法(例如 grok-4.6)。listing 用的是另一套 id(例如 grok-4-6)。照抄列表里的 id;填自带名字时,就算 base_url 对了 ModelFold 也会拒。
5. 表要写进用户级配置。 项目级 .grok/config.toml 只贡献 MCP、插件和权限相关键,写在那里的 [model.*] 不是推理配置。

列出可用模型

curl -s -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  https://ai.modelfold.online/xai/v1/models |
  jq -r '.data[] | .id'

Windows(PowerShell)下用 curl.exe 发同样的请求:

curl.exe -s -H "Authorization: Bearer $env:MODELFOLD_API_KEY" `
  https://ai.modelfold.online/xai/v1/models | jq -r '.data[].id'

响应是 OpenAI 兼容的形状。.data[] 就是列表:id 是填进 model 的值。object、owned_by、created、aliases 是样板字段。

把 id 列给用户去选。每次都重新跑这个列表,不要复用之前的答案——模型集合会变。

写配置

Grok Build 用 [model.<name>] 表配自定义模型。<name> 是选择器里的键,model 是发给 ModelFold 的 id:

[models]
default = "ModelFold"

[model.ModelFold]
model = "grok-4-6"
base_url = "https://ai.modelfold.online/xai/v1"
name = "ModelFold"
api_backend = "responses"
env_key = "MODELFOLD_API_KEY"

base_url 是发请求的根路径,api_backend = "responses" 时 Grok Build 会自己往后面拼 /responses,所以这里配的是 https://ai.modelfold.online/xai/v1,不是完整的请求 URL https://ai.modelfold.online/xai/v1/responses。

env_key 指的是 Grok Build 从哪个环境变量里读凭证并作为 bearer token 发出去,它本身不存放密钥。优先用它,不要把密钥写进 api_key。

选择器的键——这里的 ModelFold——由你自己取。[models] default 必须是这个键(或另一个 [model.*] 的键),不能是 Grok 内置目录里的名字,否则新会话仍会打到 xAI 而不是 ModelFold。

macOS 与 Linux

文件是 ~/.grok/config.toml。在启动 grok 的同一个 shell 里导出凭证,或者写进 shell profile:

export MODELFOLD_API_KEY=…

设 GROK_HOME 可以把配置放到 ~/.grok 以外的地方。

Windows(PowerShell)

文件是 %USERPROFILE%\.grok\config.toml,内容完全一致。

$env:MODELFOLD_API_KEY = "…"
setx MODELFOLD_API_KEY "…"

确认配置生效

grok models 应列出这个自定义键。grok inspect 会报告哪份配置文件生效。在设好 MODELFOLD_API_KEY 的 shell 里启动 grok 发一条消息,或 grok -p "…" -m ModelFold。

RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok 会写下请求轨迹。看 base_url 和模型 id。

常见坑

1. 名字就叫 apikey 的请求头。 ModelFold 会返回 401。key 要放进 Authorization: Bearer。
2. 把完整请求 URL 写进 base_url。 api_backend = "responses" 时 Grok Build 自己会拼 /responses,所以 base_url 以 /responses 结尾会拼成 /responses/responses。
3. 没写 api_backend。 默认是 chat_completions,会往 /v1/chat/completions 发,不是 /xai/v1/responses。
4. 把 Grok 自带的名字填进了 model。 ModelFold 读的是 [model.<name>] 里的 model 字段,必须是 listing 的 id。自带拼法例如 grok-4.6 不是那个 id。
5. [model.*] 写进了项目级 .grok/config.toml。 那个文件不承载推理配置。用 ~/.grok/config.toml。
6. 把密钥直接写进 env_key。 它填的是环境变量名,密钥本身在那个变量里,不在配置文件里。
7. setx 不影响当前窗口。 它对此后新开的窗口生效。想立刻用上,同时设 $env:。
8. PowerShell 的 curl。 它是 Invoke-WebRequest 的别名,不接受这些参数。用 curl.exe。

要用不是本协议的 listing 里的模型,见「安装 modelfold-chat-agents」页的「协议不一致时」一节。