首页/Grok Build/设置参考

设置参考

Grok Build 的完整环境变量和 TOML 配置参考。

环境变量

路径与认证

变量	默认值	说明
`GROK_HOME`	`~/.grok`	配置、认证、会话、技能、插件和日志的主目录
`XAI_API_KEY`	—	不使用浏览器/会话登录时的 API Key（CI 和无头模式）

模型与更新

变量	默认值	说明
`GROK_DEFAULT_MODEL`	catalog / config	会话默认模型（等同于 `-m` / `--model`）
`GROK_WEB_SEARCH_MODEL`	内置	`web_search` 工具使用的模型
`GROK_MODELS_BASE_URL`	—	自定义推理基础 URL
`GROK_XAI_API_BASE_URL`	`https://api.x.ai/v1`	API Key 认证的 xAI API 基础 URL
`GROK_DISABLE_AUTOUPDATER`	未设置	设置后抑制自动更新（CI/容器）

工具、沙箱与功能

变量	默认值	说明
`GROK_SANDBOX`	`off`	沙箱配置：`off`、`workspace`、`read-only`、`strict`
`GROK_WEB_FETCH`	`0`	启用 `web_fetch` 工具（默认关闭以保安全）
`GROK_MEMORY`	`0`	启用跨会话记忆
`GROK_SUBAGENTS`	`0`	启用子智能体 / 任务工具
`GROK_AGENT`	`grok-build`	内置智能体名称、配置或绝对路径
`GROK_SHOW_THINKING_BLOCKS`	`0`	在 TUI 中显示推理/思考块
`GROK_WRITE_FILE`	`1`	设为 `0` 禁用写入工具（只读会话）
`GROK_LSP_TOOLS`	`0`	启用 LSP 代码智能工具

MCP、日志与代理

变量	默认值	说明
`GROK_MCP_STARTUP_TIMEOUT_SECS`	`30`	全局 MCP 启动握手超时（秒）
`MCP_TIMEOUT`	同栈	Claude 兼容的 MCP 启动超时（毫秒）
`GROK_LOG_FILE`	—	日志写入路径
`RUST_LOG`	—	日志过滤器（例如 `debug`）
`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`	系统	标准 HTTP(S) 代理变量

TOML 配置值

项目 .grok/config.toml 仅贡献 [mcp_servers]、[plugins] 和 [permission]。其他部分属于用户配置。

[models] — 模型配置

设置	值 / 默认	说明
`default`	模型 ID	新会话使用的模型
`web_search`	模型 ID	`web_search` 工具使用的模型
`default_reasoning_effort`	推理深度	默认模型的推理深度
`temperature` / `top_p` / `max_completion_tokens`	数字	全局采样默认值
`allowed_models`	glob 列表	限制模型选择器范围
`hidden_models`	ID 列表	从选择器隐藏（仍可通过 `-m` 使用）
`disabled_models`	ID 列表	从目录中移除（优先于 hidden）

[model.<id>] — 自定义 / BYOK 模型

设置	值	说明
`model`	字符串	发送到 API 的模型 ID
`base_url`	URL	提供者端点
`name`	字符串	模型选择器中的标签
`api_key` / `env_key`	字符串	内联 API Key / 环境变量名（优先使用 `env_key`）
`api_backend`	`chat_completions` \| `responses` \| `messages`	协议
`temperature` / `top_p` / `max_completion_tokens`	数字	采样参数
`context_window`	tokens	上下文窗口大小（驱动自动压缩时机）
`extra_headers`	map	每请求头
`supports_backend_search`	bool	是否支持 Grok 托管的服务端搜索工具

[mcp_servers.<name>] — MCP 服务器

字符串字段如 url、command、args、env 和 headers 支持 ${VAR} 展开。

设置	默认值	说明
`command`	—	可执行文件（例如 `npx`）
`args`	—	参数数组
`env`	—	进程环境变量
`url`	—	HTTP/SSE MCP 端点
`headers`	—	请求头
`enabled`	`true`	启用或禁用服务器
`startup_timeout_sec`	`30`	启动握手超时（秒）
`tool_timeout_sec`	`6000`	默认工具调用超时（秒）

[tools] 和 [toolset.*]

设置	默认值	说明
`respect_gitignore`	`false`	搜索和读取工具跳过 gitignored 文件
`file_toolset`	`standard`	文件编辑工具方案（`standard` \| `hashline`）
`timeout_secs`	`120`	前台 bash 命令超时
`output_byte_limit`	`20000`	最大捕获 bash 输出

[sandbox] — 沙箱配置

设置	默认值	说明
`profile`	`off`	文件系统沙箱配置：`off`、`workspace`、`read-only`、`strict` 或自定义
`auto_allow_bash`	`false`	沙箱激活时跳过 bash 权限提示

自定义沙箱配置 — sandbox.toml

在 ~/.grok/sandbox.toml（用户）或 .grok/sandbox.toml（项目）中定义自定义配置：

[profiles.project]
extends = "workspace"
restrict_network = false
read_only = ["/data"]
read_write = ["/tmp/scratch"]
deny = ["/data/shared-secrets", "**/.env", "**/*.pem"]

[session]、[cli] 和 [hints]

设置	部分	默认值	说明
`auto_compact_threshold_percent`	`[session]`	`85`	上下文使用率达到此百分比时自动压缩
`load_envrc`	`[session]`	`true`	将 `.envrc` 变量注入 bash
`auto_update`	`[cli]`	开启	启动时检查 CLI 更新
`channel`	`[cli]`	`stable`	发布通道：`stable` \| `alpha`
`new_session_worktree_mode`	`[hints]`	`never`	`/new` 是否提供工作树
`fork_worktree_mode`	`[hints]`	`ask`	`/fork` 是否提供工作树

[permission] — 权限规则

评估顺序：deny > ask > allow

设置	值	说明
`allow` / `deny` / `ask`	规则字符串数组	紧凑规则，例如 `Bash(git )`、`Read(src/)`、`Edit(/.rs)`、`MCPTool(server__*)`
`rules`	`{ action, tool, pattern? }` 数组	详细形式

[features]、[subagents] 和 [memory]

设置	部分	默认值	说明
`web_fetch`	`[features]`	关闭	启用 `web_fetch` 工具
`lsp_tools`	`[features]`	关闭	暴露 LSP 工具
`write_file`	`[features]`	开启	启用写入工具
`tool_search`	`[features]`	开启	MCP 工具搜索 / 发现
`enabled`	`[subagents]`	—	子智能体 / 任务工具主开关
`enabled`	`[memory]`	关闭	跨会话记忆主开关

[skills]、[plugins] 和 [compat.*]

设置	部分	说明
`paths`	`[skills]` / `[plugins]`	额外的技能或插件目录
`disabled`	`[skills]` / `[plugins]`	发现但不激活
`enabled`	`[plugins]`	显式启用插件
`skills` / `rules` / `agents` / `mcps` / `hooks`	`[compat.cursor]` / `[compat.claude]`	扫描 Cursor 或 Claude 目录（默认 `true`）