变量	默认值	描述
`GROK_HOME`	`~/.grok`	Config、auth、sessions、skills、plugins 和 logs 的 home 目录。
`XAI_API_KEY`	—	不使用 browser/session login 时使用的 API key（CI 和 headless）。

模型与更新

变量	默认值	描述
`GROK_DEFAULT_MODEL`	catalog / config	Session 默认模型（与 `-m` / `--model` 含义相同）。
`GROK_WEB_SEARCH_MODEL`	built-in	`web_search` 工具使用的模型。
`GROK_MODELS_BASE_URL`	—	自定义 inference base URL；模型列表来自 `{base}/models`。
`GROK_MODELS_LIST_URL`	`{GROK_MODELS_BASE_URL}/models`	模型列表 URL 与默认值不同时进行覆盖。
`GROK_XAI_API_BASE_URL`	`https://api.x.ai/v1`	API-key auth 使用的 xAI API base。
`GROK_DISABLE_AUTOUPDATER`	unset（允许更新）	设置后禁止当前 process 的 auto-updater（CI/containers）。

工具、sandbox 与功能

变量	默认值	描述
`GROK_SANDBOX`	`off`	Sandbox profile：`off`、`workspace`、`read-only`、`strict`（或自定义 profile 名称）。与 `--sandbox` 相同。
`GROK_SANDBOX_AUTO_ALLOW_BASH`	`0`	在活动 sandbox 中自动允许 bash（`1`/`0`）。
`GROK_RESPECT_GITIGNORE`	未设置时使用 config	强制 search/read tools 按 gitignore 过滤（`1`/`0`）；覆盖 `[tools] respect_gitignore`。
`GROK_WEB_FETCH`	`0`	启用 `web_fetch` 工具（`1`/`0`）。出于安全考虑默认关闭。
`GROK_WEB_FETCH_PROXY`	—	`web_fetch` 的 egress proxy URL。
`GROK_MEMORY`	`0`	启用 cross-session memory（`1`/`0`）。
`GROK_SUBAGENTS`	`0`	启用 subagents / task 工具（`1`/`0`）。
`GROK_AGENT`	`grok-build`	内置 Agent 名称、profile 或 Agent 定义的绝对路径。
`GROK_WRITE_FILE`	`1`	禁用 `write` 工具时使用 `0`（read-only sessions）。
`GROK_TOOL_SEARCH`	`1`	为大型 toolset 按需发现 MCP 工具（`1`/`0`）。
`GROK_LSP_TOOLS`	`0`	启用 LSP code-intel 工具（`1`/`0`）。

UI 与外观

变量	默认值	描述
`GROK_THEME`	built-in	颜色主题。
`GROK_SHOW_THINKING_BLOCKS`	`1`	在 TUI 中显示 thinking/reasoning blocks（`1`/`0`）。
`GROK_GROUP_TOOL_VERBS`	`1`	折叠连续的 read/search/list 工具行（`1`/`0`）。
`GROK_COLLAPSED_EDIT_BLOCKS`	`0`	将 edits 折叠为单行 `+N/-M` 摘要（`1`/`0`）。
`GROK_PROMPT_SUGGESTIONS`	`1`	每个 turn 后显示下一 prompt 的 ghost text（`1`/`0`）。
`GROK_SCROLL_SPEED`	`50`	Mouse/trackpad 滚动速度（`1`–`100`）。
`GROK_SCROLL_MODE`	`auto`	滚动输入：`auto`、`wheel` 或 `trackpad`。
`GROK_SCROLL_LINES`	未设置时使用 config	每个滚动 tick 的行数（`1`–`10`）。
`GROK_INVERT_SCROLL`	`0`	反转垂直滚动方向（`1`/`0`）。
`GROK_DEFAULT_SELECTED_PERMISSION`	`always_allow_all_sessions`	第一次 permission prompt 中预先选择的行。
`GROK_REMEMBER_TOOL_APPROVALS`	`0`	显示每个工具的“Always allow …”选项（`1`/`0`）。
`GROK_MOUSE_REPORTING_TOGGLE`	`0`	Scrollback 中的 `Ctrl+R` 切换 terminal mouse capture（`1`/`0`）。
`GROK_DISPLAY_REFRESH_AUTO_CADENCE`	`0`	让 stream/scroll cadence 与 display refresh rate 匹配（`1`/`0`）。

MCP、logging 与 proxy

变量	默认值	描述
`GROK_MCP_STARTUP_TIMEOUT_SECS`	`30`	全局 MCP startup handshake timeout，单位为秒。每个 server 的 `startup_timeout_sec` 仍优先。
`MCP_TIMEOUT`	same stack	Claude-compatible MCP startup timeout，单位为毫秒（在 `GROK_MCP_STARTUP_TIMEOUT_SECS` 之前检查）。
`GROK_LOG_FILE`	—	将 logs 写入此路径（TUI 捕获 stderr 时很有用）。
`RUST_LOG`	—	`GROK_LOG_FILE` 和 headless stderr 的 log filter（例如 `debug`）。
`GROK_CRASH_HANDLER`	`0`	Panic 时在 `$GROK_HOME/crash/` 下写入报告（`1`/`0`）。
`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`	system	Outbound traffic 使用的标准 HTTP(S) proxy variables。

Cursor / Claude 兼容性扫描器

所有扫描器默认均为开启（true / 1 或 false / 0）：

变量	描述
`GROK_CURSOR_SKILLS_ENABLED`	扫描 Cursor skills 目录。
`GROK_CURSOR_RULES_ENABLED`	扫描 `.cursor/rules/`。
`GROK_CURSOR_AGENTS_ENABLED`	扫描 Cursor Agent 定义。
`GROK_CURSOR_MCPS_ENABLED`	扫描 Cursor `mcp.json`。
`GROK_CURSOR_HOOKS_ENABLED`	扫描 Cursor hooks。
`GROK_CLAUDE_SKILLS_ENABLED`	扫描 Claude skills。
`GROK_CLAUDE_RULES_ENABLED`	扫描 Claude rules。
`GROK_CLAUDE_AGENTS_ENABLED`	扫描 `CLAUDE.md` / `CLAUDE.local.md`。
`GROK_CLAUDE_MCPS_ENABLED`	扫描 Claude MCP config。
`GROK_CLAUDE_HOOKS_ENABLED`	扫描 Claude hooks。

TOML Values

项目 .grok/config.toml 仅提供 [mcp_servers]、[plugins] 和 [permission]。其他 section 应放在用户配置（~/.grok/config.toml 或 $GROK_HOME/config.toml）中。

`[models]`

设置	值 / 默认值	描述
`default`	model id（例如 `"grok-build"`）	新 sessions 使用的模型。
`web_search`	model id	客户端 `web_search` 工具使用的模型。
`default_reasoning_effort`	支持时使用 effort level	默认模型的默认 reasoning effort。
`session_summary`	model id	Session 摘要使用的模型。
`image_description`	model id	图像描述使用的模型。
`extra_headers`	map	应用于每个模型的 headers（per-model keys 优先）。
`temperature` / `top_p` / `max_completion_tokens`	numbers	全局 sampling 默认值。
`max_retries`	number	全局 inference retry 默认值。
`stream_tool_calls`	`true` / `false`	全局 tool-call streaming request shape（某些 BYOK endpoint 需要 `false`）。
`allowed_models`	glob list	限制 model picker / default / `-m` selection。
`hidden_models`	id list	从 picker 隐藏（仍可通过 `-m` 使用）。
`disabled_models`	id list	从 catalog 中移除（优先于 hidden）。

`[model.<id>]`

Custom / BYOK models（OpenAI-compatible 或 Anthropic Messages）。优先使用 env_key，不要硬编码 api_key。

设置	值 / 默认值	描述
`model`	string	发送给 API 的 Model id。
`base_url`	URL	Provider endpoint。
`name`	string	Model picker 中的 label。
`description`	string	可选描述。
`api_key`	string	内联 API key（优先使用 `env_key`）。
`env_key`	env var name	保存 API key 的环境变量。
`api_backend`	`chat_completions`	`responses`	`messages`	Protocol。
`temperature` / `top_p` / `max_completion_tokens`	numbers	Sampling。
`context_window`	tokens	Context window 大小（决定 auto-compact timing）。
`extra_headers`	map	Per-request headers。
`supports_backend_search`	`true` / `false`	Endpoint 是否支持 Grok 托管的服务器端搜索工具。
`supports_reasoning_effort` / `reasoning_effort`	bool / effort	支持时使用的 reasoning controls。
`stream_tool_calls`	`true` / `false`	Per-model tool-call streaming。
`max_retries` / `inference_idle_timeout_secs`	numbers	Reliability。

`[mcp_servers.<name>]`

url、command、args、env 和 headers 等 string field 支持 ${VAR} 展开。Headers 还可以使用 {{session_id}}。

stdio

设置	值 / 默认值	描述
`command`	string	Executable（例如 `npx`）。
`args`	string array	Arguments。
`env`	map	Process environment。
`cwd`	path	Process 的工作目录。

HTTP / remote

设置	值 / 默认值	描述
`url`	URL	HTTP/SSE MCP endpoint。
`headers`	map	Request headers。
`bearer_token_env_var`	env var name	从环境变量注入 `Authorization: Bearer`。

通用设置

设置	值 / 默认值	描述
`enabled`	`true`	启用或禁用 server。
`startup_timeout_sec`	`30`	Startup handshake timeout（秒）。
`tool_timeout_sec`	`6000`	默认的每次 tool-call timeout（秒）。
`tool_timeouts`	map name → seconds	Per-tool timeout 覆盖。

`[tools]` 与 `[toolset.*]`

设置	Section	值 / 默认值	描述
`respect_gitignore`	`[tools]`	`true` / `false`（默认 `false`）	为 `true` 时，search 和 read tools 跳过 gitignored 文件。
`file_toolset`	`[toolset]`	`standard`（默认）	`hashline`	File edit tool scheme。
`timeout_secs`	`[toolset.bash]`	seconds（默认 `120`）	Foreground bash command timeout。
`output_byte_limit`	`[toolset.bash]`	bytes（默认 `20000`）	捕获的 bash output 上限。
`max_timeout_secs`	`[toolset.bash]`	seconds（默认 `36000`）	模型请求的 foreground timeout 上限。
`auto_background_on_timeout`	`[toolset.bash]`	`true` / `false`（默认 `true`）	Timeout 时自动将命令转入后台。
`proxy_endpoint`	`[toolset.web_fetch]`	URL	`web_fetch` 的 egress proxy。
`allowed_domains`	`[toolset.web_fetch]`	string array	`web_fetch` 的 domain allowlist 覆盖。

`[sandbox]`（`config.toml`）

设置	值 / 默认值	描述
`profile`	`off`（默认）	`workspace`	`read-only`	`strict`（或 custom）	Filesystem sandbox profile。Custom profile 名称在 `sandbox.toml` 中定义。
`auto_allow_bash`	`true` / `false`（默认 `false`）	Sandbox profile 活动时跳过 bash permission prompt。

在 ~/.grok/sandbox.toml（用户）或 .grok/sandbox.toml（项目）中定义 custom profiles。使用 [sandbox] profile = "…"（位于 config.toml 中）、--sandbox 或 GROK_SANDBOX 激活。内置名称（off、workspace、read-only、strict、devbox）不能重新定义为 custom profiles。

[profiles.project]
extends = "workspace"
restrict_network = false
read_only = ["/data"]
read_write = ["/tmp/scratch"]
# Kernel-enforced deny (read + write/rename). Entries with *, ?, or [ are globs.
deny = ["/data/shared-secrets", "**/.env", "**/*.pem"]

设置	值 / 默认值	描述
`extends`	`workspace`（省略时默认）	`devbox`	`read-only`	`strict`	要继承的内置 profile。
`restrict_network`	`true` / `false`	限制 network access（执行时使用 Linux seccomp）。
`read_only`	path list	额外 read-only paths。
`read_write`	path list	额外 read-write paths。
`deny`	path 或 glob list	Kernel-enforced deny，适用于 read 和 write/rename。条目包含 ``、`?` 或 `[` 时为 glob（例如 `/.env`、`/.pem`）。

当 sandbox 可以应用时，非空 deny list 在 kernel level 执行。在 Linux 上，read-deny 需要 bubblewrap。操作指南请参阅 Sandbox。Managed pins 请参阅 Enterprise 部署。

`[session]`、`[cli]` 与 `[hints]`

设置	Section	值 / 默认值	描述
`auto_compact_threshold_percent`	`[session]`	`0–100`（默认 `85`）	Context 用量达到此百分比时自动压缩。
`load_envrc`	`[session]`	`true` / `false`（默认 `true`）	将 `.envrc` variables 注入 bash。
`auto_update`	`[cli]`	`true` / `false`（未设置时默认开启）	启动时检查 CLI updates。
`channel`	`[cli]`	`stable`	`alpha`	Release channel preference。
`show_tips`	`[cli]`	`true` / `false`	Startup tips。
`new_session_worktree_mode`	`[hints]`	`ask`	`always`	`never`（默认 `never`）	`/new` 是否提供 worktree。
`fork_worktree_mode`	`[hints]`	`ask`	`always`	`never`（默认 `ask`）	`/fork` 是否提供 worktree。

`[ui]`、`[ui.display_refresh]` 与 `[ui.contextual_hints]`

设置	Section	值 / 默认值	描述
`compact_mode`	`[ui]`	`true` / `false`（默认 `false`）	更紧凑的 message padding，也可用 `/compact-mode`。
`screen_mode`	`[ui]`	`fullscreen`（未设置时默认）	`minimal`	普通 `grok` 的默认 render mode。需要重启。
`show_timestamps`	`[ui]`	`true` / `false`（默认 `true`）	消息旁显示时钟时间，也可用 `/timestamps`。
`show_timeline`	`[ui]`	`true` / `false`（默认 `false`）	使用每个 turn 的 tick rail 代替 scrollbar。
`page_flip_on_send`	`[ui]`	`true` / `false`（默认 `true`）	将已发送 prompt 对齐到 viewport 顶部。
`max_thoughts_width`	`[ui]`	`40`–`500`（默认 `120`）	Thoughts panel 的 column width。
`combine_queued_prompts`	`[ui]`	`true` / `false`（默认 `false`）	将连续普通 follow-up 合并成一个 turn。
`theme`	`[ui]`	theme name 或 `auto` / `system`（默认 Grok Night）	颜色主题。`auto` 跟随 OS Light/Dark，也可用 `/theme`。
`auto_dark_theme`	`[ui]`	theme name（默认 `groknight`）	`theme = "auto"` 且 OS 为 Dark 时使用的主题。
`auto_light_theme`	`[ui]`	theme name（默认 `grokday`）	`theme = "auto"` 且 OS 为 Light 时使用的主题。
`simple_mode`	`[ui]`	`true` / `false`（默认 `true`）	为 `true` 时使用 Readline prompt editing；为 `false` 时使用实验性 vim prompt keys。
`vim_mode`	`[ui]`	`true` / `false`（默认 `false`）	Scrollback 中使用 Vim keys（不影响 prompt），也可用 `/vim-mode`。
`prompt_suggestions`	`[ui]`	`true` / `false`（默认 `true`）	每个 turn 后显示下一 prompt 的 ghost text（按 Tab 接受）。
`mouse_reporting_toggle`	`[ui]`	`true` / `false`（默认 `false`）	Scrollback 中的 `Ctrl+R` 切换 terminal mouse capture。
`keep_text_selection`	`[ui]`	`flash`（默认）	`hold`	`word_select`	应用内 selection：短暂闪烁、保持或双击选择单词。
`cursor_blink`	`[ui]`	`true` / `false`（未设置时继承 terminal）	强制 block cursor 闪烁（`true`）或保持稳定（`false`）。
`show_thinking_blocks`	`[ui]`	`true` / `false`（默认 `true`）	Streaming 时显示 thinking/reasoning blocks。
`group_tool_verbs`	`[ui]`	`true` / `false`（默认 `true`）	将连续 read/search/list 工具行折叠成一个摘要。
`collapsed_edit_blocks`	`[ui]`	`true` / `false`（默认 `false`）	将 edits 显示为单行 `+N/-M` 摘要。
`render_mermaid`	`[ui]`	`auto`（默认）	`on`	`off`	Mermaid diagrams：可点击的打开行（`auto`/`on`）或 raw source（`off`）。
`scroll_speed`	`[ui]`	`1`–`100`（默认 `50`）	Mouse/trackpad 滚动速度 multiplier。
`scroll_mode`	`[ui]`	`auto`（默认）	`wheel`	`trackpad`	自动检测错误时强制 wheel 或 trackpad。
`scroll_lines`	`[ui]`	`1`–`10`（未设置时使用 terminal profile）	Wheel 和 trackpad 每个 scroll tick 的行数。
`invert_scroll`	`[ui]`	`true` / `false`（默认 `false`）	反转垂直滚动方向。
`permission_mode`	`[ui]`	`default`	`ask`	`auto`	`always-approve`	默认 tool-permission 行为。Enterprise lock 使用 `requirements.toml`。
`default_selected_permission`	`[ui]`	`always_allow_all_sessions`（默认）	`allow_command_always`	`allow_once`	`reject`	Session 第一次 prompt 中预先选择的 approval 行。
`remember_tool_approvals`	`[ui]`	`true` / `false`（默认 `false`）	显示每个工具的“Always allow …”选项。需要重启。
`cancel_subagents_on_turn_cancel`	`[ui]`	`ask`（未设置时默认）	`always_stop`	`always_continue`	取消仍有 subagents 运行的 turn 时的行为。
`hunk_tracker_mode`	`[ui]`	`agent_only`（默认）	`all_dirty`	`off`	File-change hunk tracking。需要重启。
`fork_secondary_model`	`[ui]`	model id（默认：main default）	Fork 时 secondary Agent 使用的模型。
`voice_keybind_enabled`	`[ui]`	`true` / `false`（默认 `true`）	为 voice dictation 启用 Ctrl+Space / F8（关闭时 `/voice` 仍可用）。
`voice_capture_mode`	`[ui]`	`hold`（默认）	`toggle`	Hold-to-talk 或按下切换 voice capture。
`voice_stt_language`	`[ui]`	language code 或 `auto`（默认 `en` / `[voice].language`）	Dictation 的 Speech-to-text language。
`auto_cadence_enabled`	`[ui.display_refresh]`	`true` / `false`（默认 `false`）	让 stream/scroll cadence 与 display refresh rate 匹配。需要重启。
`undo`	`[ui.contextual_hints]`	`true` / `false`（默认 `true`）	Ctrl+Z 恢复被清空的 prompt draft。
`plan_mode`	`[ui.contextual_hints]`	`true` / `false`（默认 `true`）	对规划型 prompts 建议 plan 模式（Shift+Tab）。
`image_input`	`[ui.contextual_hints]`	`true` / `false`（默认 `true`）	模型接受图像时显示 clipboard image paste 提示。
`send_now`	`[ui.contextual_hints]`	`true` / `false`（默认 `true`）	排队 mid-turn follow-up 后，在空 prompt 上按 Enter 会立即发送。
`small_screen`	`[ui.contextual_hints]`	`true` / `false`（默认 `true`）	在较矮 terminal 上建议 `/compact-mode`。
`word_select`	`[ui.contextual_hints]`	`true` / `false`（默认 `true`）	使用 fold/nav selection 双击后，指向 settings 中的 Word select。
`ssh_wrap`	`[ui.contextual_hints]`	`true` / `false`（默认 `true`）	SSH 缺少 clipboard sink 时推荐 `grok wrap`。

`[permission]`

适用于项目 scope 和用户 scope。评估顺序：deny > ask > allow。

设置	值	描述
`allow` / `deny` / `ask`	rule string arrays	紧凑规则，例如 `Bash(git )`、`Read(src/)`、`Edit(/.rs)`、`MCPTool(server__*)`。
`rules`	`{ action, tool, pattern? }` array	详细形式。`action`：`allow`	`deny`	`ask`。`tool`：`any`	`bash`	`edit`	`read`	`grep`	`mcp`	`webfetch`。

`[features]`、`[subagents]` 与 `[memory]`

设置	Section	值 / 默认值	描述
`web_fetch`	`[features]`	`true` / `false`	启用 `web_fetch` 工具。
`lsp_tools`	`[features]`	`true` / `false`（默认关闭）	提供 LSP 工具。
`write_file`	`[features]`	`true` / `false`（默认开启）	启用 `write` 工具。
`tool_search`	`[features]`	`true` / `false`（默认开启）	MCP tool search / discovery。
`enabled`	`[subagents]`	`true` / `false`	Subagent / task 工具总开关。
`toggle`	`[subagents.toggle]`	subagent → bool map	启用或禁用单个 subagent 类型。
`models`	`[subagents.models]`	subagent → model id map	Per-subagent model routing。
`enabled`	`[memory]`	`true` / `false`（默认关闭）	Cross-session memory 总开关。

`[skills]`、`[plugins]` 与 `[compat.*]`

设置	Section	值	描述
`paths`	`[skills]` / `[plugins]`	path lists	额外 skill 或 plugin 目录。
`disabled`	`[skills]` / `[plugins]`	name lists	发现但不激活。
`enabled`	`[plugins]`	name lists	显式启用 plugins（项目 plugins 可能默认关闭）。
`skills` / `rules` / `agents` / `mcps` / `hooks`	`[compat.cursor]` / `[compat.claude]`	`true` / `false`（默认 `true`）	扫描 Cursor 或 Claude harness 目录。

设置

参考

环境变量

路径与身份验证