【技术解读】Grok Build 官方文档带读：配置体系与自定义模型

前言：为什么配置文件体系对终端 AI Agent 重要

在图形化 IDE 的时代，配置几乎不需要你操心：模型选择、主题、密钥、目录规则，全部藏在「设置」按钮背后的弹窗里，鼠标点几下就完成了。但终端 AI Agent（比如 Grok Build 的 grok CLI）是完全不同的物种：它运行在 SSH 会话里、CI 流水线里、无头服务器上，甚至被别的程序当作子进程拉起。在这些环境里没有图形设置面板，唯一可靠的「操作系统」就是配置文件、环境变量和命令行参数——它们共同决定了 Agent 用什么模型思考、以什么风格显示、遵守哪些项目规则、能记住多少跨会话的知识。

这就是为什么「配置体系」值得被单独拿出来精读。它不是一堆枯燥的键值对，而是一套完整的优先级博弈模型：个人偏好、企业策略、项目约定、命令行临时指令之间如何分层、如何合并、谁说了算。理解这套模型，你就不会在「我改了配置为什么不生效」上浪费一整天。

Grok Build 是 xAI 推出的终端 AI 编码 Agent（grok CLI），使用 Rust 实现。官方文档将它的资料随二进制一起分发：每次启动时会把一份 user-guide 文档解压到 ~/.grok/docs/user-guide/，其中 26-config-reference.md 是 config.toml、managed_config.toml 与 requirements.toml 三份配置文件的完整字段清单，而 05-configuration.md、06-theming.md、11-custom-models.md、12-project-rules.md、13-memory.md 分别讲配置总览、主题、自定义模型、AGENTS.md 项目规则与跨会话记忆。本文即围绕这六份官方文档展开带读。

需要提前声明：技术文档演进很快，本文引用的字段与默认值均来自抓取时的官方仓库文档快照；如果你手头的版本不一致，一律「以当前版本官方文档为准」。文中所有配置示例都经过核对，没有编造的成分——这也是本系列文章一贯的底线。

你现在应该掌握了什么：终端 AI Agent 的配置为什么重要（无图形界面、多环境运行、程序化拉起）；Grok Build 官方文档的结构与存放位置（~/.grok/docs/user-guide/）；带读将覆盖的六份文档分别解决什么问题。

配置层级与优先级：一场「谁说了算」的博弈

Grok Build 最值得先理解的设计，是它的配置优先级模型。官方文档给出的解析顺序（高优先级在前）如下：

┌─────────────────────────────────────────────────────────────────┐
│             Grok Build 配置优先级（高 → 低）                       │
├─────────────────────────────────────────────────────────────────┤
│  1. CLI 命令行参数        --model / --sandbox / --yolo ...        │
│  2. 环境变量              XAI_API_KEY / GROK_MEMORY / GROK_THEME  │
│  3. requirements.toml / MDM   （组织强制层，夹住下面所有层）          │
│  4. GROK_CONFIG / GROK_CONFIG_PATH   （注入式 overlay）            │
│  5. config.toml          ~/.grok/config.toml（你的个人配置）        │
│  6. managed_config.toml  /etc/grok/...（企业下发默认值）            │
│  7. 内置默认值            编译进二进制的出厂设置                      │
└─────────────────────────────────────────────────────────────────┘
           合并方向（配置文件层内，低 → 高逐层覆盖）
   managed_config.toml → config.toml → GROK_CONFIG overlay
              → requirements.toml / MDM

先解释这张图。官方 05-configuration.md 明确指出：设置项按「高优先级优先」解析，第一梯队是命令行参数（比如 --yolo、--model、--sandbox），第二梯队是环境变量（比如 XAI_API_KEY、GROK_MEMORY），第三梯队是 requirements.toml / MDM 这种组织强制的层。而「配置文件层」内部，则从低到高合并：managed_config.toml → config.toml → GROK_CONFIG overlay → requirements.toml / MDM。

这句话读起来有点绕，我用大白话翻译一遍：命令行参数 > 环境变量 > 组织强制的 requirements > 临时注入的 overlay > 你的 config.toml > 企业下发的 managed_config > 出厂默认值。其中 requirements.toml 是最特殊的一层，官方称之为「clamp（钳制）」——它像一个夹子，把下面所有层的取值都夹在组织允许的范围内，包括你的 config.toml 和你临时注入的 overlay，谁也越不过去。

为了让三层配置文件「各司其职」，官方 26-config-reference.md 用一句话点破了本质：三份文件是不同的人写的。

选型逻辑也很清晰：想让使用者能自己调整的默认值，放进 managed_config.toml；绝不允许使用者改动的底线，放进 requirements.toml。值得注意的是 managed_config.toml 接受 config.toml 表格里的全部键，只有一个例外：features.remote_fetch 这条「托管值永远赢过开发者值」。而 requirements.toml 里甚至允许出现只属于它的键，比如 fail_closed——签名校验失败时是否拒绝启动（默认 false，即不带策略照常跑），以及 ui.disable_bypass_permissions_mode——把「总是放行」模式锁死。这些细节充分说明：Grok Build 的配置体系为「企业强制合规」留足了后门与闸门。

两层容易被忽略的「隐藏层」

除了上面三份文件，优先级图里还有两个值得单独讲的入口。其一是项目级 .grok/config.toml：它并不读取全部配置节，只接受 [mcp_servers]、[plugins]、[permission] 以及 [mcp] max_output_bytes 这几类（MCP 服务器、插件、权限规则天然适合跟仓库走）。如果你把 [models]、[ui] 写进项目级文件，Grok Build 根本不会加载它们——这正是很多人「改了没反应」的头号原因，后面踩坑章节还会展开。

其二是 GROK_CONFIG / GROK_CONFIG_PATH overlay，这是给「harness 或 ACP 客户端」这类外部程序准备的注入通道：不想写 config.toml、不想挪 $GROK_HOME，只想在拉起 grok agent stdio 时临时塞进一些设置？GROK_CONFIG 是一段内联 JSON，GROK_CONFIG_PATH 指向一个额外的 JSON/TOML 文件（按扩展名识别，.json 当 JSON，其余当 TOML），两者都设置时 GROK_CONFIG 胜出。overlay 是深合并在 config.toml 之上的：只覆盖它显式声明的键。比如官方示例里，想把默认推理强度调高：

GROK_CONFIG='{"models": {"default_reasoning_effort": "high"}}' grok agent stdio

必须强调两点安全设计：第一，overlay 被严格限制在一个白名单里（只允许 models、features、收窄的 toolset 与受限的 shell_environment_policy 过滤字段），其余表格一律在入口处被丢弃，因此它不是权限提升通道，不能替你执行命令、改认证策略或重定向网络流量；第二，即使落在白名单内的设置，也有一批安全闸门坚持只读磁盘上的原始层，不读 overlay。官方注释说得很直白：overlay 内容畸形时只记一条警告并回退到 GROK_CONFIG_PATH，空字符串按未设置处理。这套「注入友好、失败关闭」的哲学，与官方提到的 codex-acp 适配器里 CODEX_CONFIG 的做法一脉相承——Grok 是 ACP 原生的，所以 overlay 直接住在 Agent 自身里。

最后，官方 26-config-reference.md 给了完整的八层读取顺序（它的编号方式与 05 文档等价，只是把配置文件细分成了编译默认值、managed、用户 config、项目 config、overlay、requirements 等行），并且提示了终极调试手段：grok inspect 或 grok inspect --json 会列出实际生效的每一份文件与每一个值的来源。配置不生效时，先跑它，别瞎猜。

你现在应该掌握了什么：Grok Build 的七级优先级模型与配置文件层内「低到高」的合并方向；三份配置文件分别由谁写、谁能覆盖谁；项目级 .grok/config.toml 只认 MCP/插件/权限类配置；GROK_CONFIG overlay 的注入方式、白名单与安全边界；用 grok inspect 验证最终生效值。

主配置文件详解：config.toml 从入门到会用

主角登场。Grok Build 的主配置是 ~/.grok/config.toml（默认 $GROK_HOME 即 ~/.grok，可用 GROK_HOME 环境变量整体改道），格式是 TOML。官方文档给了一个非常省心的承诺：文件缺失时 Grok 直接使用内置默认值，所以你只需要写出想覆盖的键——不必像某些工具那样抄一份几百行的完整配置再删改。

TUI 里的 /settings 面板会把这些设置写回 config.toml，所以「手改文件」与「面板操作」殊途同归；反过来，你也完全可以在编辑器里直接改，两种方式都会在下次启动时生效。外观相关的细粒度样式则拆到了独立的 ~/.grok/pager.toml（稍后主题章节详述），日志、会话、密钥等各归其位。

常用字段一览

下面是官方 05-configuration.md 与 26-config-reference.md 中出场率最高的字段，整理成速查表（「以当前版本官方文档为准」）：

一份「加料版」示例配置（字段均来自官方文档示例，我加了注释方便理解）：

# ~/.grok/config.toml
[cli]
auto_update = true                  # 启动时检查更新

[models]
default = "grok-4.5"                # 新会话默认模型
web_search = "grok-4.5"             # 联网搜索工具用的模型
temperature = 0.7                   # 全局采样温度（每个模型未单独设置时兜底）
max_completion_tokens = 8192        # 单次响应最大 token 数
[ui]
theme = "tokyonight"                # 主题
simple_mode = true                  # readline 式输入编辑（false = vim 式）
vim_mode = false                    # 滚动区 vim 导航（默认关闭）
max_thoughts_width = 120            # 推理过程显示的最大宽度

[features]
telemetry = false                   # 关闭匿名遥测
codebase_indexing = true            # 代码图谱索引

[session]
auto_compact_threshold_percent = 85 # 上下文 85% 时自动压缩

[tools]
respect_gitignore = false           # 默认不跳过 gitignore 文件

其它值得知道的文件与目录

26-config-reference.md 与 05-configuration.md 都整理了 ~/.grok/ 下的完整文件地图，其中高频出现的有：auth.json（自动管理的登录凭据）、sessions/（按工作目录组织的持久化会话）、memory/（跨会话记忆文件与索引）、skills/（用户级技能定义）、plugins/（用户级插件）、agents/（用户级 Agent 定义）、lsp.json（LSP 服务器配置）、logs/（内部日志）。而项目内的 .grok/ 目录则装着随仓库走的版本：.grok/config.toml（仅 MCP/插件/权限，见上）、.grok/skills/、.grok/plugins/、.grok/agents/、.grok/hooks/、.grok/lsp.json、.grok/sandbox.toml（自定义沙箱档案），以及本文后面要讲的 AGENTS.md。

环境变量方面，除了贯穿全文的 XAI_API_KEY（来自 console.x.ai 的 API 密钥）之外，官方环境变量参考还列出：GROK_HOME（配置目录改道）、GROK_MEMORY（记忆开关）、GROK_SUBAGENTS（子代理开关）、GROK_WORKFLOWS（后台工作流开关）、GROK_WEB_FETCH（网页抓取工具开关）、GROK_SANDBOX（沙箱档案）、GROK_LOG_FILE 与 RUST_LOG（排障日志）、GROK_TELEMETRY_ENABLED（遥测）、GROK_DEPLOYMENT_KEY（企业管理密钥）等。想验证当前到底哪些文件、哪些值生效，依旧是那句口诀：grok inspect。

你现在应该掌握了什么：主配置文件的位置（~/.grok/config.toml）、格式（TOML）与「只写覆盖项」的哲学；[cli]/[models]/[ui]/[features]/[session]/[tools] 各节高频字段的含义与默认值；~/.grok/ 与项目 .grok/ 两套文件系统的分工；常见环境变量的作用。

主题定制：让 TUI 长成你喜欢的样子

终端程序也要讲审美。Grok Build 的 TUI 颜色全部来自一套中央主题系统，官方 06-theming.md 明确说：你可以运行时切换主题、跟随系统明暗外观，还能通过配置文件微调滚动区布局、动画与各类块（block）的样式。

先看内置主题。Grok 自带五个主题加一个 auto 选项（别名 system），主题名大小写不敏感：

切换主题有三条路：TUI 里敲 /theme（别名 /t）打开选择器，方向键上下移动时实时预览，回车应用并保存、Esc 还原；也可以直接 /theme tokyonight 点名切换，甚至只敲一个光杆 /theme 让它在主题间轮转。想持久化则写进配置：

# ~/.grok/config.toml
[ui]
theme = "tokyonight"

更省心的是自动跟随系统外观：theme = "auto"。默认深色模式映射到 GrokNight、浅色映射到 GrokDay，你可以用 auto_dark_theme 与 auto_light_theme 改写这对映射。检测机制因平台而异：macOS 读 AppleInterfaceStyle，Linux 走 XDG Desktop Portal（org.freedesktop.appearance.color-scheme），Windows 读系统个性化注册表；SSH/tmux/无头环境则依次尝试 GROK_APPEARANCE（或 LC_GROK_APPEARANCE）、COLORFGBG、启动期 OSC 11 背景查询。运行中 Grok 每 5 秒轮询一次桌面 API 与环境提示，所以本机切换明暗模式几秒内就会生效，无需重启。不写文件强制指定主题也支持：GROK_THEME（或 LC_GROK_THEME）环境变量。

有三个容易踩的细节值得提前说。第一，minimal 模式没有主题：--minimal 渲染时使用终端自身的 16 色 ANSI 调色板（就是 git、ls 用的那套），theme 设置对它无效，/theme 在 minimal 模式下也不可用——这是为了在任何明暗终端档案下都保持可读，刻意不做极性检测。第二，颜色能力检测与量化：启动时 Grok 检测终端是 truecolor、256 色还是 16 色，然后把主题里所有 RGB 颜色量化到对应能力；TokyoNight、RosePineMoon、OscuraMidnight 这类「有性格」的底色在量化后会走样，所以非真彩色终端的选择器里直接不显示它们。设置 NO_COLOR 则彻底变单色。想确认当前终端能力，跑 /doctor。第三，语法高亮文件是内置的：三个 .tmTheme 文件编译进二进制，随主题自动选用，你不能替换成自己的。

还想更精细？pager.toml 登场。官方 06-theming.md 的后半部分展示了这块「深水区」：[scrollback.layout] 调视口内外边距与块间距；[scrollback.scrollbar] 控制滚动条显隐与配色；各 [scrollback.blocks.*] 节分别定制编辑 diff、思考块、工具调用、shell 执行块、用户提示块的样式；[animation] 控制帧率与波浪动画；[terminal] alt_screen 决定是否进入全屏 alt-screen。主题内部是一整套颜色槽位（color slots），从 bg_base、accent_user、accent_error 到 diff 配色、markdown 标题色 md_heading_h1…md_heading_h6，全部由主题系统统一管理并自动量化。另外 /compact-mode 可以切换紧凑模式（去掉上下留白、水平内边距压到 1 列），状态持久化在 [ui].compact_mode，小屏幕上非常实用。

你现在应该掌握了什么：五个内置主题与 auto 的配置名、切换主题的三条途径（/theme、config.toml、环境变量）；自动跟随系统的检测机制与映射覆盖；minimal 模式无主题、量化机制、NO_COLOR、/doctor 这些边界行为；pager.toml 能做多深的定制。

自定义模型接入：本地模型、OpenAI 兼容端点与模型切换

如果说主题是「皮」，那模型体系就是 Grok Build 的「心脏」。官方 11-custom-models.md 开篇就交代了默认形态：默认情况下 Grok 使用官方托管的模型（文档原文 "models hosted by SpaceXAI"，即 xAI 的模型托管侧），新会话默认从 grok-4.5 起步，官方模型无需任何配置，用 grok login 或 API 密钥完成认证即可开聊。想看看当前到底有哪些模型可用？一行命令：

grok models

这个列表会同时包含内置模型和你自定义的模型——它是排障时的第一求助对象。

模型切换的四种姿势

官方文档给出了四条切换路径，从临时到持久依次是：

1. 命令行参数：grok -p "你好" -m grok-4.6，headless 模式下最常用；
2. TUI 斜杠命令：会话中途敲 /model grok-4.6（别名 /m），立刻生效；
3. 模型选择器：在滚动区按 Ctrl+M 弹出选择器，列出所有内置与自定义模型，单键切换（注意：焦点在输入框时 Ctrl+M 是多行输入开关，不想离开输入框就用 /model）；
4. 配置默认值：在 config.toml 里写 [models] default = "grok-4.5"，让新会话固定用它。

企业场景还有第五条路：管理员可以在签名的 requirements.toml 里用 [models] default + allowed_models 钉死可选择集合——这个列表会整体替换用户侧的 allowed_models（不是取并集），并且按「模型 id」匹配而非用户起的目录键，所以 /model、Ctrl+M、-m 都拿不到名单外的模型。想限制自家团队误用未审批模型时，这是官方钦定的闸门。

三大 API 后端与自定义模型写法

接入第三方或自托管模型的核心概念是 api_backend：Grok 支持三种线上协议，在 [model.*] 里显式指定：

自定义模型的完整形态写在 config.toml 的 [model.<名字>] 节里。字段名与官方示例完全对齐：

[model.my-model]
model = "model-id"                        # 发给 API 的模型标识
base_url = "https://api.example.com/v1"   # OpenAI 兼容端点
name = "Display Name"                     # 模型选择器里显示的名字
description = "Model description"         # 可选描述
api_key = "sk-..."                        # 该提供商的密钥（可选，见凭据解析）
env_key = "XAI_API_KEY"                   # 存密钥的环境变量（可选；字符串或数组）
api_backend = "chat_completions"          # chat_completions | responses | messages
temperature = 0.7                         # 采样温度
top_p = 0.95                              # 核采样参数
max_completion_tokens = 8192              # 单次响应最大 token
context_window = 128000                   # 上下文窗口（驱动自动压缩时机）
extra_headers = { "x-api-key" = "sk-..." }   # 附加请求头，逐字发送
query_params = { api-version = "2026-07-22" } # 追加到每个请求 URL 的查询参数
env_http_headers = { "X-Tenant" = "TENANT_TOKEN" } # 从环境变量取值的请求头

密钥解析有一套固定顺序（官方原文）：先看 [model.*] 里的 api_key 字段；没有再看 env_key 指向的环境变量（支持字符串或数组，取第一个「已设置且非空」的——数组写法方便 SSH 场景同时声明 ANTHROPIC_AUTH_TOKEN 与 LC_ANTHROPIC_AUTH_TOKEN）；再没有就回落到你 grok login 的会话令牌；最后兜底全局的 XAI_API_KEY。安全建议贯穿始终：官方在配置参考里反复提醒 优先 env_key 而不是内联 api_key，别把密钥写进会进 git 仓库的共享配置里。

两个非常容易踩的坑，官方文档都单独标了出来。其一，context_window 决定自动压缩的触发时机：覆盖一个官方已知模型时 Grok 会继承它原有的窗口；但定义一个全新模型而省略 context_window 时，默认值是 200,000 token——如果你的真实端点窗口远小于它，会话会在模型侧被截断而 Grok 浑然不知。其二，query_params 会被存进会话文件，官方明令「不要把秘密放进去」，需要每请求带秘密头时用 env_http_headers——它在构建客户端时读取环境变量、只进请求头、永不落盘，且解析出的值会覆盖同名 extra_headers。此外还有全局共享的写法：[models] 下可以设全局默认采样参数与 extra_headers（适合打 X-Request-Tags 这类成本归属标签），以及 [model_providers.<id>] 这种把 query_params/env_http_headers/extra_headers 抽出来供多个模型继承的「提供商」块。

覆盖内置模型与真实接入示例

覆盖内置模型只需要写想改的字段，未写字段自动继承官方默认（含正确的 base_url）。优先级是：你的 [model.*] 配置最高 > 从远端 /v1/models 预取的模型 > 硬编码默认值最低。官方给出的典型示例：

# 只覆盖某个内置模型的 API 密钥
[model.grok-4.6]
api_key = "my-api-key"

# 或同时改温度与密钥
[model.grok-4.6]
temperature = 0.5
api_key = "sk-custom"

接入各家模型的官方示例，我挑三个最有代表性的。OpenAI 系最简单，api_backend 省略即默认 Chat Completions：

[model.gpt-4o]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
name = "GPT-4o"
env_key = "OPENAI_API_KEY"

Anthropic 系则必须显式 api_backend = "messages"，并且因为 Anthropic 用 x-api-key 头而非 Authorization 头认证，密钥要走 extra_headers 逐字发送，还要带上 anthropic-version：

[model.claude-opus]
model = "claude-opus-4-6"
base_url = "https://api.anthropic.com/v1"
name = "Claude Opus 4.6"
api_backend = "messages"
context_window = 200000
extra_headers = { "x-api-key" = "sk-ant-...", "anthropic-version" = "2023-06-01" }

本地模型最典型的姿势是 Ollama——它原生暴露 OpenAI 兼容的 /v1 端点，所以配置极其干净：

[model.ollama-codellama]
model = "codellama"
base_url = "http://localhost:11434/v1"
name = "CodeLlama (Ollama)"

前提是 Ollama 在跑（ollama serve）且模型已拉取（ollama pull codellama）。任意实现了 OpenAI Chat Completions 或 Responses 协议的自建服务同理，base_url 指向自己的监听地址即可，比如 http://localhost:8080/v1。官方还给了 Together AI 的例子（base_url = "https://api.together.xyz/v1" + env_key = "TOGETHER_API_KEY"），路径完全一致，套路就是「抄 OpenAI 兼容端点的模板 + 换 base_url + 换密钥来源」。

如果你整个环境都走自建网关（比如公司代理），还有一条「全局改道」的路：环境变量 GROK_MODELS_BASE_URL（必填，推理基址，Grok 会从 {base_url}/models 拉模型清单）+ XAI_API_KEY（必填），可选 GROK_MODELS_LIST_URL 覆盖清单 URL；配置文件等价写法是 [endpoints] models_base_url = "..."，此时各 [model.*] 节可以省略 base_url（自动继承端点配置）。一个行为变化要记牢：一旦设置了 models_base_url，认证就切到 API key 模式（Authorization: Bearer）而不是会话登录模式——不需要 grok login，有 key 就行。web_search 工具用的模型独立配置：[models] web_search = "grok-4.5" 或环境变量 GROK_WEB_SEARCH_MODEL；指向自定义模型时还需要对应的 [model.*] 条目，需要服务端（后端）搜索则给模型加 supports_backend_search = true。

最后是官方文档标配的排障三板斧：模型找不到（Model Not Found）时先 grok models 看清单，再检查 config.toml 里 [model.*] 表名有没有拼错；连接报错时直接用 curl 验证端点可达性；要深挖就开调试日志：RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok，然后在日志里 grep model 或 sampling 追踪模型选择与 API 调用全过程。

你现在应该掌握了什么：模型切换的四条路径与组织级 allowed_models 钉死机制；三种 api_backend 协议与 [model.*] 全部常用字段；密钥解析的四级顺序与「别内联密钥、别把秘密放 query_params」的安全红线；覆盖内置模型、接入 OpenAI/Anthropic/Ollama/任意 OpenAI 兼容端点的完整配置写法；models_base_url 全局改道与认证模式切换；排障三板斧。

AGENTS.md 项目规则：把团队约定写进仓库

模型再聪明，也不知道你的仓库「用 2 空格缩进还是 tab、提交信息要不要 conventional commits、接口文档放哪个目录」。这些项目级约定如果每次都靠口头叮嘱，既低效又不可靠。Grok Build 的解法是 AGENTS.md 项目规则：在仓库里放 Markdown 文件，Grok 启动时自动读取并加入上下文，之后在这个目录树里的每一次交互都遵守它。官方 12-project-rules.md 称其为「教 Grok 了解项目约定的主要机制——无需每个会话重复陈述」。

文件名、发现顺序与优先级

每个目录里，Grok 按固定顺序检查这些文件名：Agents.md → Claude.md → CLAUDE.md → CLAUDE.local.md → AGENT.md → AGENTS.md。注意它不是「找到第一个就停」——同一目录下所有匹配文件全部加载，比如同时存在 AGENTS.md 和 CLAUDE.md 就两个都进上下文；大小写不敏感的文件系统上（如 macOS）名字解析到同一文件时会去重。Claude.md/CLAUDE.md/CLAUDE.local.md 的存在是为了兼容 Claude Code 工作流：Claude 兼容默认开启时，Grok 还会扫你家目录的 ~/.claude/ 与各级目录下的 .claude/CLAUDE.md；Cursor 兼容同样默认开启，扫 ~/.cursor/。这些兼容开关在 [compat.claude]、[compat.cursor] 下逐项可控（skills/rules/agents/mcps/hooks/sessions 各有独立开关，全部默认 true）。

发现顺序三层递进：先加载家目录规则（$GROK_HOME/rules/，默认 ~/.grok/rules/，始终扫描，另有 ~/.claude/rules/、~/.cursor/rules/ 受兼容开关控制）；若在 git 仓库内，再从仓库根目录到当前目录逐级扫描每层目录里的规则文件；若不在 git 仓库内，则只扫当前工作目录。除了顶层命名文件，还有「规则目录」机制：每一层目录下的 .grok/rules/（始终扫描）、.claude/rules/、.cursor/rules/ 里的所有 *.md 都会被加载。加自定义规则目录也行：[paths] extra_rule_dirs = [...]。

优先级规则一句话：越深的文件越靠后进入上下文，冲突时越深者胜。官方示例给得很直观——仓库根 AGENTS.md 写「用 styled-components」，但 components/AGENTS.md 写「用 CSS modules」，则后者赢。加载时机也有讲究：会话开始时自动加载「仓库根到当前目录」这组文件；之后如果 Grok 读、列、编辑了初始集合之外目录的文件，它会探测那里是否存在项目规则文件、记下路径并在任务相关时读取——也就是说你 cd 到深层目录干活，规则也能跟上。

内容建议与作用域

规则文件里放什么？官方给了五类模板：编码规范（「新代码一律 TypeScript；默认 const，只有需要重赋值才用 let；行宽 100」）、构建与测试指令（「提交前跑 npm test；构建必须零 TS 报错」）、风格指南（「遵循 Airbnb 风格；2 空格缩进」）、PR 与提交要求（「提交信息用 conventional commits；PR 至少一人批准后合入」）、架构说明（「API 路由放 src/routes/，业务逻辑放 src/services/，禁止反向 import」）。模板代码长这样：

# Coding Standards
- Use TypeScript for all new code
- Prefer functional components with hooks over class components
- Use `const` by default; only use `let` when reassignment is needed
- Maximum line length: 100 characters

AGENTS.md 天然支持按子目录作用域化：文件只管辖以它所在目录为根的整棵子树。大型 monorepo 里，根放全仓规则，packages/frontend/AGENTS.md 写「用 React、CSS modules」，packages/backend/AGENTS.md 写「用 Express、遵循 REST 约定」，各司其职互不干扰。官方最后给出了七条最佳实践，精华是：最重要的全仓规则放根目录；指令要具体（「用 TypeScript」好过「用现代 JavaScript」）；保持简短（长规则更容易被忽略，且每个文件都消耗上下文）；规则入版本库让全团队受益，个人覆盖放 ~/.grok/；别把 AGENTS.md 写成 README 的复制品——它该装可执行指令，文档链接外置；规则要随项目演进定期评审更新。

几个容易忽略的细节：规则文件没有大小上限、不会被截断，但会实打实吃掉上下文，所以务必精炼；.gitignore 忽略的文件在发现阶段被跳过——想保留个人覆盖又不提交仓库，就把 CLAUDE.local.md 加进 .gitignore；顶层只认那六个固定文件名，AGENTS.local.md、notes.md 这类自定义名字不会被发现（规则目录里的 *.md 则不受名字限制）。如果只想临时加几条规则而不改任何文件，用 grok --rules "Always use TypeScript..."（别名 --append-system-prompt，内容会被包进 <human_rules> 块追加到默认系统提示词之后）；想彻底替换系统提示词则用 --system-prompt-override（别名 --system-prompt，原样使用，跳过默认提示词与 --rules）。最后，.grok/ 项目目录里还有 config.toml、skills/、plugins/、agents/、hooks/、lsp.json 等项目级资产，配合 AGENTS.md 构成完整的「仓库随身配置」；而验证一切是否加载成功，依旧是 grok inspect——它会列出找到的每个规则文件及其路径和大致 token 数。

你现在应该掌握了什么：AGENTS.md 的六个候选文件名与「全部加载」策略；家目录→仓库根→当前目录的发现顺序与「越深越优先」的冲突规则；规则目录（.grok/rules/ 等）与 Claude/Cursor 兼容扫描；该写什么、如何按子目录作用域化；--rules 与 --system-prompt-override 的差别；gitignore 过滤与用 grok inspect 验证加载。

Memory 机制：让 Agent 拥有跨会话的长期记忆

人类程序员跨项目、跨周工作，靠的是大脑记忆；终端 AI Agent 的每一次会话默认都是「失忆」的——模型对上一个会话一无所知。Grok Build 的 Memory（跨会话记忆）机制就是来补这块短板的。官方 13-memory.md 给出的能力清单非常诱人：回忆你上次讲过的项目约定、复用上次奏效的调试步骤、把架构决策带到未来的会话、不再重复提问早已有答案的问题。需要立刻认清的现实是：Memory 目前仍是实验特性，默认关闭，想要它得自己开。

开启方式与优先级

开启记忆有三条路，外加一条强制关闭的路。环境变量方式适合临时体验：export GROK_MEMORY=1 && grok；持久方式写进 ~/.grok/config.toml：

# ~/.grok/config.toml
[memory]
enabled = true

会话中途也能临时开关：/memory on、/memory off——注意它是会话级开关，不会写回 config.toml，关掉只是移除记忆工具访问权，磁盘文件原样保留；在 /memory 弹窗里按 t 也能切换。想对某个进程强制禁用（哪怕 TOML 或远程设置开着）：export GROK_MEMORY=0。官方给的五级优先级值得背下来：隐藏的废弃兼容标志 > GROK_MEMORY 环境变量 > 生效 TOML 里的 [memory] 节 > 托管远程设置 > 默认关闭。这条链也解释了「为什么我明明在设置里开了却不起作用」——八成是有个环境变量或者兼容标志压在上面。

存储布局与检索原理

记忆本质上是 ~/.grok/memory/ 下的一堆 Markdown 文件，外加一个 SQLite 索引。文件按作用域分三层：

每个工作区目录名末尾的短哈希来自仓库身份：目录是带 origin 远程的 git 仓库时，身份取 org/repo 形式的 origin；否则取目录路径。妙处在于：同一仓库的克隆与 worktree 共享同一个 origin，所以它们共享同一份记忆目录——换机器克隆同一仓库，记忆也跟着走。SQLite 索引支撑检索：FTS5 负责默认的全文关键词匹配，vec0 在配置了 embedding 模型后提供向量语义检索（embedding 模型默认未设置，所以开箱即用的是纯全文模式）。

记忆从哪来：自动保存、/flush 与 /dream

记忆有三条「进货渠道」。第一是会话结束自动保存：Grok 会把结构化的元数据摘要（消息条数、最多五个主题、UTC 时间）写进当天的会话日志——全程只用会话元数据、不调 LLM、零额外延迟；太琐碎的会话（少于三个实质提示，或用户文本不足 50 字节）会跳过。注意摘要不记录工具用法、文件路径或 shell 命令，想保存这些富内容得靠 /flush。第二是 /flush 命令：它触发一次 LLM 生成的「当前会话最重要内容」摘要，写入带日期的会话日志并进入索引。官方建议的 flush 时机：压缩（compaction）丢弃旧对话轮次之前、一段高产的排障结束之后、发现了重要模式或约定之时。第三是 /dream 自动整理：把散落的记忆碎片合并成有条理、去重后的知识库；它也会自动运行，默认门槛是距上次整理至少 24 小时且积累了至少 5 个会话（[memory.dream] 下 min_hours、min_sessions、check_interval_secs 可调）。

日常使用则是自然语言交互：说「remember to always open PR links after pushing」或敲 /remember，Grok 会把笔记追加到工作区或全局的 MEMORY.md，先弹审核面板、确认后才落盘，然后回你一句 Memory saved to ~/.grok/memory/MEMORY.md；「forget the snake_case convention」是尽力而为的删除，想确保删干净就自己编辑 ~/.grok/memory/ 下的文件（在 /memory 浏览器里按 y 可以复制文件路径）；问「what do you remember?」则触发全库检索并按来源分组汇报。文件被外部编辑也没关系：默认开启的文件监视器会在下次检索时自动重索引变更与删除。/memory 弹窗本身是个分栏浏览器，左侧文件列表（按全局/工作区/会话分组），右侧只读预览，支持 ↑/↓（或 j/k）移动、/ 过滤、y 复制路径、x 删除会话文件（连按确认）、t 开关记忆、Ctrl+F 全屏、Esc 关闭——只允许删会话文件，全局与工作区 MEMORY.md 动不得。

记忆如何影响会话与检索打分

记忆不是摆设，它真的会进提示词。首轮注入：每个新会话的第一轮，Grok 自动检索与当前项目相关的记忆并注入为上下文——这意味着如果你在开启记忆之前就启动了会话，这个会话里是看不到记忆的，官方排障建议直接 /new 开新会话。压缩之后：自动压缩丢掉的上下文，会再检索一次记忆来捞回相关内容。两个门槛都可调：[memory.initial_injection] enabled（默认 true）与 min_score = 0.9。

检索打分机制相当讲究。配置了 embedding 模型后，向量相似度权重 0.7 + BM25 文本相似度权重 0.3，结果按最低分阈值过滤（min_score 默认 0.7）；工作区/会话/全局三类来源各有权重乘数（默认都是 1.0，可在 [memory.search.source_weights] 调整）；会话记忆带时间衰减（half_life_days = 30，分数每 30 天减半——全局与工作区记忆因为是精选的长期知识而豁免）；还有 MMR（最大边际相关）重排去冗余（lambda = 0.7，越接近 0 越多样、越接近 1 越纯相关）。老会话记忆还会被贴上「可能过时」的 staleness 提醒，越老提醒越强，防止你照着过时结论干活。命令行侧，grok memory clear 可以清工作区（默认）/全局（--global）/全清（--all），加 --yes 跳过确认。

排障速查

官方 13-memory.md 的 Troubleshooting 部分非常实用：记忆完全不工作，先 grok inspect 确认生效配置，再查 GROK_MEMORY 与 TOML 里 [memory] enabled，最后警惕 GROK_MEMORY=0 或废弃兼容标志在作祟；记忆不进会话，多半是会话开得太早——/new 重开；想看原始文件，ls ~/.grok/memory/ 或 $EDITOR ~/.grok/memory/MEMORY.md 直接编辑；要深挖就 RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok 后在日志里 grep memory。

你现在应该掌握了什么：Memory 是默认关闭的实验特性；四种开关途径与五级优先级；~/.grok/memory/ 的三层文件布局与 SQLite 双索引（FTS5 + vec0）；自动保存、/flush、/dream 三条记忆来源；/remember、自然语言、/memory 浏览器、直接编辑四种读写方式；首轮注入与压缩后检索、打分权重与时间衰减；grok memory clear 与常见排障手段。

踩坑经验：那些「改了不生效」的真实场景

文档读得再细，不如踩坑记得牢。以下场景全部基于官方文档明文描述的行为推导而来，用 ❌/✅ 对照呈现，方便你直接对号入座。

场景一：配置文件明明改了，行为毫无变化

❌ 把 [models]、[ui]、[features] 写进了项目里的 .grok/config.toml，指望它生效。官方明文：项目级文件只接受 [mcp_servers]、[plugins]、[permission] 与 [mcp] max_output_bytes，其它节只从 ~/.grok/config.toml 加载——你改了个寂寞。
✅ 个人级设置一律写 ~/.grok/config.toml；项目级文件只放 MCP 服务器、插件与权限规则。

❌ 改了 config.toml 里的 [ui] theme，但 shell 里早就 export GROK_THEME=tokyonight，还开了 --minimal。环境变量压过配置文件，minimal 模式又压根不吃主题设置——三重叠加，自然纹丝不动。
✅ 记住优先级链：CLI 参数 > 环境变量 > requirements > overlay > config.toml > managed > 默认值。排查时先 env | grep GROK，再 grok inspect 看每个值的最终来源，一步到位。

❌ 修改后不重启、不重开会话，直接在当前会话里验证。很多设置在会话启动时读一次，之后只在特定时机（如主题切换、下次发送）生效。
✅ 改了配置先 /new 重开一个会话再验证；涉及主题的外观类改动看是否即时生效，拿不准就重启 grok。

场景二：模型切换失败

❌ 在 config.toml 里写 [models] default = "my-fancy-model"，但 [model.my-fancy-model] 节名拼错（或压根没建）。Grok 报 Model Not Found，你却盯着 default 行发呆。
✅ 先 grok models 看当前可用清单里到底有没有这个名字；再逐字核对 [model.*] 的表名、model 字段与 base_url。官方排障第一步就是这两条。

❌ 团队环境里 -m 一个模型被拒。这不是你配置写错了，而是管理员的 requirements.toml 用 allowed_models 钉死了可选择集合，并且按模型 id 匹配、整体替换用户白名单。
✅ 先确认组织策略：grok inspect 会列出贡献了哪些 requirements 文件；名单外的模型找管理员，而不是继续折腾本地配置。

❌ 自定义端点一直报 401/403。自定义 base_url 或 models_base_url 后认证切到 API key 模式，你却没设 api_key/env_key/XAI_API_KEY；或者你接的是 Anthropic 系端点却走了默认的 chat_completions 后端、把密钥放在 Authorization 头里。
✅ 记住三条：凭据解析顺序是 api_key 字段 > env_key 变量 > 登录会话令牌 > XAI_API_KEY；Anthropic 用 api_backend = "messages" + extra_headers 里的 x-api-key；先 curl 一下 {base_url}/models 验证端点与密钥本身可用，再用 RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok 看请求细节。

❌ 模型能对话，但上下文老是被截断、自动压缩时机诡异。自定义模型漏写了 context_window——官方默认按 200,000 token 算，你的端点实际窗口可能只有 32k，Grok 自然「太晚才压缩」。
✅ 自定义新模型时显式设置 context_window 匹配真实端点；覆盖官方已知模型则不用管（自动继承）。

场景三：AGENTS.md 与记忆「不灵」

❌ 仓库里放了 AGENTS.md，规则一条没执行。可能原因：文件被 .gitignore 忽略了（发现阶段直接跳过）；目录不在 git 仓库里而你从子目录启动（非 git 场景只扫当前工作目录）；文件名写成了 AGENTS.local.md 这类不被识别的自定义名（顶层只认那六个固定名字）。
✅ 用 grok inspect 确认文件是否被加载及其 token 数；规则文件放仓库根与相关子目录、commit 进版本库、别 gitignore；个人临时规则用 --rules。

❌ Memory 开了，也 remember 了一堆，新会话却什么都不记得。多半是：会话在开启记忆之前就启动了——首轮注入只发生在会话第一轮；或者有个 GROK_MEMORY=0 正压着你的 TOML 设置。
✅ 开记忆后 /new 重开会话；/memory on 确认状态；查 env | grep GROK_MEMORY；用 grok memory//memory 确认文件真实存在。

❌ 想让模型记住某次排障的完整推理过程，只靠会话结束的自动摘要——它只存元数据（消息数、主题、时间），不记录工具用法、文件路径与 shell 命令。
✅ 关键产出用 /flush 显式落盘（LLM 生成的富摘要），压缩前、长排障后各来一发；定期 /dream 整理碎片。

你现在应该掌握了什么：三组高频踩坑场景的根因——项目级与用户级配置文件分工错位、环境变量/CLI 参数压过配置文件、minimal 模式不吃主题；模型切换失败的四大原因（表名拼错、组织钉死名单、认证模式切换、漏设 context_window）；AGENTS.md 不加载的三种文件系统级原因；Memory 的会话开启时机与 GROK_MEMORY=0 覆盖问题；以及贯穿一切的终极调试咒语——grok inspect。

总结

把六份官方文档串起来，Grok Build 的配置哲学其实可以浓缩成几句话：

1. 配置是分层博弈，不是单点覆盖。命令行参数 > 环境变量 > requirements.toml/MDM > GROK_CONFIG overlay > config.toml > managed_config.toml > 内置默认值；配置文件层内部从低到高合并。理解层级，胜过背诵一百个键。
2. 三份配置文件各为其主。config.toml 是开发者的个人偏好，managed_config.toml 是管理员下发的「可调默认值」，requirements.toml 是签名钉死的「不可调底线」——选文件就是在选「谁说了算」。
3. 模型体系围绕 OpenAI 兼容协议展开。默认 chat_completions，可选 responses 与 Anthropic messages；自定义模型就是 [model.*] 一节配置，密钥优先走 env_key，秘密绝不进 query_params，新模型务必显式声明 context_window。
4. 约定写进仓库，记忆留在本机。AGENTS.md 按「仓库根 → 当前目录、越深越优先」自动加载，规则要短、要具体、要入版本库；Memory 默认关闭、按需开启，靠自动保存、/flush、/dream 三条渠道沉淀，首轮注入让新会话「自带前情提要」。
5. 一切以 grok inspect 为准。它列出每份生效文件与每个值的来源，是配置不生效、模型切换失败、记忆不工作时的第一诊断工具。
6. 文档会演进，版本会漂移。本文所有字段与默认值均出自抓取时的官方仓库文档；升级后如有出入，以当前版本官方文档为准。

你现在应该掌握了什么：配置体系的全景图——层级博弈模型、三文件分工、模型接入、主题、项目规则、记忆机制与排障手段已全部串成一条可执行的认知链；下次遇到「终端 AI Agent 配置不生效」时，你知道先看哪一层、先跑哪条命令。

参考资料

本系列文章坚持「一手资料优先」，以下为撰写本文实际抓取并核对的官方文档（base：xai-org/grok-build 仓库 crates/codegen/xai-grok-pager/docs/user-guide/）：

• 05-configuration.md（配置总览：优先级、config.toml、环境变量、文件位置）
• 06-theming.md（主题与外观定制：内置主题、auto 主题、pager.toml、颜色槽位）
• 11-custom-models.md（自定义模型：选择、API 后端、Provider 示例、排障）
• 26-config-reference.md（配置参考：三份文件的完整字段清单、pin 机制、inspect）
• 12-project-rules.md（项目规则：AGENTS.md 发现顺序、作用域、最佳实践）
• 13-memory.md（跨会话记忆：开关、存储、检索打分、/flush 与 /dream）

官方仓库：https://github.com/xai-org/grok-build（README 与本系列文档的一手来源）；在线文档与发布版本如有更新，请以 https://docs.x.ai/build 对应章节为准。