ki-grok/14-konfiguration-und-custom-models.md

Kapitel 14

Konfiguration und Custom Models

Kern in einem Satz: Grok liest Einstellungen in fester Precedence (CLI > Env > config.toml > managed > Defaults) – wer die Schichten kennt, debuggt „greift nicht“ in Minuten statt Stunden.

---

14.1 Precedence (auswendig lernen)

1. CLI-Flags (--yolo, -m, --sandbox, …)
2. Environment Variables (XAI_API_KEY, GROK_MEMORY, …)
3. config.toml (~/.grok/config.toml und projektrelevante Teile)
4. Managed / requirements (Org: managed_config.toml, requirements.toml)
5. Built-in Defaults

Project .grok/config.toml: liefert vor allem [mcp_servers], [plugins], [permission] (und verwandte team-sharebare Blöcke). Viele UI-/Model-Defaults bleiben user-global. MCP-Namen: Project ersetzt User-Server gleichen Namens komplett (Kapitel 9).

{width=90%}

---

14.2 Wo liegt was?

Config greift nicht? Zuerst wissen, welche Datei und welche Schicht – grok inspect spart Rate-Orakel.

Pfad	Rolle
~/.grok/config.toml	Haupt-User-Config
~/.grok/sandbox.toml	Sandbox-Profile
~/.grok/auth.json	Login-Tokens
~/.grok/mcp_credentials.json	MCP-OAuth
~/.grok/trusted_folders.toml	Folder-Trust
~/.grok/sessions/	Sessions (Kap. 12)
~/.grok/memory/	Memory (Kap. 12)
~/.grok/skills/, hooks/, rules/	User-Extensions
<repo>/.grok/config.toml	Project MCP/Plugins/Permissions
$GROK_HOME	Override der Home-Basis
/etc/grok/…	System managed (Org)

grok inspect / grok inspect --json – erste Anlaufstelle, was geladen wurde.

---

14.3 config.toml – die nützlichen Sektionen

Datei nur mit Overrides füllen; Defaults greifen sonst. Heute typisch setzen: Model-Default, Permission-Deny, ggf. MCP/Plugins. UI-Flags (simple_mode, vim_mode) und Experimente nur, wenn du sie brauchst.

[cli]
auto_update = true

[models]
default = "grok-4.5"
web_search = "grok-4.5"
# temperature, top_p, max_completion_tokens, max_retries, …
# extra_headers = { "X-Request-Tags" = "team=example" }

[ui]
permission_mode = "ask"
vim_mode = false
simple_mode = true
screen_mode = "fullscreen"          # oder minimal
show_thinking_blocks = true
remember_tool_approvals = false
default_selected_permission = "allow_once"  # sicherere Default-Zeile

[features]
telemetry = false
codebase_indexing = true
remote_fetch = true                 # false in air-gap
lsp_tools = false

[session]
auto_compact_threshold_percent = 85
load_envrc = true

[tools]
respect_gitignore = false

[memory]
enabled = false

[subagents]
enabled = true

UI-Hinweis: simple_mode = Prompt-Editor (readline vs. vim-input). vim_mode = Scrollback-Navigation. Unabhängig (Kapitel 3).

Permission-Default-Zeile: default_selected_permission steuert nur den ersten Prompt einer Session; danach sticky. Env-Override: GROK_DEFAULT_SELECTED_PERMISSION.

Theming/Pager: separate pager.toml / Settings-UI – im Buch bewusst knapp; Details im User-Guide Configuration / Theming.

---

14.4 Compat-Schalter (Claude / Cursor)

Grok scannt default Claude- und Cursor-Pfade für Skills, Rules, Hooks, MCPs. Abschalten z. B.:

[compat.claude]
skills = false
rules = false
hooks = false
mcps = false

[compat.cursor]
skills = false
rules = false
hooks = false
mcps = false

Env-Pendants existieren (GROK_CLAUDE_SKILLS_ENABLED=false, …). Wenn „fremde“ Skills/MCP spuken: Compat + grok inspect.

---

14.5 Modelle wählen

grok models                 # verfügbare Modelle listen
grok -m grok-build -p "…"

TUI: /model grok-build (/m), Effort /effort high, Picker Ctrl+M (Scrollback-Fokus).

[models]
default = "grok-4.5"

Default-Hosted-Modelle brauchen keine Extra-Endpoint-Config – Auth per Login/Key (Kapitel 2). IDs und Namen driften mit Releases; grok models und Picker sind Source of Truth.

---

14.6 Custom Models / alternative Endpoints

Für Self-Hosted, Proxy, Drittanbieter in ~/.grok/config.toml:

[model.my-model]
model = "model-id"                         # Wire-ID an die API
base_url = "https://api.example.com/v1"
name = "Display Name"                      # Picker-Label
api_backend = "chat_completions"           # oder responses | messages
env_key = "MY_MODEL_API_KEY"               # Key aus Env – nicht api_key in TOML committen
# extra_headers = { … }

api_backend	Protokoll
chat_completions (default)	OpenAI /v1/chat/completions
responses	OpenAI Responses
messages	Anthropic Messages

Provider-Header (z. B. Anthropic x-api-key) über extra_headers. Keys nicht committen – Env-Referenzen nutzen, wo unterstützt.

grok -m my-model -p "ping"
/model my-model

Air-gap: [features] remote_fetch = false, fester Model-Katalog, eigener base_url.

---

14.7 Skills-, MCP-, Permission-Config (Querverweis)

Thema	Kapitel	Config-Ort
Skills paths/ignore/disabled	8	[skills]
MCP servers	9	[mcp_servers.*], [mcp]
Permissions	13	[permission]
Subagents	5	[subagents.*]
Sandbox	13	sandbox.toml
Marketplaces	8	[[marketplace.sources]]
Hooks in TOML	8	[[hooks.Event]]

Vorlage: vorlagen/config.toml.beispiel.toml.

---

14.8 Debug-Workflow: „Config greift nicht“

1. Welcher Prozess? TUI vs. -p vs. agent – Flags unterschiedlich.
2. grok inspect – was ist geladen (Rules, MCP, Skills, Origin)?
3. Precedence – überschreibt CLI/Env deine TOML?
4. Project vs User – liegst du im richtigen CWD/Repo?
5. Trust – project MCP/hooks still?
6. Compat – kommt der Wert aus Claude/Cursor-Datei?
7. Syntax – TOML-Validität, falscher Tabellenname.
8. Reload – neue Session; MCP-Modal r.
9. /doctor – Terminal/Sandbox/Clipboard.
10. Minimal repro – leere Config + ein Override.

grok inspect --json | jq 'keys'
# je nach Schema: skills, mcp, instructions filtern

---

14.9 Praxis-Sessions

Session 1 – Default-Modell setzen

[models]
default = "grok-4.5"   # oder aktuelle ID aus `grok models`

grok -c
/session-info

Session 2 – sicherere Permission-UI

[ui]
default_selected_permission = "allow_once"
remember_tool_approvals = false
permission_mode = "ask"

Neuen Session-Start: erster Prompt sollte nicht auf „always all sessions“ kleben.

Session 3 – Project Permission vs. User Model

Project: Deny-Liste. User: default model. Prüfen: Deny greift im Repo, Modell kommt aus User-Config.

Session 4 – Custom Model Smoke (wenn Endpoint vorhanden)

[model.local-proxy]
model = "my-weights"
base_url = "http://127.0.0.1:8000/v1"
name = "Local Proxy"

grok -m local-proxy -p "Reply with pong only."

Session 5 – Compat-Noise abschalten

Cursor-Skills nerven → [compat.cursor] skills = false → grok inspect ohne Cursor-Skills.

Session 6 – Air-gap Flags

[features]
remote_fetch = false
telemetry = false

---

14.10 Jetzt selbst machen: Config-Parcours (20 Minuten)

Jetzt selbst machen

1. ~/.grok/config.toml anlegen/backupen.
2. Ein UI- und ein Model-Override setzen.
3. grok inspect vor/nach.
4. CLI -m überschreibt Default – verifizieren.
5. Project .grok/config.toml mit einem Deny.
6. Debug-Checkliste 14.8 einmal an einem echten „greift nicht“-Fall durchspielen (oder simulieren).

---

14.11 Häufige Fehler

Symptom	Ursache	Fix
TOML-Änderung wirkungslos	CLI/Env höher	Flags/Env prüfen
Model unbekannt	Tippfehler / Katalog	grok models
MCP nur lokal	project untrusted / scope	Trust, list --
Fremde Skills	Compat an	compat.*.skills false
Zwei Wahrheiten	user + project conflict	inspect, eine Quelle
Secret in TOML committed	Klartext	Env, rotieren

---

14.12 Checkliste

• Precedence verstanden
• User-Config versioniert/backup (ohne Secrets)
• Project nur sharebare Sektionen
• grok inspect im Werkzeugkasten
• Model-Default bewusst
• Compat nur so weit wie nötig
• Custom Endpoints ohne committed Keys

---

Was du jetzt kannst

• Config-Schichten und Precedence anwenden und debuggen
• config.toml-Kernsektionen und Compat-Schalter setzen
• Modelle wählen und Custom-Endpoints anbinden
• Project- vs. User-Scope für Team-Configs trennen

Nächste Schritte

→ Kapitel 15 – Reale Workflows und Use-Cases: die Hebel aus Kapitel 2–14 in durchgängigen Produktions-Szenarien.