Grok Build設定ガイド｜config.tomlとMCP・hooks【2026年9月】

Grok Buildのconfig.tomlが分かりにくい理由は、TOMLの書き方ではありません。同じキーを書ける場所が複数あり、場所によって「効く／効かない／上書きできない」が変わることです。個人の好みはホーム側、リポジトリで共有したいものはプロジェクト側、組織として絶対に動かしたくないものはrequirements.toml——この3段を先に決めないと、書いたのに効かない設定が積み上がります。

もう1つの落とし穴が、公開ドキュメントと同梱ドキュメントの粒度差です。docs.x.ai のSettingsページはスコープを5つに整理した入門で、キーの網羅表はSettings Referenceにあります。一方、Grok Buildは2026年7月にソースがApache-2.0で公開されており（xai-org/grok-build・リポジトリ作成2026年7月14日）、そのツリーにはCLIに同梱されて起動時に手元へ展開される設定リファレンスが入っています。この2つを突き合わせると、公開ドキュメントには出てこない層・キー・制約が見えます。

この記事は2026年9月27日に、docs.x.ai の/build/*ページ24本と、OSSミラーの設定ガイド（05-configuration.md）・設定リファレンス（26-config-reference.md）・hooks仕様（10-hooks.md）を取得して書き直しています。公式changelog（x.ai/build/changelog）は同日、当方の環境からはCloudflareにより403で取得できなかったため、版ごとの日付を一次情報として本文に置いていません。確認できない設定名や、SNSで見かけただけのキーは入れません。Grokエージェント全体の概念から確認したい方は、先にGrokエージェント完全ガイドを読むと全体像がつかみやすいです。Grok Buildそのものの使い方はGrok Buildの使い方完全ガイドでもまとめています。

Grok Buildのconfig.tomlはどこに置くか｜読み込み8層の優先順位

Grok Buildの設定は単一ファイルで完結しません。CLI同梱の設定リファレンスは、読み込み順を8層として明示しています（後の行が勝つ。ただしrequirements.tomlのpinとmanagedの例外は別）。docs.x.ai のSettingsページが示す5スコープは、この8層を利用者視点でまとめた入門版です。

順	読み込むもの	役割
1	コンパイル済みの既定値	何も書かないときの挙動
2	/etc/grok/managed_config.toml → $GROK_HOME/managed_config.toml	組織が配る既定値（利用者が上書きできる）
3	$GROK_HOME/config.toml（既定は~/.grok）	個人設定。/settingsの保存先
4	プロジェクト.grok/config.toml	[mcp_servers]・[plugins]・[permission]・[mcp] max_output_bytesのみ
5	GROK_CONFIG（インラインJSON）／GROK_CONFIG_PATH（JSONまたはTOML）	許可リスト内のキーだけのオーバーレイ
6	$GROK_HOME/requirements.toml → /etc/grok/requirements.toml → macOS MDM ai.x.grok	管理者層。pin指定のキーは下位から上書き不可
7	GROK_*環境変数	セッション・CIでの上書き
8	CLIフラグ（--model、--sandbox、--yoloなど）	その起動だけの上書き

ここで押さえるべきは3点です。第1に、.grok/config.tomlは「リポジトリに置ける全部入り設定」ではありません。モデルのデフォルト、UIの好み、個人のAPIキー周辺は、ユーザー設定か環境変数に置きます。第2に、GROK_CONFIG／GROK_CONFIG_PATHは環境変数の見た目をしていますが、環境変数の層（7）ではなく設定ファイル層の一部（5）として扱われ、requirements.tomlより下に置かれます。第3に、この層は許可リスト方式でフェイルクローズです。同梱ガイドでは、オーバーレイが触れるのはmodels・features・絞り込まれたtoolset・フィルタ項目に限ったshell_environment_policyだけで、それ以外のテーブルは境界で破棄され、コマンドの起動・認証ポリシー・通信先の変更・信頼の昇格・探索元の追加には使えないと明記されています。ACPクライアントやハーネスがGrok Buildを起動する際に、設定ファイルを書かずに値を差し込むための穴であって、権限昇格の経路ではありません。

# インラインJSONで既定のreasoning effortだけ差し込む例（同梱ガイドの記載）
GROK_CONFIG='{"models": {"default_reasoning_effort": "high"}}' grok agent stdio

どのファイルのどの値が勝ったかはgrok inspectで確認できます。設定を変えてTUIを何度も再起動して悩むより、まずinspectで「どのconfig sourceが見えているか」を見るほうが早いです。--jsonを付ければ機械可読な出力になり、CIでの設定監査にも使えます。

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 設定ソース、instructions（AGENTS.md等）、skills、plugins、hooks、MCPを一覧
grok inspect

# 機械可読（設定監査・差分チェック向け）
grok inspect --json

# 一時的に別ホームで検証したい場合
export GROK_HOME="$HOME/.grok-work"
grok inspect

置き場所	中身
~/.grok/config.toml	本体の設定ファイル
~/.grok/pager.toml	TUIの見た目（スクロールバック・ブロック表示・アニメーション）
~/.grok/auth.json	認証情報（自動管理）
~/.grok/sessions/	作業ディレクトリごとのセッション履歴
~/.grok/logs/	内部ログ（unified.jsonl、MCPサーバーのログ）
~/.grok/trusted_folders.toml	フォルダ信頼の記録（hooks・MCP・LSP・プロジェクト指示・プロジェクトskillsを一括で解禁）
~/.grok/sandbox.toml／.grok/sandbox.toml	カスタムサンドボックスプロファイル
.grok/lsp.json／~/.grok/lsp.json	LSPサーバー定義（プロジェクト側が優先）

dotfilesリポジトリで設定を管理している人向けの実務的な注意が1つあります。同梱ガイドによると、ユーザーconfig.tomlへの書き込み（/settingsなどからの保存）はシンボリックリンクを辿って参照先の実ファイルを書き換え、リンクはリンクのまま残ります。一方、プロジェクト.grok/config.tomlへの書き込み（MCP・plugin・permissionの編集）はリンクを通常ファイルに置き換えます。これは後の保存がリポジトリ外へ抜けるのを防ぐための挙動です。なお、構文エラーで読めないユーザーconfig.tomlは上書きされません（直してから保存し直す）。

事例区分: 想定シナリオ
個人開発者がGrok Buildを試す場合、最初のゴールは「最強の設定を作る」ではなく、「毎回同じ挙動で起動し、危険な操作は確認を挟む」ことです。モデルやMCPを増やすのは、grok inspectで読み込み状態を確認できるようになってからで問題ありません。

grok build mcpの書き方｜[mcp_servers]とgrok mcpコマンド

grok build mcpで必要なことは2つだけです。追加はgrok mcp addかTOMLの[mcp_servers.<name>]、確認はgrok mcp doctorとgrok inspect。MCPサーバーのツールは組み込みツールと並んで<server>__<tool>という名前空間で見えるので、権限ルールを書くときもこの形で指定します。

一番早いのはCLIです。--より後ろがサーバーの起動コマンドになります。OAuthが必要なリモートサーバーは初回利用時にブラウザが開き、トークンは~/.grok/mcp_credentials.jsonに保存されます。

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# ローカルのstdioサーバー（-- 以降が起動コマンド）
grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# HTTPのリモートサーバー（OAuthは自動で処理される）
grok mcp add --transport http linear https://mcp.linear.app/mcp

# 固定の認証ヘッダーを付ける（--header は繰り返し指定できる）
grok mcp add --transport http api https://mcp.example.com/mcp --header "Authorization: Bearer ${API_TOKEN}"

# 一覧・削除・診断（list と doctor は --json に対応）
grok mcp list --json
grok mcp remove filesystem
grok mcp doctor linear

# リポジトリに同梱する（カレントディレクトリに .grok/config.toml を書く）
grok mcp add --scope project repo_filesystem -- npx -y @modelcontextprotocol/server-filesystem ./docs

TOMLで直接書く場合はこうなります。url・command・args・env・headersの文字列では${VAR}と${VAR:-default}が読み込み時に展開されるため、秘密情報を環境変数に置いたままにできます。headersでは{{session_id}}も使えます。

# .grok/config.toml（プロジェクト共有）または ~/.grok/config.toml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[mcp_servers.repo_filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
env = { API_KEY = "${MY_API_KEY}" }
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 6000
tool_timeouts = { create_issue = 120 }

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_API_KEY"
headers = { "x-mcp-session-id" = "{{session_id}}" }

[mcp]
max_output_bytes = 200000

キー	対象	既定／意味
command／args／env／cwd	stdio	実行ファイル、引数、プロセス環境、作業ディレクトリ
url／headers	HTTP・SSE	エンドポイントとリクエストヘッダー
bearer_token_env_var	HTTP	環境変数からAuthorization: Bearerを注入する
oauth／oauth_client_id／oauth_client_secret_env_var／oauth_scopes	HTTP	OAuthクライアントの明示指定
enabled	共通	既定true
startup_timeout_sec	共通	既定30（秒）。初回にnpxがパッケージを取得するサーバーは伸ばす
tool_timeout_sec	共通	既定6000（秒）
tool_timeouts	共通	ツール名ごとのタイムアウト上書き
expose_image_base64／type	共通	画像結果の扱い、トランスポート種別の明示
[mcp] max_output_bytes	全体	MCPツール出力のバイト上限。プロジェクト設定でも指定できる

プロジェクトスコープの読み込み規則は、実務で最も事故が起きる部分です。Grok Buildはカレントディレクトリからgit rootへ向かって各.grok/config.tomlを読み、同名のプロジェクトサーバーはユーザー側の同名サーバーを完全に置き換えます（マージではありません）。同梱ガイドはさらに具体的で、[mcp_servers]と[plugins]の優先順位はカレントの.grok/config.toml > リポジトリルートの.grok/config.toml > ~/.grok/config.toml、一方で[permission]ルールは優先順位で上書きされず、すべてのファイルを横断してマージされる（評価はdeny > ask > allow）と書き分けられています。つまり「MCPは置き換え、権限は足し算」です。チームで使うMCPにはrepo_filesystem・project_docsのように用途が分かる名前を付けてください。

互換読み込みも覚えておくと事故が減ります。Grok Buildは~/.claude.json、.cursor/mcp.json、プロジェクトの.mcp.jsonからもMCP設定を読み、config.tomlより低い優先度でマージします。他のハーネスで設定した覚えのないサーバーが出てきたら、まずgrok inspectで出所を見てください。ベンダーごとに切るなら[compat.claude] mcps = falseか[compat.cursor] mcps = falseです。

タイムアウトの単位違いも押さえておきます。グローバルの起動ハンドシェイクはGROK_MCP_STARTUP_TIMEOUT_SECSが秒、Claude互換のMCP_TIMEOUTがミリ秒で、MCP_TIMEOUTのほうが先に評価されます（サーバーごとのstartup_timeout_secが最終的に勝ちます）。起動しないのに接続できないstdioサーバーは、stderrが~/.grok/logs/mcp/<server>.stderr.logに落ちているので、まずgrok mcp doctor、次にこのログを見ます。接続エラーの切り分け手順はMCPサーバーのデバッグ方法も併せてどうぞ。

TUIからは/mcpsで拡張モーダルのMCPタブが開きます。Spaceで有効・無効の切り替え、rで設定編集後の再読み込み、iでOAuth認証、a／xで追加・削除です。設定ファイルを直したあとにTUIを再起動する必要はありません。

grok build hooksの書き方｜config.tomlに直接書ける[[hooks.Event]]

grok build hooksへの直答は「hooksはJSONファイル専用ではない」です。公開ドキュメントのHooksページはJSONファイル（~/.grok/hooks/*.jsonと<project>/.grok/hooks/*.json）の説明が中心ですが、CLI同梱のhooks仕様と設定リファレンスは、[[hooks.<Event>]]がconfig.toml・managed_config.toml・requirements.tomlの3ファイルで有効なキーであることを明記しています（設定リファレンスのhooks.<event>は「array of tables」）。本記事の旧版は「hooksを何でもconfig.tomlに書くわけではない」と書いていましたが、2026年9月時点の仕様ではTOMLに書けます。訂正します。

# ~/.grok/config.toml（managed_config.toml / requirements.toml も同じ形）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[[hooks.PreToolUse]]
matcher = "Bash|Write|Edit"
hooks = [
  { type = "command", command = "/opt/guard/pretooluse.sh", timeout = 10 },
]

# 入れ子の配列テーブル形も同じ構造に解釈される（同梱仕様はインライン形を推奨）
[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "/opt/guard/on-stop.sh"
timeout = 5

JSONで書く場合の形は変わりません。matcherはツール名に対する正規表現（Claude CodeのBash・Read・Editといった名前はGrok側に自動マッピングされます）、省略すると全件一致です。typeはcommandかhttp（urlにイベントをPOST）、timeoutは秒で既定5です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bin/safety-check.sh", "timeout": 10 }]
      }
    ]
  }
}

イベント	発火するとき	ブロックできるか
SessionStart／SessionEnd	セッションの開始・終了（SessionEndは子セッションでsubagentTypeを運ぶ）	いいえ
UserPromptSubmit	プロンプトを送信したとき	はい（プロンプトを止められる）
PreToolUse	ツールが実行される直前	はい（denyで拒否）
PostToolUse	ツールの実行完了（非ゼロ終了を含む）	いいえ。ただしモデルが見る出力を差し替えられる
PostToolUseFailure	ディスパッチ失敗、MCPツールのエラー応答	いいえ（additionalContextを渡せる）
PermissionDenied	権限システムがツール呼び出しを拒否したとき	いいえ
Stop	ターンが正常に終わったとき	はい（作業を続行させられる）
StopFailure	APIエラーでターンが終わったとき	いいえ
StopCancelled	中断・権限拒否・--max-turns到達・進捗なしで打ち切られたとき	いいえ
Notification	通知（idle_prompt・permission_prompt・task_completeなど）	いいえ
SubagentStart／SubagentStop	サブエージェントの開始・終了（SubagentEndは別名）	SubagentStopははい
PreCompact／PostCompact	会話の圧縮の前後	いいえ

スクリプトの契約はシンプルです。イベントはJSONで標準入力に届き、hookEventName・sessionId・cwd・workspaceRoot、ツールイベントではtoolName・toolInputが入ります。プロセスの環境変数にはGROK_HOOK_EVENT・GROK_HOOK_NAME・GROK_SESSION_ID・GROK_WORKSPACE_ROOTが渡ります（plugin由来のhooksはGROK_PLUGIN_ROOT・GROK_PLUGIN_DATAも受け取ります）。PreToolUseは標準出力にJSONを書いて判定します。

{ "decision": "deny", "reason": "Unsafe command detected" }

終了コード0は許可、2は拒否です。重要なのはfail-openという設計方針です。タイムアウト・クラッシュ・壊れた出力は、セッションに記録されるだけでツール呼び出しはそのまま進みます。明示的なdenyだけがブロックします。例外は1つで、PreToolUseが返したupdatedInputがツールのスキーマに合わなかった場合だけ、安全に書き換えられないため呼び出しがブロックされ、入力不正として報告されます。同一イベントの複数ハンドラは設定順に走り、最初のdenyで連鎖が止まります。どのハンドラもモデルの元の入力を見るため、updatedInputの書き換えは全ハンドラ終了後に適用されます（最後の書き換えが勝ちます）。

プロジェクトのhooksは信頼（trust）を得るまで黙ってスキップされます。/hooks-trustか--trustで許可し、判定は~/.grok/trusted_folders.tomlに記録されます。このフォルダ信頼はMCP・LSP・hooks・プロジェクト指示・プロジェクトskillsを一括で解禁する1つのゲートで、同じリポジトリのサブディレクトリまで及びます（配下の別のgitチェックアウトは別ワークスペース扱いで対象外）。逆にGROK_FOLDER_TRUST=0や[folder_trust] enabled = falseで切ると、これらがまとめてゲートされなくなります。

組織として固定したい場合は、enforced hooksという考え方になります。root所有の/etc/grok/requirements.tomlと/etc/grok/managed_config.toml、および署名が一致している~/.grok/requirements.tomlのhooksは/hooksで[policy]バッジが付き、Spaceで無効化できず、~/.grok/disabled-hooksでもスキップされません。さらに端末を「組織が強制するhooksだけ」に絞るなら次の1行です。

# /etc/grok/requirements.toml
allow_managed_hooks_only = true

これを入れると、~/.grok/hooks・~/.grok/*.tomlのhooks・プロジェクトhooks・pluginのhooks・agentのfrontmatter由来のhooks・ClaudeとCursorの互換ファイルがディスパッチ時にスキップされ、/hooksでは[disabled]表示になります。締める方向にしか動かないpinで、どの層も解除できません。Windowsにはroot所有の層（/etc/grok）が無いため、署名済みの同期requirements.tomlとACPクライアント登録のhooksだけが残ります。Claude CodeでのHooks設計に慣れている方はClaude Code Hooksの使い方と読み比べると、イベント名とブロック可否の対応が早く頭に入ります。

最後に小さな罠を1つ。TOML／JSONいずれでも、commandやurlに書いた${VAR}は読み込み時に展開されません。そのままhookランナーに渡り、展開は実行側で1回だけ行われます（MCPの[mcp_servers]は読み込み時に展開されるので、挙動が逆です）。

grok build goalの正体｜/goalと[workflows]の関係

grok build goalを検索して手が止まる理由は明確です。2026年9月27日時点のdocs.x.ai には/goalの記載がなく、公開されているコマンド表にも出てきません。実体はCLI同梱ドキュメントにあります。TOML側のキーは[goal] enabledの1つだけで、これは「/goalを使えるようにするか」のスイッチです。

その上で、/goalの中身はもう1つの設定で2種類に切り替わります。同梱ガイドの記述では、バックグラウンドワークフローが有効なとき（既定）はホスト側のワークフローエンジンがラウンドを評価して完了検証まで駆動し、無効にするとモデル側のupdate_goalツールにフォールバックします。「/goalが使えるか」と「/goalが何で動くか」は別のスイッチだ、という構造です。

# ~/.grok/config.toml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[goal]
enabled = true          # /goal を使えるようにする

[workflows]
enabled = true          # 既定オン。false にすると /goal は update_goal ツール駆動に戻る
                        # 環境変数 GROK_WORKFLOWS=0 でも同じ

バックグラウンドワークフローは、workflowツール・名前付きの.grok/workflows/*.rhaiスクリプト・/deep-research・/workflow起動をまとめた機能で、既定で有効です。プロジェクト側は<repo-root>/.grok/workflows/、個人は~/.grok/workflows/から見つかります。探索と呼び出しはスクリプトのmeta.nameを鍵にするため、ファイル名とmeta.nameを一致させておくのが運用のコツです。名前が衝突した場合は組み込み > プロジェクト > ユーザーの順で勝つので、スコープをまたいで一意な名前にします。

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 作る（対話でファンアウト・検証・スコープを聞かれ、.grok/workflows/<name>.rhai が保存される）
/create-workflow Review the current branch for bugs, then verify each finding

# 起動（JSON引数は任意）・一時停止・再開・停止
/workflow review-changes {"target":"origin/main...HEAD"}
/workflow pause review-changes
/workflow resume review-changes
/workflow stop review-changes-2

# 組み込みの調査ワークフロー
/deep-research Grok Build の設定層の変更履歴

起動ごとにセッション内で一意の表示ハンドル（deep-research-2のような形）が付き、ダッシュボードやpause／resume／stopではこのハンドルを使います。内部のrun IDはコマンドに出てきません。番号付きのハンドルは再利用できる定義名ではないため、ダッシュボードの保存は新しい一意なmeta.nameを付けるまで無効になります。「/goalで回した作業をそのまま定型化したい」ときは、ここで名前を決め直す手順が必要だと覚えておくと迷いません。

定期実行だけが目的なら、ワークフローではなく/loopのほうが軽いです。間隔はNs（最小60）・Nm・Nh・Ndで、即時に1回発火してから繰り返します。ループは7日で期限切れ、同時に有効なスケジュールタスクは最大50件です。サブエージェントを含む並列実行の設計はGrokマルチエージェント実装ガイドも参考になります。

最小推奨config（2026年9月版）

個人開発で最初に入れるなら、いきなりMCPや外部ゲートウェイまで足す必要はありません。モデル、UI、権限、セッション、CLI更新、機能フラグを、保守しやすい範囲でまとめます。以下は「まず動かす」よりも「事故りにくく運用する」ことを優先した最小構成で、値はすべて2026年9月27日時点の公式リファレンスにある既定値か公式例に合わせています。

# ~/.grok/config.toml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[models]
default = "grok-build"           # 公式Settings例の既定
web_search = "grok-4.7"          # クライアント側 web_search tool で使うモデル

[ui]
theme = "auto"                   # OSのライト・ダークに追従
auto_dark_theme = "tokyonight"
auto_light_theme = "grokday"
permission_mode = "ask"          # default | ask | auto | always-approve
show_thinking_blocks = true      # 既定 true
compact_mode = false             # 既定 false（/compact-mode でも切替）

[session]
auto_compact_threshold_percent = 85   # 既定 85
load_envrc = true                     # 既定 true

[cli]
auto_update = true               # 未設定時はオン
channel = "stable"               # stable | alpha
show_tips = true

[hints]
new_session_worktree_mode = "never"   # 既定 never
fork_worktree_mode = "ask"            # 既定 ask

[features]
web_fetch = true                 # 既定オフ（セキュリティ理由）
write_file = true                # 既定オン
tool_search = true               # 既定オン（大きなツールセットの逐次探索）
lsp_tools = false                # 既定オフ

[tools]
respect_gitignore = false        # 既定 false。true で検索・読み取りが gitignore を尊重

[subagents]
enabled = true

[memory]
enabled = false                  # 既定オフ

この構成で最も大事なのはpermission_modeです。設定リファレンスの値はdefault・ask・auto・always-approveの4つで、Permissionsページの既定はAsk（確認）です。検証環境でも最初からalways-approveにしないでください。Grok Buildはコーディングエージェントなので、ファイル編集やコマンド実行が絡みます。便利さより先に、どの操作を承認なしに通すかを設計します。

旧版の本記事から変えた点を挙げておきます。第1に、web_searchのモデルをgrok-4.3からgrok-4.7へ（公式Settings例の現行値）。第2に、[features] web_fetchは既定オフで、環境変数GROK_WEB_FETCH=1でも有効化できることを明記（「セキュリティ理由で既定オフ」と設定リファレンスに書かれています）。第3に、[tools] respect_gitignoreとshow_thinking_blocks・compact_modeを追加。第4に、旧版が[model."grok-4.3"]の例でcontext_window = 1000000と書いていた部分を、公式Settings例の500000（grok-4.7の例）へ直しました。context_windowはauto-compactの発動タイミングを決める値なので、実際より大きく書くと圧縮が遅れます。

load_envrc = trueは.envrcの変数をbashへ注入する設定です。direnvを使っているチームでは便利ですが、.envrcに秘密情報を置いている場合は扱いに注意してください。ローカルエージェントへ渡る環境変数は、ログやツール呼び出しの設計とセットで考える必要があります。

モデル設定｜default・web_search・api_backendとモデルの絞り込み

Grok Buildの設定で最も検索されやすいのがモデル設定です。[models]に全体の既定、[model.<id>]にモデルごとの定義を書きます。公式Settings例では[models].defaultにgrok-build、web_searchにgrok-4.7を置き、個別モデルを[model."grok-4.7"]のように定義しています。

設定	役割	備考
[models].default	新しいセッションで使うモデル	公式例はgrok-build
[models].web_search	クライアント側web_search toolのモデル	公式例はgrok-4.7
[models].default_reasoning_effort	既定モデルのreasoning effort	対応モデルのみ。/effortでも変更可
[models].session_summary／image_description	セッション要約・画像説明のモデル	用途別に安いモデルへ回せる
[models].allowed_models	モデルピッカー・既定・-mの選択肢をglobで制限	空なら無制限
[models].hidden_models	ピッカーから隠す（-mでは使える）	「見せたくないが禁止ではない」
[models].disabled_models	カタログから外す（hiddenより強い）	実質の禁止
[model.<id>].model	APIに送信される実モデルID	プロバイダの公式IDを使う
[model.<id>].name	モデルピッカーの表示名	modelと混同しない
base_url	プロバイダのエンドポイント	xAIならhttps://api.x.ai/v1
env_key／api_key	APIキーの読み方	env_keyを優先（api_keyは直書き）
api_backend	プロトコル	chat_completions／responses／messages
context_window	コンテキスト長	auto-compactの発動タイミングを決める
supports_backend_search	サーバー側検索ツールに対応するか	Grokホスト側の検索を使う場合
stream_tool_calls／max_retries／inference_idle_timeout_secs	通信の形と信頼性	BYOKエンドポイントはstream_tool_calls = falseが必要な場合あり

# ~/.grok/config.toml（xAI公式APIを使う例・公式Settings例に準拠）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[models]
default = "grok-build"
web_search = "grok-4.7"

[model."grok-4.7"]
model = "grok-4.7"
base_url = "https://api.x.ai/v1"
name = "Grok 4.7"
description = "Grok 4.7 from xAI"
env_key = "XAI_API_KEY"
api_backend = "responses"
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
context_window = 500000
supports_backend_search = true

# ~/.grok/config.toml（OpenAI互換の社内ゲートウェイを挟む例）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[model.my-gateway-code]
model = "provider/model-id"
base_url = "https://api.example.com/v1"
name = "Company Gateway Code Model"
env_key = "COMPANY_AI_GATEWAY_KEY"
stream_tool_calls = false        # 一部のBYOKエンドポイントで必要

[models]
default = "my-gateway-code"
allowed_models = ["my-gateway-code"]   # 社外モデルへの切り替えを塞ぐ

認証情報の解決順も覚えておくと、「どのキーが使われているのか分からない」を避けられます。Enterprise Deploymentsページによると、複数の資格情報があるときGrok Buildはモデル単位でmodel.api_key > model.env_key > 有効なセッショントークン > XAI_API_KEYの順に解決します。チームで共有する設定ファイルにAPIキーを入れるのは避け、env_keyに逃がしてください。

モデル設定でやりがちな失敗は、モデルIDと表示名の混同です。nameは人間がモデルピッカーで読む表示名、modelはAPIに送られるIDです。切り替えはTUI内の/model <name>やヘッドレス実行の-m、環境変数GROK_DEFAULT_MODELで行えますが、まずはgrok modelsで一覧を出し、grok -p "Hello" -m my-modelのように小さいプロンプトで疎通確認すると安全です。Grok 4.7をAPIやIDEから使う場合の実際はGrok 4.7をAPI・Copilot・Cursorで使うにまとめています。

権限設定｜ask・auto・always-approveの3モードとallow/deny

Grok Buildをチームで使うなら、権限設定が最重要です。2026年9月時点のモードは3種類あり、旧版で触れていなかったautoが加わっています（grok build auto modeへの直答）。評価順はdeny > ask > allowで、許可ルールを書いた後でも、より強いdenyがあればブロックできます。

モード	挙動	入り方
Ask（既定）	まだ許可していない操作はすべて確認する	—
Auto	分類器が安全なツールを自動承認。危険なものは確認が出ることがある（denyルールとhooksは有効）	/auto、機能が有効なときのShift+Tab
Always-approve	ツール呼び出しを自動承認（denyルールとPreToolUse hooksは有効）	/always-approve、Ctrl+O、Shift+Tab、grok --always-approve

Shift+TabはNormal → Plan → Auto（利用可能なとき）→ Always-approveの順に回ります。/autoはauto permission-mode機能が有効なときだけ現れ、always-approve中に/autoを実行すると（逆も同様に）モードが積み重なるのではなく切り替わります。Autoを既定にしたい場合のキーは次の2つです。

# ~/.grok/config.toml（プロジェクト側には置けない）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[auto_mode]
enabled = true            # Auto権限モードを使えるようにする

default_auto_mode = true  # セッション単位の指定がないとき Auto で始める

[ui]
permission_mode = "auto"  # default | ask | auto | always-approve

旧キーの互換も残っています。approval_modeとyolo = trueは今も動作し、複数が設定されているときはpermission_modeが勝ちます。古い手順書をそのまま使っているチームは、この機会にpermission_modeへ寄せておくと読みやすくなります。

allow／denyルールには2つの記法があります。コンパクト形（文字列配列）と、verbose形（action・tool・patternのオブジェクト配列）です。どちらもプロジェクト側の.grok/config.tomlに置けます。

# .grok/config.toml または ~/.grok/config.toml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[permission]
# コンパクト形
allow = [
  "Read(src/**)",
  "Read(package.json)",
  "Bash(npm test*)"
]
ask = [
  "Edit(src/**)",
  "Bash(git *)",
  "Bash(npm install*)"
]
deny = [
  "Bash(rm -rf *)",
  "Bash(sudo *)",
  "Read(.env*)",
  "Edit(.github/workflows/**)",
  "MCPTool(untrusted__*)"
]

# verbose形（同じ意味を明示的に書く）
rules = [
  { action = "allow", tool = "bash", pattern = "git *" },
  { action = "allow", tool = "read" },
  { action = "deny",  tool = "bash", pattern = "rm -rf *" },
]

コンパクト形で使えるフィルタはBash・Edit・Read・Grep・MCPTool・WebFetch・WebSearch、verbose形のtoolはany・bash・edit・read・grep・mcp・webfetchです。同じパターンはCLIの--allow／--denyでも1回の起動だけ指定できます。

ここで、公開ドキュメントには書かれていない挙動を1つ。同梱ガイドによると、[permission]ルールは優先順位で上書きされず、すべての設定ファイルを横断してマージされます。[mcp_servers]と[plugins]が「近いファイルが勝つ（置き換え）」なのに対し、権限は「足し算してからdeny > ask > allowで評価」です。つまりプロジェクト側にdenyを1行足せば、個人のallowを打ち消せます。チームの安全ルールをリポジトリに置く根拠になる挙動なので、権限設計の前提として押さえてください。

もう1つ実務的な差があります。Permissionsページによると、プロンプトで覚えさせた「always allow」の許可は、rmやgit pushのような危険なパターンではそれでも確認が出ます。設定やCLIで明示的にallowルールを書いた場合だけ自動承認されます。always-approve中はdenyを足さない限り走るので、denyを先に整えるのが順番です。AIエージェントの権限設計そのものはAIエージェントのガバナンス・権限設計、MCPツール側の安全表示はMCP Tool Annotationsの実装で扱っています。

CIやヘッドレス実行では、追加の2モードが効きます。dontAskは明示的なallowが無いものを黙って拒否、acceptEditsはファイル編集を自動承認してシェルコマンドだけ確認します。Enterprise Deploymentsページの例はそのまま使えます。

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
grok -p "Review the API changes" \
  --permission-mode dontAsk \
  --allow 'Bash(git *)' \
  --allow 'Bash(gh *)' \
  --allow 'Read' \
  --allow 'Grep' \
  --deny 'Bash(rm -rf *)' \
  --sandbox strict

組織としてalways-approveを封じるなら[ui] disable_bypass_permissions_mode = trueです。これは--yolo、--permission-mode bypassPermissions、セッション内のCtrl+O・/always-approve・Shift+Tab、クライアント側のyolo設定、*や**のような包括allowルールまで塞ぎます。ただし改ざん耐性のため、root所有のソース（/etc/grok/requirements.tomlかシステム層）からしか効きません。利用者が書ける~/.grok/requirements.tomlに書いても無視されます。Claude Codeのmanaged-settings.jsonにあるdisableBypassPermissionsModeはGrok側のalways-approveには適用されないので、両方を使う環境では必ずGrok自身のrequirements.tomlに書いてください。

Plan modeは権限モードとは独立しています。計画中は編集ツールが制限され、autoでもalways-approveでも計画レビュー画面はスキップされません。ただしPlan modeがゲートするのは編集ツールであってシェルではないため、bashのリダイレクトでは書き込めます。サブエージェントは親のPlan modeで編集を止められませんが、権限モード（autoやalways-approveを含む）は継承します。

UI・ステータスライン・セッション設定

UI設定は軽く見られがちですが、ターミナル常駐のコーディングエージェントでは生産性に直結します。Themingページの組み込みテーマは5種類で、truecolorが必要なものと不要なものが分かれています。

テーマ	指定名	truecolorが必要か
GrokNight（既定）	groknight／dark	不要
GrokDay	grokday／light／day	不要
TokyoNight	tokyonight／tokyo	必要
RosePineMoon	rosepine／rose-pine-moon	必要
OscuraMidnight	oscura／oscura-midnight	必要

チームドキュメントに書く推奨値はtheme = "auto"（別名system）が扱いやすいです。個人のターミナルでは暗色、画面共有では明色といった切り替えが起きるからで、OSの設定変更には再起動なしで数秒で追従します。細かい表示制御（スクロールバックのレイアウト、ブロックの見た目、アニメーション）は~/.grok/pager.tomlという別ファイルに寄るため、config.tomlだけで全部を解決しようとしないのがポイントです。

日々の見やすさに効く[ui]のキーを挙げます。compact_mode（既定false・/compact-modeでも切替）、screen_mode（fullscreen／minimal・再起動が必要）、show_timestamps（既定true）、show_timeline（既定false）、page_flip_on_send（既定true・送信したプロンプトを画面上端に固定）、max_thoughts_width（40〜500・既定120）、group_tool_verbs（既定true・読み取り系の連続行を1行に畳む）、collapsed_edit_blocks（既定false・編集を1行の差分要約にする）、render_mermaid（auto／on／off）、combine_queued_prompts（既定false）です。remember_tool_approvalsとhunk_tracker_modeは再起動が必要なので、変えたら一度落としてください。

grok build statuslineで探されるステータスラインは既定でオフです。[ui.status_line]のtypeで3通りに切り替わります。builtinはGrokが描く値、commandは自分のスクリプトの出力、disabledは非表示です。この節はユーザー自身の設定か管理者が配る設定からしか読まれません（クローンしたリポジトリがステータスラインを設定することはできません）。反映には再起動が必要です。

# ~/.grok/config.toml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[ui.status_line]
type = "builtin"
items = ["cwd", "model", "context"]   # 省略時の既定。列挙順に並ぶ

組み込み項目はcwd（現在のディレクトリ名）・model（表示名）・context（コンテキスト使用率。auto-compact閾値、報告がなければ80%で琥珀色になる）・cost（このプロセスの費用。0.005ドル未満は非表示。再開したセッションは再開時点から数える）・turn-timer（現在のターンの経過時間）・session-nameです。既定の3項目はmy-project │ Grok 4.5 │ 12% ctxのように描かれます。

自前スクリプトにする場合は、標準入力にJSONが1件届き、1行を出力する契約です。よく使うフィールドはmodel.display_name・context_window.used_percentage・workspace.branch・cwdで、取得できないフィールドは省かれるため、jqなら// "?"で欠損を必ずガードします。実行ビットを立てていないと[status line: could not start the script: …]と表示されます。

#!/bin/sh
# ~/.grok/statusline.sh （chmod +x を忘れないこと）
payload=$(cat)
model=$(printf '%s' "$payload" | jq -r '.model.display_name // "?"')
ctx=$(printf '%s' "$payload" | jq -r '.context_window.used_percentage // 0')
printf '%s │ %s%% ctxn' "$model" "$ctx"

# ~/.grok/config.toml
[ui.status_line]
type = "command"
command = "~/.grok/statusline.sh"
refresh_interval = 10   # command のときだけ有効。アイドル中も定期実行する

失敗時の表示は原因ごとに分かれています。何も出力せず失敗すると[status line: exit N]、タイムアウトは[status line: timed out]、シグナルで落ちたときは[status line: killed by signal]。標準エラーは表示されないため、読むには--debugを付けて起動します。grok inspectはこの節の問題も報告し、読めなかったキー名を出します。

セッション側は[session] auto_compact_threshold_percent（0〜100・既定85）とload_envrcの2つが主役です。長い作業ではコンテキスト圧縮が必要になりますが、圧縮のタイミングは作業の継続性に影響します。まずは既定に合わせ、会話が長くなりやすいリポジトリだけ調整するのが無難です。現在の使用率は/contextか/session-infoで見られます。

事例区分: 想定シナリオ
複数メンバーが同じリポジトリでGrok Buildを使う場合、UIテーマまでプロジェクト設定で縛る必要はありません（そもそもプロジェクト側には[ui]を置けません）。一方でpermission_modeやMCPの範囲は事故に直結します。個人の見た目と、チームの安全ルールを分離するのが現実的です。

プロジェクト設定・managed_config・requirements.tomlの使い分け

ユーザー設定とプロジェクト設定の境界を間違えると、Grok Buildのconfigは一気に分かりにくくなります。CLI同梱の設定リファレンスは、この3ファイルを「誰が書くか」で分けて説明しています。

ファイル	書く人	置き場所	用途
config.toml	開発者本人	~/.grok/config.tomlとリポジトリの.grok/config.toml	個人の既定値。端末の利用者がいつでも変えられる
managed_config.toml	組織（コンソールや配布ツール経由）	/etc/grok/managed_config.toml、$GROK_HOME/managed_config.toml	出発点を配る。開発者のファイルが優先される
requirements.toml	組織（署名つき）	/etc/grok/requirements.toml、macOSのデバイス管理、$GROK_HOME/requirements.toml	開発者が変えられない値。pin指定は他のどのファイル・環境変数・コマンドラインより強い

プロジェクト設定で書けるのは[mcp_servers]・[plugins]・[permission]・[mcp] max_output_bytesの4つだけです。ただし.grok/ディレクトリ自体はもっと多くを運べます。

ファイル・ディレクトリ	設定する対象
.grok/config.toml	MCPサーバー、plugins、権限ルール、MCP出力の上限
.grok/skills/	プロジェクト固有のskill（SKILL.md）
.grok/hooks/	プロジェクト固有のライフサイクルhooks（信頼が必要）
.grok/agents/／.grok/personas/*.toml	サブエージェントの型とペルソナ
.grok/workflows/*.rhai	バックグラウンドワークフロー
.grok/lsp.json	LSPサーバー（プロジェクトがユーザーより優先）
.grok/sandbox.toml	カスタムサンドボックスプロファイル
AGENTS.md（.grok/rules/*.md）	プロジェクト指示。CLAUDE.md・.cursor/rules/も互換で読まれる

プロジェクト指示の探索順は、~/.grok/のグローバルルール → リポジトリルートから作業ディレクトリまでの各階層で、深いファイルが競合時に勝ちます。各階層でAGENTS.md・Agents.md・AGENT.md・CLAUDE.md・Claude.md・CLAUDE.local.mdと.grok/rules/配下の*.mdが読まれ、.gitignoreで無視されるファイルはスキップされます（CLAUDE.local.mdのような個人の上書きが共有コンテキストに混ざらない設計です）。サイズ上限はありませんが、短く具体的な指示のほうが確実に守られると公式に明記されています。1回だけルールを足したいときは--rules、システムプロンプトを丸ごと差し替えるなら--system-prompt-overrideです。

組織側の層は、managed_config.tomlが「変えてよい既定値」、requirements.tomlが「変えさせない値」です。設定リファレンスの表にはキーごとにRequirements列（pin／yes）とManaged列（fleet／user／—）が付いており、どのキーがどちらで効くかを1件ずつ引けます。例外は1つで、features.remote_fetchだけはmanagedの値が開発者の値に勝ちます。requirements専用のキーも3つあります。

キー	意味
fail_closed（既定false）	署名済みrequirementsやversion_overridesを適用できないときに起動を拒否する
features.image_edit	画像編集の可否をpinする（ユーザーファイルに書いても認識されない）
ui.disable_bypass_permissions_mode	always-approveを封じる。requirements層からしか効かない

# /etc/grok/requirements.toml の考え方例
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 組織で上書き不可にしたい設定だけを書く

fail_closed = true

[ui]
permission_mode = "ask"
disable_bypass_permissions_mode = true

[cli]
channel = "stable"
required_minimum_version = "1.0.30"   # 自社で承認した下限へ置き換える（値は例）

[features]
web_fetch = false

[sandbox]
profile = "workspace"

[permission]
deny = [
  "Bash(sudo *)",
  "Read(.env*)",
  "Bash(rm -rf *)"
]

allow_managed_hooks_only = true

設定が拒否されたときの挙動も表になっています。開発者がpin済みのキーを書いた場合はpinの値が適用され、grok inspectにどのrequirementsファイルが寄与したか出ます。requirements.tomlが無い、または署名が検証できない場合はpinが適用されないまま起動します——ここを締めるのがfail_closed = trueです。pinしたキーがそのバージョンで認識されない値だった場合は、そのキーだけ無視され残りのファイルは有効になります。「この権限がなぜ許可されないのか」を説明できる状態にしてから配布してください。

ネットワーク要件も配布前に確認する項目です。Enterprise Deploymentsページによると、コア機能に必須なホストはcli-chat-proxy.grok.com（推論プロキシと設定）とauth.x.ai（OAuth2／OIDC認証）の2つだけで、いずれもHTTPS（443）です。x.aiとstorage.googleapis.comはシェルスクリプト版インストーラとgrok updateだけに必要なので、npm配布（npm install -g @xai-official/grok）にすれば開けずに済みます。TLSは1.2／1.3でrustlsが強制し、無効化するオプションはありません。TLSインスペクションのプロキシを挟む環境では、プロキシのCA証明書をOSのトラストストアへ入れます。SSEストリーミングの1チャンクあたりアイドルタイムアウトは既定600秒なので、プロキシのアイドルタイムアウトは10分以上にしておかないと長い応答の途中で切れます。

事例区分: 想定シナリオ
情シス部門がGrok Buildを開発者端末へ配布する場合、全員のUIやテーマまで統一するより、秘密情報の読み取り、危険なシェル操作、外部通信ツールの扱い、always-approveの封鎖をrequirementsで固定するほうが効果的です。開発体験の自由度を残すほど、現場の反発も小さくなります。

バージョン更新の制御｜auto_updateと4つのバージョン境界

grok build 更新で効くのは[cli]の数キーです。単に自動更新を止めるだけならauto_update = false、チャンネルを固定するならchannel（stable／alpha）ですが、2026年9月時点では4つのバージョン境界が使えます。ここが旧版にまったく無かった部分です。

# ~/.grok/config.toml または managed_config.toml / requirements.toml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[cli]
auto_update = true
channel = "stable"
minimum_version = "1.0.30"           # 更新器がこれより下へは下げない（値は例）
maximum_version = "1.0.41"           # 更新器がこれより上を入れない（値は例）
required_minimum_version = "1.0.20"  # これより下では起動しない（値は例）
required_maximum_version = "1.0.50"  # これより上では起動しない（値は例）

キー	環境変数	効き方
minimum_version	GROK_MINIMUM_VERSION	ソフトな下限。更新器はこれより低い対象を飛ばし、現バージョンを維持する。起動は止めない
maximum_version	GROK_MAXIMUM_VERSION	ソフトな上限。更新器は対象をここで打ち止めにする
required_minimum_version	GROK_REQUIRED_MINIMUM_VERSION	ハードな下限。範囲外なら起動時に終了し、承認済みバージョンの導入を促す
required_maximum_version	GROK_REQUIRED_MAXIMUM_VERSION	ハードな上限。同じく起動を止める

同梱ガイドには「変更点」として、minimum_versionはもう起動をブロックしないと明記されています。古いバージョンの起動そのものを止めたいならrequired_minimum_versionです。ここを混同したまま「下限を入れたから安心」と思っているチームが一番危ないので、設定を棚卸しするときに必ず確認してください。境界は層をまたぐと締める方向にだけ解決されます（下限は最も高い値、上限は最も低い値を採用）。managedの境界は緩められず、ユーザーや環境変数の値が組織のハード境界を打ち消すこともできません。無効な値は無視されるので、設定ミスで起動不能になることはありません。範囲外のインストールから復帰できるよう、grok updateとgrok --versionは動き続け、明示的なgrok update --version Xは上限より上でも許可されます（ハード下限より下は拒否）。

CIやコンテナでは更新チェック自体が邪魔になります。環境変数GROK_DISABLE_AUTOUPDATERを設定すればそのプロセスの自動更新が抑止され、ヘッドレス（-p）やACP（grok agent stdio）では--no-auto-updateが使えます。手動更新はgrok updateで、--check（確認のみ）・--version <V>・--alpha・--stableを取ります。バージョン条件付きの設定パッチを配る[[version_overrides]]も全層で使えます。

「いま自分の環境はどの版か」を判断する材料についても書いておきます。公式changelogはx.ai/build/changelogですが、2026年9月27日の当方の環境からはCloudflareにより403で取得できませんでした。したがって版ごとの日付は本記事では一次情報として扱いません。一次的に確認できる範囲では、OSSミラーxai-org/grok-buildはApache-2.0で公開され、GitHub APIの値で最終pushは2026年9月23日、ルートのSOURCE_REVは036a5d8348cd744767cd0b08518ab17bf608fa7f、crates/codegen/xai-grok-shellのversionは1.0.41です。版番号が1.0.x系であることはここから確認できます（第三者のリリース集約サイトでは1.0.40が2026年9月20日でGrok 4.7対応とされていますが、これは公式一次情報ではありません）。自分の端末ではgrok versionと/release-notes（別名/changelog）で確認するのが確実です。

サンドボックス設定｜権限との役割分担

権限とサンドボックスは別物です。権限はツール呼び出しを実行してよいかを決め、サンドボックスは承認された呼び出しがファイルシステムとネットワークに何をできるかを制限します。実装はLinuxがLandlock、macOSがSeatbeltで、既定はオフです。旧版にはこの節がありませんでした。

プロファイル	読み取り	書き込み	子プロセスの通信	用途
off	無制限	無制限	許可	既定（サンドボックスなし）
workspace	全域	カレント、~/.grok/、一時領域	許可	通常の開発
devbox	全域	/data以外のトップレベル	許可	クラウドのdevbox環境
read-only	全域	~/.grok/と一時領域のみ	遮断	コードレビュー、監査
strict	カレントとシステムパス	カレント、~/.grok/、一時領域	遮断	信頼できないリポジトリ

制限事項を公式が明記しているので、そこも押さえます。子プロセスの通信遮断はLinuxでのみ強制され、macOSのread-only／strictでは効きません。組み込みプロファイルは~/.sshのような資格情報パスを恒久的に守るわけではないため、カスタムのdenyリストが必要です。~/.grok/はセッションを保存するためサンドボックス下でも書き込み可能なままです。モデルAPIとWeb系ツールは、子プロセスの通信設定では遮断されません。

# ~/.grok/sandbox.toml または .grok/sandbox.toml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

[profiles.project]
extends = "workspace"      # workspace | devbox | read-only | strict
restrict_network = false
read_only = ["/data"]
read_write = ["/tmp/scratch"]
# カーネルで強制するdeny（読み取りと書き込み・リネーム）。* ? [ を含む要素はグロブ
deny = ["/data/shared-secrets", "**/.env", "**/*.pem"]

有効化は4通り——CLIのgrok --sandbox workspace、config.tomlの[sandbox] profile、環境変数GROK_SANDBOX、requirements.tomlでのpin（CLIより強い）です。組み込み名（off・workspace・read-only・strict・devbox）はカスタムプロファイル名として再定義できません。空でないdenyリストはサンドボックスを適用できる環境でカーネルレベルで強制され、Linuxで読み取りをdenyするにはbubblewrapが必要です。サンドボックス内でbashの確認を省きたい場合は[sandbox] auto_allow_bash = true（既定false）かGROK_SANDBOX_AUTO_ALLOW_BASH=1ですが、これは「サンドボックスが効いているから確認を省く」という設計判断なので、プロファイルが本当に適用されているかを先に確認してください。信頼できないツリーにはstrictプロファイルと狭いallow（またはヘッドレスのdontAsk）を組み合わせるのが公式の推奨です。

設定キーの一次情報を手元で引く｜grok inspectと同梱リファレンス

grok build docsで探している「設定キーの完全な一覧」は、実はWebだけを探しても見つかりません。CLIに同梱されていて、起動時に~/.grok/docs/user-guide/26-config-reference.mdへ展開されます。これがconfig.toml・managed_config.toml・requirements.tomlの全フィールド表の正本で、概念的な説明は同じディレクトリの05-configuration.mdです。

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 同梱ドキュメントの場所（起動後に展開される）
ls ~/.grok/docs/user-guide/

# キー名で引く（例: status_line のキーを探す）
grep -n "status_line" ~/.grok/docs/user-guide/26-config-reference.md

# 環境変数を GROK_ で総当たりする
grep -n "GROK_" ~/.grok/docs/user-guide/26-config-reference.md

# いま効いている値と、寄与したファイルを見る
grok inspect --json

同じ2本はOSSミラーでも読めます（xai-org/grok-buildのcrates/codegen/xai-grok-pager/docs/user-guide/配下）。Apache-2.0で、GitHub APIの値ではstar 27,117・作成2026年7月14日・最終push 2026年9月23日です。CLIを入れる前に設定方針を決めたい情シス担当者は、こちらを先に読むほうが早いでしょう。

ただし2つの情報源で役割を分けてください。キーの有無・型・pin可否・managedの効き方は同梱リファレンス（ミラーのツリーは定期同期なので、手元のCLIに展開されたものが自分の版の正本）、推奨値とモデル名の現行値はdocs.x.aiです。実際、同梱ガイドの例はdefault = "grok-4.5"のままですが、docs.x.ai のSettings例はweb_search = "grok-4.7"になっています。例の値をそのままコピーすると古いモデルを指してしまうので、モデルIDは公式ドキュメントかgrok modelsで確認するのが安全です。

【要注意】よくある失敗パターンと回避策

失敗1：プロジェクト設定に何でも入れてしまう

❌ よくある間違い: .grok/config.tomlにモデル、UI、APIキー、個人用MCPまで全部入れる。

⭕ 正しいアプローチ: プロジェクト設定が出せるのは[mcp_servers]・[plugins]・[permission]・[mcp] max_output_bytesの4つだけ。個人の標準モデルやUIは~/.grok/config.tomlへ置く。

なぜ重要か: チーム全員のローカル環境をリポジトリ設定で縛ると、デバッグが難しくなります。特にモデルやAPIキーは人によって契約・権限・ゲートウェイが違うため、共有すると破綻しやすいです。

失敗2：APIキーをTOMLへ直書きする

❌ よくある間違い: extra_headersやapi_keyに本物のAPIキーを直接書き、そのままGit管理する。

⭕ 正しいアプローチ: env_key、MCPならbearer_token_env_varや${LINEAR_API_KEY}のような環境変数参照を使う。リポジトリには秘密情報を置かない。

なぜ重要か: Grok Buildの設定は便利なぶん、MCPやゲートウェイの認証情報に近い場所です。秘密情報がGitに入ると、AIエージェント以前のセキュリティ事故になります。

失敗3：always-approveを標準にする

❌ よくある間違い: 承認ダイアログが面倒なので、全員にpermission_mode = "always-approve"を推奨する。

⭕ 正しいアプローチ: 既定のAskか、分類器が安全な操作だけ通すAuto（[auto_mode] enabled = true）にする。読み取りやテスト実行など低リスク操作だけallowし、編集・git・依存追加はaskに残す。

なぜ重要か: AIエージェントは高速に作業します。危険な操作だけ人間が止められる設計が必要です。承認を消すなら、その前にdenyルールとPreToolUse hooksを整えてください。

失敗4：MCPサーバー名の衝突を見落とす

❌ よくある間違い: ユーザー設定とプロジェクト設定の両方で同じMCP名を使い、どちらが効いているか分からなくなる。

⭕ 正しいアプローチ: プロジェクトMCPにはproject_docs、repo_filesystemのように用途が分かる名前を付け、変更後はgrok inspectで出所を確認する。

なぜ重要か: 同名のプロジェクトサーバーはユーザーサーバーを完全に置き換えます（マージではありません）。名前の衝突は権限範囲の誤解につながります。

失敗5：hooksをJSONファイルの中だけ探す

❌ よくある間違い: ~/.grok/hooks/*.jsonを見て「hookは設定されていない」と結論づける。

⭕ 正しいアプローチ: config.toml・managed_config.toml・requirements.tomlの[[hooks.<Event>]]、ClaudeとCursorの互換ファイル、pluginのhooksまで含めてgrok inspectと/hooksで一覧する。

なぜ重要か: 設定ファイル由来のhooksは出所ラベル（managed:・requirements/signed:・user:など）が付いて/hooksに並びます。プロジェクトhooksは/hooks-trustまで黙って走らないので、「動かない」の切り分けにも必要です。

失敗6：MCPタイムアウトの単位を混同する

❌ よくある間違い: MCP_TIMEOUT=30と書いて「30秒」だと思い込む。

⭕ 正しいアプローチ: GROK_MCP_STARTUP_TIMEOUT_SECSは秒、Claude互換のMCP_TIMEOUTはミリ秒。サーバー単位で確実に効かせたいなら[mcp_servers.<name>] startup_timeout_secを書く。

なぜ重要か: MCP_TIMEOUTのほうが先に評価されるため、ミリ秒の小さい値を入れると初回にnpxでパッケージを取得するサーバーが必ずハンドシェイクに失敗します。

失敗7：minimum_versionで起動を止めたつもりになる

❌ よくある間違い: [cli] minimum_versionを配って「古い版は起動できない」と社内に告知する。

⭕ 正しいアプローチ: 起動を止めるのはrequired_minimum_version。minimum_versionは更新器の下限（アンチダウングレード）で、起動はブロックしない。

なぜ重要か: 同梱ガイドに「変更点」として明記された挙動です。古い前提の手順書が残っていると、脆弱性対応の下限が実際には効いていない状態になります。

よくある質問

Grok Buildの設定ファイルはどこにありますか？

個人設定は~/.grok/config.toml（$GROK_HOMEを設定している場合は$GROK_HOME/config.toml、Windowsは%USERPROFILE%.grokconfig.toml）です。リポジトリ側は.grok/config.tomlで、書けるのは[mcp_servers]・[plugins]・[permission]・[mcp] max_output_bytesの4つだけです。組織配布はmanaged_config.tomlとrequirements.tomlで、TUIの見た目だけは~/.grok/pager.tomlという別ファイルです。実際にどのファイルが読まれたかはgrok inspectで一覧できます。

grok buildでMCPサーバーを追加する一番早い方法は？

grok mcp add <name> -- <起動コマンド>です。リモートはgrok mcp add --transport http <name> <URL>で、OAuthは初回にブラウザが開き、トークンは~/.grok/mcp_credentials.jsonに保存されます。リポジトリに同梱するなら--scope projectを付けるとカレントディレクトリに.grok/config.tomlが書かれます。追加後はgrok mcp listとgrok mcp doctor（どちらも--json可）で確認してください。

hooksはconfig.tomlに書けますか？

書けます。~/.grok/config.toml・managed_config.toml・requirements.tomlの3ファイルで[[hooks.<Event>]]が有効なキーです。JSONファイル（~/.grok/hooks/*.json、<project>/.grok/hooks/*.json）と構造は同一で、両方が加算的にマージされます。ただしプロジェクトのhooksは/hooks-trustか--trustで信頼するまで黙ってスキップされます。

grok buildのgoalとは何ですか？

TUIの/goalコマンドと、それを有効にする[goal] enabledという設定キーのことです。2026年9月27日時点でdocs.x.ai には/goalの記述がなく、CLI同梱ドキュメントにだけ説明があります。/goalの駆動方式は[workflows] enabled（既定オン・GROK_WORKFLOWS=0でも切れる）で切り替わり、有効ならホスト側のワークフローエンジンがラウンド評価と完了検証を行い、無効ならモデル側のupdate_goalツールにフォールバックします。

auto modeはどうやって有効にしますか？

[auto_mode] enabled = trueで使えるようにし、既定モードにするなら[ui] permission_mode = "auto"またはdefault_auto_mode = trueです。いずれもユーザー設定側（~/.grok/config.tomlかmanaged／requirements）に書き、プロジェクトの.grok/config.tomlには置けません。セッション中の切り替えは/autoかShift+Tabで、denyルールとPreToolUse hooksはAuto中も有効です。

grok buildのモデルは何が既定で、どう切り替えますか？

公式Settings例では[models] default = "grok-build"、web_search = "grok-4.7"です。切り替えはTUIの/model <name>、CLIの-m／--model、環境変数GROK_DEFAULT_MODEL。一覧はgrok modelsで出ます。選べる範囲を絞るならallowed_models（glob許可リスト）、ピッカーから隠すだけならhidden_models、カタログから外すならdisabled_modelsを使い分けます。

設定キーの全一覧はどこで読めますか？

CLIに同梱されていて、起動時に~/.grok/docs/user-guide/26-config-reference.mdへ展開されます。config.toml・managed_config.toml・requirements.tomlの全フィールドが、pin可否とmanagedの効き方つきで表になっています。概念説明は同じディレクトリの05-configuration.mdで、どちらもOSSミラーのcrates/codegen/xai-grok-pager/docs/user-guide/配下でWebからも読めます。Web側の入門はSettings Referenceです。

Grok Buildの自動更新を止めたり、バージョンを固定できますか？

できます。[cli] auto_update = falseで自動更新を止め、channelでstable／alphaを選びます。バージョン境界は4つあり、minimum_versionとmaximum_versionは更新器へのソフトな境界（起動は止めません）、required_minimum_versionとrequired_maximum_versionは範囲外で起動を拒否するハードな境界です。CIではGROK_DISABLE_AUTOUPDATERか--no-auto-updateを使います。

Grok Buildの料金はいくらですか？

本記事は設定ファイルの扱いに限定しているため、金額は載せていません。プラン別の枠と無料枠の考え方はGrok Buildは無料で使える？無料枠の上限と料金プラン比較にまとめています。自分のアカウントの消費状況は、TUIの/usageで確認できます。

運営元 Uravation よりAIエージェントを構想から本番運用まで進める順番と、体制・KPIの決め方をまとめた資料を無料で公開しています。 AIエージェント導入ロードマップを受け取る（無料）

参考・出典

• Settings – xAI Docs — configの保存場所、5スコープ表、grok inspect、公式config.toml例（web_search = "grok-4.7"・context_window = 500000）を確認（参照日: 2026-09-27）
• Settings Reference – xAI Docs — 環境変数一覧と[models]・[model.<id>]・[mcp_servers]・[permission]・[ui]・[sandbox]・[features]の全キー、プロジェクト設定が出せる3セクションを確認（参照日: 2026-09-27）
• MCP Servers – xAI Docs — grok mcp add/list/remove/doctor、--transport http、${VAR}展開、--scope projectの完全置き換え、互換読み込み、stderrログの場所を確認（参照日: 2026-09-27）
• Hooks – xAI Docs — hooksのJSON形式、matcher、type、既定timeout 5秒、イベント表、fail-open、/hooks-trustとtrusted_folders.tomlを確認（参照日: 2026-09-27）
• Permissions – xAI Docs — Ask／Auto／Always-approveの3モード、Shift+Tabの巡回順、permission_modeはユーザー設定のみ、approval_mode／yoloの互換、コンパクト／verboseのルール記法を確認（参照日: 2026-09-27）
• Sandbox – xAI Docs — 5プロファイルの権限表、Landlock／Seatbelt、Linux限定の通信遮断、sandbox.tomlのカスタムプロファイルを確認（参照日: 2026-09-27）
• Status Line – xAI Docs — [ui.status_line]のtype3種、組み込み項目6種、スクリプト契約とエラー表示、refresh_intervalを確認（参照日: 2026-09-27）
• Skills, Plugins & Marketplaces – xAI Docs — skills／pluginsの探索先、SKILL.mdのfrontmatter、[[marketplace.sources]]、Claude Code・AGENTS.md互換を確認（参照日: 2026-09-27）
• AGENTS.md – xAI Docs — プロジェクト指示の探索順、読まれるファイル名、.gitignoreの扱い、--rules／--system-prompt-overrideを確認（参照日: 2026-09-27）
• Background Tasks – xAI Docs — /loopの間隔指定（Nsは最小60）、7日で期限切れ、同時50件の上限を確認（参照日: 2026-09-27）
• Modes and Commands – xAI Docs — Plan／Auto／Always-approveの入り方、コマンド表、/create-workflowと.grok/workflows/*.rhai、[workflows] enabled = falseを確認（参照日: 2026-09-27）
• Enterprise Deployments – xAI Docs — 5層の設定優先順位、必須2ホスト、TLSとプロキシのアイドル要件、認証4方式と解決順、dontAsk／acceptEdits、disable_bypass_permissions_modeを確認（参照日: 2026-09-27）
• CLI Reference – xAI Docs — grok inspect／models／mcp／updateの各サブコマンドと共通フラグ、Claude Code互換のフラグ別名を確認（参照日: 2026-09-27）
• Headless & Scripting – xAI Docs — -pと出力形式3種、--no-auto-update、[cli] auto_update = false、ACPのgrok agent stdioを確認（参照日: 2026-09-27）
• Grok Build – xAI Docs — インストール、ヘッドレス実行、カスタムモデル設定、grok inspect、/model切り替えを確認（参照日: 2026-09-27）
• xai-org/grok-build（GitHub・Apache-2.0） — CLI同梱ドキュメントcrates/codegen/xai-grok-pager/docs/user-guide/05-configuration.md（8層の優先順位・GROK_CONFIGオーバーレイの許可リスト・[permission]のマージ規則・/goalの2ドライバ・バージョン境界4種・dotfilesのシンボリックリンク挙動）、26-config-reference.md（全キー表・[goal] enabled・[auto_mode] enabled・requirements専用3キー）、10-hooks.md（[[hooks.<Event>]]のTOML形式・15イベント・enforced hooks・allow_managed_hooks_only）を確認（参照日: 2026-09-27。SOURCE_REV 036a5d8348cd744767cd0b08518ab17bf608fa7f・最終push 2026-09-23）
• Grok Build Changelog – xAI — 版ごとの変更履歴の公式ページ。2026-09-27に当方の環境からはCloudflareにより403で取得できず、本記事では版ごとの日付を一次情報として採用していない
• Grok Build – Vercel AI Gateway Docs — ゲートウェイ経由での環境変数、[models].default、Responses系モデルの設定例を確認（参照日: 2026-09-27）

まとめ：今日から始める3つのアクション

Grok Buildのconfig.tomlは、全部を詰め込むファイルではなく、誰が書くファイルなのかで役割を分けるための設定です。個人設定は~/.grok/config.toml、リポジトリ共有は.grok/config.tomlの4項目だけ、組織の強制ポリシーはrequirements.toml。この分離ができていれば、モデル、MCP、hooks、権限、skills／pluginsを増やしても破綻しにくくなります。2026年9月時点で押さえ直すべき点は3つ——hooksはTOMLに書ける、[permission]は層をまたいでマージされる（MCPは置き換え）、起動を止める下限はrequired_minimum_versionです。

1. 今日やること: この記事の最小推奨configを~/.grok/config.tomlに入れ、grok inspect --jsonでどのファイルのどの値が勝ったかを確認する。
2. 今週中にやること: チームリポジトリで共有すべきMCPと[permission]ルールだけを.grok/config.tomlに分離し、denyを先に書く。
3. 次の運用でやること: ~/.grok/docs/user-guide/26-config-reference.mdを開いて、自社で固定したいキーのRequirements列とManaged列を確認し、requirements.tomlの草案を作る。

あわせて読みたい:

• Grok Buildの使い方完全ガイド — CLI、ヘッドレス実行、並列エージェントの全体像を確認したい方向け
• Grok Buildは無料で使える？無料枠の上限と料金プラン比較 — プランと枠から導入判断をしたい方向け
• Grok 4.7をAPI・Copilot・Cursorで使う — モデル設定に書くIDと使い分けを確認したい方向け
• Grok Build vs Claude Code徹底比較 — 既存のAIコーディング環境と比べて導入判断したい方向け
• Grokエージェント完全ガイド — Grok Agent全体の使い方・切り替え・カスタム設定を俯瞰したい方向け
• MCPサーバーのデバッグ方法 — 追加したMCPが繋がらないときの切り分け手順
• AIエージェント ガバナンス・権限設計2026 — チーム導入時の承認・監査・権限設計を深掘りしたい方向け

---

著者: 佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』。

このテーマの関連記事

• ▸ 【2026年10月】LM Studio Bionicの日本語化｜設定と注意点
• ▸ n8n AI Agent入門｜ノード基本編【2026年10月】
• ▸ LangGraph MCP連携3手順【2026年10月4日】
• ▸ ローカルLLM×RAGの作り方｜オフライン実装【2026年10月】
• ▸ LangGraph Studioの使い方｜可視化・デバッグ【2026年10月】