跳转到内容
NoviaHub 文档

命令行 Agent

Grok Build

在 Grok Build 的 config.toml 里把 NoviaHub 的模型添加为自定义模型：安装、配置、验证、切换模型。

Grok Build 是 xAI 推出的编程 Agent（官方介绍：a powerful and extensible coding agent），可以在终端的全屏界面里使用，也可以在脚本里无界面运行。它支持在配置文件里添加「自定义模型」，每个模型可以单独指定接口地址和协议，用来接入 NoviaHub。

前提条件

Section titled “前提条件”

安装

Section titled “安装”
终端窗口
curl -fsSL https://x.ai/cli/install.sh | bash

配置 NoviaHub

Section titled “配置 NoviaHub”

  1. 把 API 密钥存进环境变量 NOVIAHUB_API_KEY。配置文件里只写变量名，Grok Build 启动时从环境变量读取密钥。

    终端窗口
    # macOS 默认用 zsh；Linux 用 bash 的话把 ~/.zshrc 换成 ~/.bashrc
    echo 'export NOVIAHUB_API_KEY="sk-..."' >> ~/.zshrc
    source ~/.zshrc

  2. 编辑配置文件，没有就新建：

    • macOS / Linux：~/.grok/config.toml
    • Windows：%USERPROFILE%\.grok\config.toml

    写入下面的内容。这里添加了两个模型：deepseek-v4-flash 走 OpenAI Chat Completions 协议，claude-sonnet-5 走 Anthropic Messages 协议。

    ~/.grok/config.toml
    [model.deepseek-v4-flash]
    model = "deepseek-v4-flash"
    name = "deepseek-v4-flash (NoviaHub)"
    base_url = "https://noviahub.com/v1"
    env_key = "NOVIAHUB_API_KEY"
    api_backend = "chat_completions"
    context_window = 1000000
    

    [model.claude-sonnet-5]
    model = "claude-sonnet-5"
    name = "claude-sonnet-5 (NoviaHub)"
    base_url = "https://noviahub.com/v1"
    env_key = "NOVIAHUB_API_KEY"
    api_backend = "messages"
    context_window = 1000000
    

    [models]
    default = "deepseek-v4-flash"

    各字段的含义：

    字段 说明
    [model.<名称>] 这个模型在 Grok Build 里的名称，切换模型时用它。名称里有 .（例如 gpt-5.6-sol）时要加双引号：[model."gpt-5.6-sol"]。
    model 发给 NoviaHub 的模型 ID，要和 模型&价格 里的写法逐字一致。
    name 在模型选择器里显示的名字，可以随便写。
    base_url 填 https://noviahub.com/v1。三种协议都要带 /v1，Grok Build 会在后面接上 /chat/completions、/responses 或 /messages。
    env_key 保存密钥的环境变量名。
    api_backend 协议，见下一节。不写时默认是 chat_completions。
    context_window 模型的上下文长度，Grok Build 用它判断何时自动压缩对话。官方说明：新添加的模型不写这一项时，按 200,000 tokens 处理。示例里的数值取自 2026-09-28 的「模型&价格」页，请以页面上的「上下文」为准。
    [models] 下的 default 启动时默认使用的模型，填上面某个 [model.<名称>] 里的名称。

  3. 重新打开终端，进入项目目录，运行 grok。只要 NOVIAHUB_API_KEY 在这个终端里有值，Grok Build 就不会要求登录 xAI 账号，见下方「常见问题」。

api_backend 怎么选

Section titled “api_backend 怎么选”

api_backend 要和模型支持的协议对应。到 模型&价格 打开模型详情，看端点标签：

api_backend 请求的接口 模型需要有的端点标签
chat_completions（默认） /v1/chat/completions Chat
responses /v1/responses Response
messages /v1/messages Anthropic

2026-09-28 NoviaHub 上所有文本模型都带 Chat 标签，所以不确定时用 chat_completions 即可。Claude 模型建议用 messages，原因见 协议转换。

验证

Section titled “验证”
终端窗口
# 列出全部可用模型，应该能看到上面添加的两个
grok models


# 不进入界面，直接用指定模型问一句话
grok -p "用一句话介绍你自己。" -m deepseek-v4-flash

能收到回复，并且 NoviaHub 的 使用日志 里出现这次调用，就说明配置成功。改完配置后也可以运行 grok inspect，查看 Grok Build 读到了哪些配置。

切换模型

Section titled “切换模型”
  • 在界面里输入 /model claude-sonnet-5（也可以简写成 /m claude-sonnet-5）。
  • 焦点在对话记录区时按 Ctrl+M，打开模型选择器。
  • 启动时指定：grok -m claude-sonnet-5。
  • 修改配置文件 [models] 下的 default，作为默认模型。

要用新模型，先在配置文件里给它加一段 [model.<名称>]。

常见问题

Section titled “常见问题”

首次启动时要不要登录 xAI 账号 不需要。官方文档写的是「首次启动时会打开浏览器登录」，但 Grok Build 源码里另有规则：启动时只要有模型带着自己的密钥（env_key 指向的环境变量有值，或者写了 api_key），就直接进入界面，不显示登录页。官方文档也说明，模型自己的 env_key / api_key 优先于登录后的会话。

所以如果启动后还是打开了浏览器，通常是 NOVIAHUB_API_KEY 在当前终端里没有值。关掉 Grok Build，运行 echo $NOVIAHUB_API_KEY（PowerShell 用 echo $env:NOVIAHUB_API_KEY）确认能打印出密钥后再启动。

grok models 里找不到自己添加的模型 检查 config.toml 里 [model.<名称>] 的拼写；名称带 . 时要加双引号。

用 responses 协议时报错，提示与 reasoning.summary 有关 官方说明：Grok Build 在 Responses 协议下默认会请求简要的推理摘要（reasoning.summary）。在该模型那一段加上 reasoning_summary = "none"，就不再发送这个字段。

返回 401 Invalid token（无效的令牌） 密钥写错了、环境变量没有生效，或者这把密钥已被禁用、已过期、额度已用完。先在同一个终端里运行 echo $NOVIAHUB_API_KEY（PowerShell 用 echo $env:NOVIAHUB_API_KEY）确认能打印出密钥，再到「API 密钥」页检查状态，见 API 密钥 · 密钥的四种状态。

返回 403 insufficient_user_quota 账户余额不足，先充值。

参考资料

Section titled “参考资料”

以下资料查阅于 2026-09-28 至 2026-09-29：