手动配置完整指南

如果你不想让 AI 代劳，或者想弄清楚每一步到底在做什么，照这份走。全部步骤在 Grok Build 上实测通过。

前置：先登出官方账号

Grok Build 的登录 session 优先级高于 API Key。只要本地还有有效 session，后面配的 api_key 就不会生效，而且报错信息会把你往错误的方向引。

bash

grok --version          # 确认已安装
grok logout             # 必须先登出
ls ~/.grok/auth.json    # 应报 No such file（剩 auth.json.lock 是正常的）

第一步：拿到真实模型名

这一步是地基。不要假设模型叫 grok-4 或 grok-4.5，第三方网关实际提供什么，以接口返回为准。

bash

export K="sk-your-api-key"
export EP="https://your-gateway.example.com/v1"

curl -s "$EP/models" -H "Authorization: Bearer $K"

从返回 JSON 的 data[].id 里读出模型 ID

返回 401 — 密钥无效或写错
返回 404 — 端点路径不对，试试加上或去掉结尾的 /v1
返回 503 — 上游暂时不可用，等一会重试，别急着改配置

第二步：实测一次推理

模型列表能返回，不代表推理能用。这两件事在实际的中转网关上经常不同步。

bash

curl -s "$EP/chat/completions" \
  -H "Authorization: Bearer $K" \
  -H "Content-Type: application/json" \
  -d '{"model":"<第一步拿到的模型ID>","messages":[{"role":"user","content":"hi"}],"max_tokens":20}'

确认返回 200 且 choices[0].message.content 有内容

第三步：写入 config.toml

配置文件在 ~/.grok/config.toml，Windows 上是 %USERPROFILE%\.grok\config.toml。写之前先备份。

toml

[endpoints]
models_base_url = "https://your-gateway.example.com/v1"

[model."grok-4.5"]
api_key = "sk-your-api-key"
context_window = 500000

[models]
default = "grok-4.5"
default_reasoning_effort = "high"

把模型名换成第一步拿到的真实 ID

模型名含小数点时，引号不能省

写成 [model.grok-4.5] 的话，TOML 会把点当层级分隔符，解析成「grok-4 表下的 5 键」，你的 api_key 根本没挂上去。必须写 [model."grok-4.5"]。这是配置失败最常见的原因。

关键字段说明

[endpoints] models_base_url — 核心开关。一旦设置，Grok 就从 session 鉴权切换为 Authorization: Bearer 密钥鉴权，不再需要 grok login。所有 [model.*] 自动继承这个 base_url
[model."..."] api_key — 该模型使用的密钥。凭据解析顺序是 api_key → env_key → 全局 XAI_API_KEY
context_window — 用于计算何时触发自动压缩上下文，按你实际模型的窗口填
[models] default — 默认模型，必须是网关上真实存在的 ID
default_reasoning_effort — 推理强度，可选 low / medium / high
[ui] fork_secondary_model — fork 功能用的副模型，同样必须是真实存在的模型

第四步：收紧权限

配置文件里是明文密钥，别让它保持默认权限。

bash

chmod 600 ~/.grok/config.toml

第五步：验证

写完文件不等于生效。必须验证，而且要验证两次——一次看配置是否被识别，一次看推理是否真的能跑通。

bash

grok models
# 期望看到：Model 'grok-4.5' is using its own API key.
# 期望列出：第一步拿到的那些模型

grok -p "用一句话介绍你自己"

如果看到 You are not authenticated

说明配置没生效。按这个顺序排查：模型名的引号 → 是否真的登出了 → base_url 要不要带 /v1。如果 grok models 列出的是你从没配过的内置模型，基本可以确定是引号问题。

替代方案：只用环境变量

不想改配置文件，或者需要在多个网关之间临时切换，用环境变量也行。适合 CI 或一次性场景。

bash

export GROK_MODELS_BASE_URL="https://your-gateway.example.com/v1"
export XAI_API_KEY="sk-your-api-key"
grok

此时 grok models 会提示 You are using XAI_API_KEY.

GROK_MODELS_BASE_URL — 推理 base URL，模型列表自动从 {base_url}/models 拉取
XAI_API_KEY — 作为 Authorization: Bearer 发送
GROK_MODELS_LIST_URL — 当模型列表地址不是 {base_url}/models 时用它覆盖
GROK_HOME — 覆盖默认的 ~/.grok 目录

回滚：切回官方账号

session 和 API Key 是二选一的关系，想切回去，得先把网关配置撤干净。

bash

# 1. 删掉 config.toml 里的 [endpoints] models_base_url 和各模型的 api_key
# 2. 清掉环境变量
unset GROK_MODELS_BASE_URL XAI_API_KEY
# 3. 重新登录
grok login