【2026年最新】Grok Build設定config完全ガイド

「Grok Buildを入れたけど、どの設定をどこに書けばいいのか分からない」。先日、開発チームの検証環境を整えているときに、まさにこの相談が出ました。Grok BuildはTUIでかなりの設定を変更できますが、チームで再現したい設定、モデルルーティング、MCP、権限ルールは、やはりconfig.tomlとして管理したくなります。

実際に構築してみると、詰まりやすいのは「TOMLの書き方」そのものではありません。どのスコープに書くべきか、プロジェクト設定で効く項目と効かない項目は何か、APIキーをファイルに直書きしてよいのか、MCPをユーザー設定とリポジトリ設定のどちらに置くべきか。このあたりで手が止まるんです。

正直に言うと、Grok Buildは2026年5月25日にxAIが早期ベータとして発表した新しいCLIコーディングエージェントなので、設定まわりの情報はまだ流動的です。この記事では2026年7月8日にxAI公式ドキュメント、xAI公式ニュース、Grok Build changelog、Vercel AI Gatewayの公式ドキュメントで確認できた範囲だけを扱います。確認できない設定名や、SNSで見かけただけのキーは入れません。

この記事では、Grok Buildのconfig.tomlでカスタマイズできる項目を、コピペできる設定例つきで整理します。Grokエージェント全体の概念から確認したい方は、先にGrokエージェント完全ガイドを読むと全体像がつかみやすいです。Grok Buildそのものの使い方はGrok Buildの使い方完全ガイドでもまとめています。

Grok Buildのconfig.tomlで設定できる範囲

Grok Buildの設定は、単一ファイルだけで完結するというより、スコープごとに役割を分ける設計です。xAI DocsのSettingsページでは、環境変数、ユーザー設定、プロジェクト設定、managed config、requirementsのスコープが示されています。ここを最初に理解しておくと、後で「書いたのに効かない」をかなり減らせます。

スコープ	主な場所	使いどころ	注意点
環境変数	GROK_*など	CIや一時的な上書き、APIキー注入	シェルやCIごとに反映範囲が変わる
ユーザー設定	~/.grok/config.toml	個人の標準モデル、UI、権限、MCP	チームで共有する設定は混ぜすぎない
GROK_HOME指定時	$GROK_HOME/config.toml	複数環境の切り替え、検証用ホーム	どのホームを見ているかgrok inspectで確認する
プロジェクト設定	.grok/config.toml	リポジトリ共有のMCP、plugins、権限ルール	公式上、フルユーザー設定の置き場ではない
requirements	~/.grok/requirements.toml、/etc/grok/requirements.toml	組織の強制ポリシー、監査要件	下位レイヤーでは上書きできない前提で設計する

ポイントは、.grok/config.tomlを「リポジトリに置ける全部入り設定」と考えないことです。公式ドキュメントでは、プロジェクト設定はMCPサーバー、plugins、permission rulesに限定されると説明されています。モデルのデフォルトやUIの好み、個人のAPIキー周辺は、基本的にユーザー設定や環境変数に置くのが安全です。

また、Grok Buildがどの設定を読み込んでいるかは、公式が案内しているgrok inspectで確認できます。設定変更後にTUIを何度も再起動して悩むより、まずinspectで「どのconfig sourceが見えているか」を確認するほうが早いです。

# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# Grok Buildが検出している設定ソース、instructions、skills、plugins、hooks、MCPなどを確認
grok inspect

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

最小推奨config：まずここから始める

個人開発で最初に入れるなら、いきなりMCPや外部ゲートウェイまで足す必要はありません。モデル、UI、権限、セッション、CLI更新、機能フラグを、保守しやすい範囲でまとめます。以下は「まず動かす」よりも「事故りにくく運用する」ことを優先した最小構成です。

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

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

[ui]
theme = "auto"
auto_dark_theme = "tokyonight"
auto_light_theme = "grokday"
permission_mode = "ask"

[session]
auto_compact_threshold_percent = 85
load_envrc = true

[cli]
auto_update = true
channel = "stable"
show_tips = true

[hints]
new_session_worktree_mode = "never"
fork_worktree_mode = "ask"

[features]
web_fetch = true
write_file = true
tool_search = true
lsp_tools = false

[subagents]
enabled = true

[memory]
enabled = false

この設定で大事なのは、permission_mode = "ask"です。xAI DocsのModes and Commandsでは、permission_modeはaskまたはalways-approveを設定でき、デフォルトはaskとされています。検証環境でも、最初からalways-approveにしないほうがよいです。Grok Buildはコーディングエージェントなので、ファイル編集やコマンド実行が絡みます。便利さより先に、どの操作を承認なしに通すかを設計してください。

auto_compact_threshold_percent = 85は、公式リファレンスで確認できるセッション設定です。長い作業ではコンテキスト圧縮が必要になりますが、圧縮のタイミングは作業の継続性に影響します。まずは公式デフォルトに合わせ、実運用で会話が長くなりやすいリポジトリだけ調整するのが無難です。

lsp_tools = falseは、最初の構成では保守的にしています。公式リファレンスではLSP toolは設定項目として示されていますが、リポジトリの言語サーバー、エディタ連携、チームの開発環境に依存します。導入時は「必要になったら有効化」で十分です。

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

モデル設定：default、web_search、custom modelを分ける

Grok Buildの設定で最も検索されやすいのがモデル設定です。xAI DocsのSettings例では、[models]にdefaultとweb_searchを置き、個別モデルを[model."grok-4.3"]のように定義しています。さらにOverviewでは、ユーザー設定の~/.grok/config.tomlにカスタムモデルを追加できると説明されています。

設定	役割	推奨
[models].default	通常のエージェント作業で使うモデル	コード作業なら公式例に沿ってgrok-buildから開始
[models].web_search	クライアント側web_search toolで使うモデル	公式例ではgrok-4.3
[model.<name>].model	APIに送信される実モデルID	プロバイダの公式IDを使う
base_url	プロバイダのエンドポイント	xAIならhttps://api.x.ai/v1、ゲートウェイ利用時は各公式URL
env_key	APIキーを読む環境変数名	秘密情報をTOMLに直書きせず環境変数へ逃がす
api_backend	APIバックエンド種別	公式例ではresponses、選択肢はchat_completions、responses、messages

まずは公式例に近い形で、xAI APIキーを環境変数から読む構成にします。extra_headersに秘密情報を直接書ける場面はありますが、通常はenv_keyのほうが安全です。チームで共有する設定ファイルにAPIキーを入れるのは避けてください。

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

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

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

次に、OpenAI互換の社内ゲートウェイや別プロバイダを挟む場合です。xAI DocsのOverviewでは、[model.my-model]にmodel、base_url、name、env_keyを定義し、[models].defaultで選ぶ例が示されています。この形を使えば、モデルピッカーに表示する名前と、実際にAPIへ送るモデルIDを分離できます。

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

[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"

[models]
default = "my-gateway-code"

モデル設定でやりがちな失敗は、モデルIDと表示名を混同することです。nameは人間がモデルピッカーで読む表示名、modelはAPIに送られるIDです。切り替えはTUI内の/model <name>やヘッドレス実行の-mで行えますが、まずはgrok -p "Hello" -m my-modelのように小さいプロンプトで疎通確認すると安全です。

UIとセッション設定：毎日使う体験を安定させる

UI設定は軽く見られがちですが、ターミナル常駐のコーディングエージェントでは生産性に直結します。xAI DocsのThemingページでは、[ui]のthemeにtokyonightなどを設定する例や、theme = "auto"でOSのライト・ダークに追従する例が示されています。

テーマは好みでよいのですが、チームドキュメントに書く推奨値はautoが扱いやすいです。個人のターミナルでは暗色、社内デモや画面共有では明色、といった切り替えが起きるからです。細かい表示制御は~/.grok/pager.tomlに寄る項目もあるため、config.tomlだけで全部を解決しようとしないのがポイントです。

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

[ui]
theme = "auto"
auto_dark_theme = "tokyonight"
auto_light_theme = "grokday"
permission_mode = "ask"

[session]
auto_compact_threshold_percent = 85
load_envrc = true

[cli]
auto_update = true
channel = "stable"
show_tips = false

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

auto_updateは、公式リファレンス上では未設定時にオンと説明されています。安定性重視のチームではchannel = "stable"を明示し、本番に近い作業端末では自動更新の扱いをチームで決めるのがよいです。xAIのGrok Build changelogを見ると、2026年6月にはv0.2系で設定、権限、MCP、Windows、コンテキスト表示などの修正が継続的に入っています。便利な反面、エージェントの挙動が変わる可能性もあるので、重要プロジェクトではバージョン確認を運用に入れてください。

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

権限設定：askを標準にしてallow/denyで絞る

Grok Buildをチームで使うなら、権限設定は最重要です。公式のSettings Referenceでは、[permission]はユーザースコープとプロジェクトスコープの両方に対応し、評価順はdeny > ask > allowとされています。つまり、許可ルールを書いた後でも、より強いdenyがあればブロックできます。

この順序は実務的にかなり重要です。たとえば「Bash(git *)は普段askでよいが、git push --forceはdenyしたい」という考え方ができます。Grok Buildに限らず、AIエージェントの権限設計はAIエージェントのガバナンス・権限設計でも扱っている通り、便利な操作を増やすほど監査性が必要になります。

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

[ui]
permission_mode = "ask"

[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/**)"
]

上の例は、あくまで考え方のサンプルです。Read(.env*)をdenyするかどうかは、プロジェクトの秘密情報管理に依存します。CIテンプレートやGitHub ActionsをGrok Buildに編集させたいチームもありますが、その場合はレビュー必須のaskにするなど、権限とレビュー体制を一緒に設計してください。

個人端末でpermission_mode = "always-approve"にしたくなる気持ちは分かります。毎回確認が出るとテンポが落ちるからです。ただし、公式ドキュメントでもpermission_modeはユーザー設定に置くものとして説明され、プロジェクト側に置かないよう示されています。チームリポジトリで勝手に全員を常時承認モードへ寄せるのは避けるべきです。

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

ユーザー設定とプロジェクト設定の境界を間違えると、Grok Buildのconfigは一気に分かりにくくなります。公式Settingsページでは、プロジェクト設定は.grok/config.tomlに置けるものの、対象はMCPサーバー、plugins、permission rulesに限定されると説明されています。モデルやUIの好みをリポジトリに押し込むより、チーム全員が共有すべき作業ルールだけ置くのが実務向きです。

一方、Enterprise Deploymentsでは、Grok Buildが設定を低い優先度から高い優先度へ読み込む階層が説明されています。/etc/grok/managed_config.toml、~/.grok/managed_config.toml、~/.grok/config.toml、~/.grok/requirements.toml、/etc/grok/requirements.tomlの順で、特にrequirementsは下位レイヤーやユーザー設定で上書きできないピン留めに使う設計です。

置き場所	向いている設定	向いていない設定
~/.grok/config.toml	個人のモデル、UI、通常使うMCP、権限の初期値	チーム全員に強制したい監査ポリシー
.grok/config.toml	リポジトリ共有のMCP、plugins、permission rules	APIキー、個人のUIテーマ、フルユーザー設定
/etc/grok/requirements.toml	MDMや構成管理で配る強制ポリシー	個人が日々調整する表示や作業スタイル

チーム導入では、まずプロジェクト設定でMCPと権限を共有し、それでも足りない場合だけrequirementsを使うのが現実的です。requirementsは強力ですが、強い設定はトラブル時の切り分けも難しくします。特に「この権限がなぜ許可されないのか」を説明できる状態にしてから配布してください。

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

[ui]
permission_mode = "ask"

[cli]
channel = "stable"

[features]
web_fetch = false

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

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

MCP、skills、pluginsをconfigで管理する

Grok Buildの実務価値は、モデルだけではなく拡張機能にもあります。xAI DocsのMCP Serversページでは、grok mcp add --scope projectが現在のディレクトリに.grok/config.tomlを書き、Grok Buildがカレントディレクトリからgit rootへ向かって.grok/config.tomlを読むと説明されています。また、同名のプロジェクトサーバーはユーザー側の同名サーバーを置き換えるとされています。

これは便利ですが、同時に注意点でもあります。個人のfilesystem MCPと、プロジェクトのfilesystem MCPが同じ名前だと、プロジェクト側で置き換わります。チームで使うMCPには、用途が分かる名前を付けるのがおすすめです。

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

[mcp_servers.repo_filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 6000

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

skillsとpluginsも、公式ドキュメントで探索場所が説明されています。skillsは./.grok/skills/、~/.grok/skills/、有効化されたplugin内のskills/、そして[skills] pathsの追加パスから見つかります。pluginsは./.grok/plugins/、~/.grok/plugins/、marketplaceインストール先、[plugins] paths、CLIの--plugin-dirなどから読み込まれます。

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

[skills]
paths = [
  "/Users/me/work/grok-skills",
  "/Users/me/company/shared-skills"
]
disabled = [
  "legacy-skill-name"
]

[plugins]
paths = [
  "/Users/me/work/grok-plugins"
]
enabled = [
  "browser-review"
]
disabled = [
  "experimental-plugin"
]

ここでの推奨は、skillsは「再利用可能な作業手順」、pluginsは「ツール、hooks、MCP、サブエージェントなどをまとめる拡張」として分けることです。単にプロンプトを足したいだけならskillで十分です。外部APIやMCP、hooksまで含めるならpluginとして整理したほうが管理しやすくなります。

なお、hooksはGrok Buildの拡張で重要ですが、公式HooksページではhooksはJSONファイルとして管理され、個人hooksは~/.grok/hooks/*.json、プロジェクトhooksは<project>/.grok/hooks/*.jsonに置くと説明されています。つまり、hooksを何でもconfig.tomlに書くわけではありません。この混同はかなり起きやすいので注意してください。

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

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

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

⭕ 正しいアプローチ: プロジェクト設定は、公式が示す通りMCP、plugins、permission rules中心にする。個人の標準モデルやUIは~/.grok/config.tomlへ置く。

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

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

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

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

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

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

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

⭕ 正しいアプローチ: 標準はask。読み取りやテスト実行など低リスク操作だけallowし、編集・git・依存追加はaskに残す。

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

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

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

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

なぜ重要か: xAI Docsでは、同名のプロジェクトサーバーがユーザーサーバーを置き換えると説明されています。名前の衝突は、権限範囲の誤解につながります。

参考・出典

• Settings – xAI Docs — configの保存場所、スコープ、grok inspect、公式config.toml例を確認（参照日: 2026-07-08）
• Settings Reference – xAI Docs — [permission]、[features]、[skills]、[plugins]などの設定キーを確認（参照日: 2026-07-08）
• Grok Build – xAI Docs — インストール、ヘッドレス実行、カスタムモデル設定、grok inspect、/model切り替えを確認（参照日: 2026-07-08）
• Modes and Commands – xAI Docs — permission_modeのask、always-approve、デフォルト、ユーザー設定に置く注意を確認（参照日: 2026-07-08）
• Enterprise Deployments – xAI Docs — managed configとrequirementsの優先順位、MDM・構成管理での利用を確認（参照日: 2026-07-08）
• Introducing Grok Build – xAI — 2026年5月25日のGrok Build発表、早期ベータ、インストール、plan mode、headless modeを確認（参照日: 2026-07-08）
• Grok Build – Vercel AI Gateway Docs — Vercel AI Gateway経由の環境変数、[models].default、web search向けResponses-backed model設定を確認（参照日: 2026-07-08）

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

Grok Buildのconfig.tomlは、全部を詰め込むファイルではなく、スコープごとに責務を分けるための設定です。個人設定は~/.grok/config.toml、リポジトリ共有は.grok/config.toml、組織の強制ポリシーはrequirements.toml。この分離ができていれば、モデル、MCP、権限、skills/pluginsを増やしても破綻しにくくなります。

1. 今日やること: この記事の最小推奨configを~/.grok/config.tomlに入れ、grok inspectで読み込み状態を確認する。
2. 今週中にやること: チームリポジトリで共有すべきMCPとpermission rulesだけを.grok/config.tomlに分離する。
3. 次の運用でやること: APIキー、MCP、hooks、requirementsの扱いを見直し、Grok Buildの設定変更をレビュー対象にする。

あわせて読みたい:

• Grok Buildの使い方完全ガイド — CLI、ヘッドレス実行、並列エージェントの全体像を確認したい方向け
• Grok Build vs Claude Code徹底比較 — 既存のAIコーディング環境と比べて導入判断したい方向け
• Grokエージェント完全ガイド — Grok Agent全体の使い方・切り替え・カスタム設定を俯瞰したい方向け
• AIエージェント ガバナンス・権限設計2026 — チーム導入時の承認・監査・権限設計を深掘りしたい方向け

次回予告: 次回は、Grok BuildのMCP設定をもう一段深掘りし、filesystem、Issue管理、社内ドキュメント検索を安全に接続する構成例を扱います。

---

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