设置
参考
环境变量
路径和认证
| 变量 | 默认值 | 描述 |
|---|---|---|
GROK_HOME | ~/.grok | 配置、认证、会话、技能、插件和日志的主目录。 |
XAI_API_KEY | — | 不使用浏览器/会话登录时的 API 密钥（CI 和无头模式）。 |
模型和更新
| 变量 | 默认值 | 描述 |
|---|---|---|
GROK_DEFAULT_MODEL | catalog / config | 会话默认模型（与 -m / --model 相同的概念）。 |
GROK_WEB_SEARCH_MODEL | built-in | web_search 工具使用的模型。 |
GROK_MODELS_BASE_URL | — | 自定义推理基础 URL；模型列表来自 {base}/models。 |
GROK_MODELS_LIST_URL | {GROK_MODELS_BASE_URL}/models | 当模型列表 URL 与默认值不同时覆盖。 |
GROK_XAI_API_BASE_URL | https://api.x.ai/v1 | API 密钥认证的 xAI API 基础地址。 |
GROK_DISABLE_AUTOUPDATER | unset（允许更新） | 如果设置，则为此进程禁用自动更新器（CI/容器）。 |
工具、沙箱和功能
| 变量 | 默认值 | 描述 |
|---|---|---|
GROK_SANDBOX | off | 沙箱配置文件：off、workspace、read-only、strict（或自定义配置文件名）。与 --sandbox 相同。 |
GROK_SANDBOX_AUTO_ALLOW_BASH | 0 | 在活动的沙箱内自动允许 bash（1/0）。 |
GROK_RESPECT_GITIGNORE | 未设置时使用配置 | 强制对搜索/读取工具使用 gitignore 过滤（1/0）；覆盖 [tools] respect_gitignore。 |
GROK_WEB_FETCH | 0 | 启用 web_fetch 工具（1/0）。出于安全考虑默认关闭。 |
GROK_WEB_FETCH_PROXY | — | web_fetch 的出站代理 URL。 |
GROK_MEMORY | 0 | 启用跨会话记忆（1/0）。 |
GROK_SUBAGENTS | 0 | 启用子代理/任务工具（1/0）。 |
GROK_AGENT | grok-build | 内置代理名称、配置文件或代理定义的绝对路径。 |
GROK_WRITE_FILE | 1 | 使用 0 禁用 write 工具（只读会话）。 |
GROK_TOOL_SEARCH | 1 | 对于大型工具集的按需 MCP 工具发现（1/0）。 |
GROK_LSP_TOOLS | 0 | 启用 LSP 代码智能工具（1/0）。 |
UI 和外观
| 变量 | 默认值 | 描述 |
|---|---|---|
GROK_THEME | built-in | 颜色主题。 |
GROK_SHOW_THINKING_BLOCKS | 1 | 在 TUI 中显示思考/推理块（1/0）。 |
GROK_GROUP_TOOL_VERBS | 1 | 折叠连续的读取/搜索/列出工具行（1/0）。 |
GROK_COLLAPSED_EDIT_BLOCKS | 0 | 将编辑折叠为单行 +N/-M 摘要（1/0）。 |
GROK_PROMPT_SUGGESTIONS | 1 | 每次轮次后的下一个提示幽灵文本（1/0）。 |
GROK_SCROLL_SPEED | 50 | 鼠标/触控板滚动速度（1–100）。 |
GROK_SCROLL_MODE | auto | 滚动输入：auto、wheel 或 trackpad。 |
GROK_SCROLL_LINES | 未设置时使用配置 | 每次滚动刻度的行数（1–10）。 |
GROK_INVERT_SCROLL | 0 | 反转垂直滚动方向（1/0）。 |
GROK_DEFAULT_SELECTED_PERMISSION | always_allow_all_sessions | 首次权限提示时预选的行。 |
GROK_REMEMBER_TOOL_APPROVALS | 0 | 显示每个工具的"始终允许..."选项（1/0）。 |
GROK_MOUSE_REPORTING_TOGGLE | 0 | 在回滚区域中使用 Ctrl+R 切换终端鼠标捕获（1/0）。 |
GROK_DISPLAY_REFRESH_AUTO_CADENCE | 0 | 匹配流/滚动节奏与显示器刷新率（1/0）。 |
MCP、日志和代理
| 变量 | 默认值 | 描述 |
|---|---|---|
GROK_MCP_STARTUP_TIMEOUT_SECS | 30 | 全局 MCP 启动握手超时时间（秒）。每个服务器的 startup_timeout_sec 仍然优先。 |
MCP_TIMEOUT | same stack | Claude 兼容的 MCP 启动超时时间（毫秒）（在检查 GROK_MCP_STARTUP_TIMEOUT_SECS 之前）。 |
GROK_LOG_FILE | — | 将日志写入此路径（当 TUI 捕获 stderr 时有用）。 |
RUST_LOG | — | GROK_LOG_FILE 和无头 stderr 的日志过滤器（例如 debug）。 |
GROK_CRASH_HANDLER | 0 | 在 panic 时，在 $GROK_HOME/crash/ 下写入报告（1/0）。 |
HTTPS_PROXY / HTTP_PROXY / NO_PROXY | system | 出站流量的标准 HTTP(S) 代理变量。 |
Cursor / Claude 兼容性扫描器
所有默认为开启（true / 1 或 false / 0）：
| 变量 | 描述 |
|---|---|
GROK_CURSOR_SKILLS_ENABLED | 扫描 Cursor 技能目录。 |
GROK_CURSOR_RULES_ENABLED | 扫描 .cursor/rules/。 |
GROK_CURSOR_AGENTS_ENABLED | 扫描 Cursor 代理定义。 |
GROK_CURSOR_MCPS_ENABLED | 扫描 Cursor mcp.json。 |
GROK_CURSOR_HOOKS_ENABLED | 扫描 Cursor 钩子。 |
GROK_CLAUDE_SKILLS_ENABLED | 扫描 Claude 技能。 |
GROK_CLAUDE_RULES_ENABLED | 扫描 Claude 规则。 |
GROK_CLAUDE_AGENTS_ENABLED | 扫描 CLAUDE.md / CLAUDE.local.md。 |
GROK_CLAUDE_MCPS_ENABLED | 扫描 Claude MCP 配置。 |
GROK_CLAUDE_HOOKS_ENABLED | 扫描 Claude 钩子。 |
TOML 值
项目 .grok/config.toml 仅贡献 [mcp_servers]、[plugins] 和 [permission]。其他部分属于用户配置（~/.grok/config.toml 或 $GROK_HOME/config.toml）。
[models]
| 设置 | 值/默认值 | 描述 |
|---|---|---|
default | 模型 ID（例如 "grok-build"） | 用于新会话的模型。 |
web_search | 模型 ID | 客户端 web_search 工具使用的模型。 |
default_reasoning_effort | 如果支持则使用努力级别 | 默认模型的默认推理努力程度。 |
session_summary | 模型 ID | 用于会话摘要的模型。 |
image_description | 模型 ID | 用于图像描述的模型。 |
extra_headers | 映射 | 应用于每个模型的标头（每个模型的键优先）。 |
temperature / top_p / max_completion_tokens | 数字 | 全局采样默认值。 |
max_retries | 数字 | 全局推理重试默认值。 |
stream_tool_calls | true / false | 全局工具调用流式请求形状（某些 BYOK 端点需要 false）。 |
allowed_models | glob 列表 | 限制模型选择器/默认值/-m 选择。 |
hidden_models | ID 列表 | 从选择器中隐藏（仍可通过 -m 使用）。 |
disabled_models | ID 列表 | 从目录中移除（优先于隐藏）。 |
[model.<id>]
自定义 / BYOK 模型（OpenAI 兼容或 Anthropic 消息）。优先使用 env_key 而不是硬编码 api_key。
| 设置 | 值/默认值 | 描述 |
|---|---|---|
model | 字符串 | 发送到 API 的模型 ID。 |
base_url | URL | 提供者端点。 |
name | 字符串 | 模型选择器中的标签。 |
description | 字符串 | 可选描述。 |
api_key | 字符串 | 内联 API 密钥（优先使用 env_key）。 |
env_key | 环境变量名 | 包含 API 密钥的环境变量。 |
api_backend | chat_completions | responses |
temperature / top_p / max_completion_tokens | 数字 | 采样。 |
context_window | token | 上下文窗口大小（驱动自动压缩时机）。 |
extra_headers | 映射 | 每个请求的标头。 |
supports_backend_search | true / false | 端点是否支持 Grok 托管的服务器端搜索工具。 |
supports_reasoning_effort / reasoning_effort | 布尔值/努力程度 | 支持时的推理控制。 |
stream_tool_calls | true / false | 每个模型的工具调用流式处理。 |
max_retries / inference_idle_timeout_secs | 数字 | 可靠性。 |
[mcp_servers.<name>]
字符串字段如 url、command、args、env 和 headers 支持 ${VAR} 扩展。标头也可以使用 。
stdio
| 设置 | 值/默认值 | 描述 |
|---|---|---|
command | 字符串 | 可执行文件（例如 npx）。 |
args | 字符串数组 | 参数。 |
env | 映射 | 进程环境。 |
cwd | 路径 | 进程的工作目录。 |
HTTP / 远程
| 设置 | 值/默认值 | 描述 |
|---|---|---|
url | URL | HTTP/SSE MCP 端点。 |
headers | 映射 | 请求标头。 |
bearer_token_env_var | 环境变量名 | 从环境变量注入 Authorization: Bearer。 |
通用
| 设置 | 值/默认值 | 描述 |
|---|---|---|
enabled | true | 启用或禁用服务器。 |
startup_timeout_sec | 30 | 启动握手超时（秒）。 |
tool_timeout_sec | 6000 | 默认每个工具调用超时（秒）。 |
tool_timeouts | 映射 名称 → 秒 | 每个工具超时覆盖。 |
[tools] 和 [toolset.*]
| 设置 | 部分 | 值/默认值 | 描述 |
|---|---|---|---|
respect_gitignore | [tools] | true / false（默认 false） | 当为 true 时，搜索和读取工具跳过 gitignore 文件。 |
file_toolset | [toolset] | standard（默认） | hashline |
timeout_secs | [toolset.bash] | 秒（默认 120） | 前台 bash 命令超时。 |
output_byte_limit | [toolset.bash] | 字节（默认 20000） | 最大捕获的 bash 输出。 |
max_timeout_secs | [toolset.bash] | 秒（默认 36000） | 模型请求的前台超时上限。 |
auto_background_on_timeout | [toolset.bash] | true / false（默认 true） | 在超时自动将命令置于后台。 |
proxy_endpoint | [toolset.web_fetch] | URL | web_fetch 的出站代理。 |
allowed_domains | [toolset.web_fetch] | 字符串数组 | web_fetch 的域名允许列表覆盖。 |
[sandbox]（config.toml）
| 设置 | 值/默认值 | 描述 |
|---|---|---|
profile | off（默认） | workspace |
auto_allow_bash | true / false（默认 false） | 当沙箱配置文件激活时跳过 bash 权限提示。 |
sandbox.toml 自定义配置文件
在 ~/.grok/sandbox.toml（用户）或 .grok/sandbox.toml（项目）中定义自定义配置文件。在 config.toml、--sandbox 或 GROK_SANDBOX 中使用 [sandbox] profile = "…" 激活。内置名称（off、workspace、read-only、strict、devbox）不能重新定义为自定义配置文件。
toml
[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 |
restrict_network | true / false | 限制网络访问（强制执行时为 Linux seccomp）。 |
read_only | 路径列表 | 其他只读路径。 |
read_write | 路径列表 | 其他读写路径。 |
deny | 路径或 glob 列表 | 对读取和写入/重命名的内核强制拒绝。如果条目包含 *、? 或 [（例如 **/.env、**/*.pem），则为 glob。 |
当沙箱可以应用时，非空的 deny 列表在内核级别强制执行。在 Linux 上，读取拒绝需要 bubblewrap。操作指南：沙箱。管理的引脚：企业部署。
[session]、[cli] 和 [hints]
| 设置 | 部分 | 值/默认值 | 描述 |
|---|---|---|---|
auto_compact_threshold_percent | [session] | 0–100（默认 85） | 当上下文使用率达到此百分比时自动压缩。 |
load_envrc | [session] | true / false（默认 true） | 将 .envrc 变量注入 bash。 |
auto_update | [cli] | true / false（未设置时默认开启） | 在启动时检查 CLI 更新。 |
channel | [cli] | stable | alpha |
show_tips | [cli] | true / false | 启动提示。 |
new_session_worktree_mode | [hints] | ask | always |
fork_worktree_mode | [hints] | ask | always |
[ui]、[ui.display_refresh] 和 [ui.contextual_hints]
| 设置 | 部分 | 值/默认值 | 描述 |
|---|---|---|---|
compact_mode | [ui] | true / false（默认 false） | 更密集的消息填充。也适用于 /compact-mode。 |
screen_mode | [ui] | fullscreen（未设置时默认） | minimal |
show_timestamps | [ui] | true / false（默认 true） | 消息旁边的时钟时间。也适用于 /timestamps。 |
show_timeline | [ui] |