📘 תיעוד 29

תצורה

Grok קורא הגדרות מקובצי תצורה, ממשתני סביבה ומדגלי CLI. דף זה מכסה את האפשרויות הנפוצות. רשימת השדות עבור config.toml, managed_config.toml ו-requirements.toml מופיעה ב-26-config-reference.md (מחולץ אל ~/.grok/docs/user-guide/ בעת ההפעלה).

#סדר קדימויות

הגדרות נקבעות לפי העדיפות הגבוהה ביותר תחילה:

1. דגלי CLI (למשל --yolo, --model, --sandbox)
2. משתני סביבה (למשל XAI_API_KEY, GROK_MEMORY)
3. requirements.toml / MDM (נאכף על ידי הארגון, מגביל כל שכבת תצורה שמתחתיו, כולל שכבת ה-overlay)
4. שכבת overlay של GROK_CONFIG / GROK_CONFIG_PATH (מעל config.toml ו-managed, מתחת ל-requirements.toml / MDM)
5. config.toml (~/.grok/config.toml)
6. managed_config.toml (ברירות מחדל שנפרסו על ידי הארגון, מתחת ל-config.toml)
7. ברירות מחדל מובנות

בתוך רובד קובצי התצורה, השכבות מתמזגות מהנמוכה לגבוהה: managed_config.toml → config.toml → שכבת ה-overlay של GROK_CONFIG → requirements.toml / MDM. לכן requirements.toml ו-MDM מגבילים גם את config.toml שלך וגם את ה-overlay.

GROK_CONFIG / GROK_CONFIG_PATH (רובד 4) הם שכבות כיסוי (overlays) של תצורה: שכבת תצורה ממוזגת, ולא משתני סביבה של הגדרה ישירה כמו XAI_API_KEY (רובד 2). הם מגדירים מפתחות תצורה (בכפוף לרשימת ההיתרים שלהלן), לכן יש לקרוא אותם כחלק מרובד קובצי התצורה ולא מרובד משתני הסביבה.

#הזרקת תצורה באמצעות GROK_CONFIG

מעטפת (harness) או לקוח ACP שמפעיל את grok agent stdio יכול להזריק הגדרות בלי לכתוב config.toml ובלי לשנות את מיקום $GROK_HOME:

• GROK_CONFIG: שכבת overlay מוטבעת של אובייקט JSON.
• GROK_CONFIG_PATH: שכבת overlay מקובץ נוסף (אינו תחליף ל-config.toml), קובץ JSON או TOML שנקרא לפי הסיומת שלו (.json מוביל ל-JSON, אחרת TOML). אם שניהם מוגדרים, GROK_CONFIG מנצח. ערך ריק ב-GROK_CONFIG נחשב כלא מוגדר, וערך בעל מבנה לא תקין רושם אזהרה ביומן ועובר אל GROK_CONFIG_PATH.

שכבת ה-overlay עוברת מיזוג עמוק (deep-merged) על גבי ה-config.toml שלך (היא דורסת רק את המפתחות שהיא מגדירה), ממוקמת מעל שכבות המשתמש/המנוהלות אך מתחת ל-requirements.toml / MDM, כך שנעילה ארגונית עדיין מנצחת. תוכן במבנה שגוי זוכה להתעלמות עם אזהרה. התנהגות זו משקפת את CODEX_CONFIG ממתאם codex-acp (אובייקט JSON הממוזג לתוך תצורת ההפעלה). Grok תומך ב-ACP באופן טבעי, ולכן ה-overlay חי בתוך הסוכן עצמו. הוא משפיע רק על הגדרות שנקראות מתוך התצורה הממוזגת, והוא אינו מסלול להסלמת הרשאות. שכבת ה-overlay מוגבלת, באופן של חסימה בעת כשל (fail-closed), לרשימת היתרים (allowlist) של הגדרות רכות (models, features, קבוצת כלים מצומצמת ב-toolset, ו-shell_environment_policy המוגבלת לשדות הסינון שלה, אשר בוחרים מבין שמות משתני סביבה שמשגר ההפעלה כבר שולט בהם ואינם יכולים להזריק ערך משתנה סביבה לתהליכי משנה של כלים). כל טבלה אחרת מושמטת בנקודת החסימה, כך שה-overlay אינו יכול להפעיל פקודות, להגדיר מדיניות אימות, לנתב מחדש תעבורת רשת, להעלות רמת אמון או להוסיף מקור גילוי. גם בהגדרות שברשימת ההיתרים, קבוצה מסוימת של שערי אבטחה קוראת את שכבות הדיסק הגולמיות במקום את ה-overlay. ה-rustdoc של ConfigLayers::env_overlay הוא הרשימה המוסמכת של מה שה-overlay יכול ולא יכול להגיע אליו ואילו שערים קוראים אותו ללא overlay. ראה גם את מדריך משתני הסביבה הפנימיים. השתמש ב-GROK_DEFAULT_SELECTED_PERMISSION עבור בקרת הרשאות במצב ללא ממשק (headless). לדוגמה, כדי להגדיר את מאמץ החשיבה המוגדר כברירת מחדל:

GROK_CONFIG='{"models": {"default_reasoning_effort": "high"}}' grok agent stdio

#config.toml (תצורה ראשית)

מיקום: ~/.grok/config.toml. אם הקובץ חסר, Grok משתמש בברירות המחדל המובנות שלו, כך שעליך להגדיר רק את הערכים שברצונך לדרוס.

#הגדרות כלליות

[cli]
auto_update = true                     
# check for updates on launch

[models]
default = "grok-4.5"                   
# model used for new sessions
web_search = "grok-4.5"                
# model used by the web_search tool
# Optional picker allowlist (globs on catalog key or model id). Empty = unrestricted.
# A signed policy pin replaces this list (model id only) and cannot be widened from here.
# allowed_models = ["grok-4.5", "grok-4*"]

# Defaults applied to every model; a per-model [model.<id>] value always wins.
# See "Custom Models" for the per-model overrides and full details.
extra_headers = { "X-Request-Tags" = "team=example,env=prod" }
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
max_retries = 8
inference_idle_timeout_secs = 600
subagent_rate_limit_max_attempts = 8
stream_tool_calls = true

[ui]
simple_mode = true                     
# readline-style prompt editing (default); false = vim editing in the prompt
vim_mode = false                       
# vim-style scrollback navigation keys (default: false)
max_thoughts_width = 120               
# max column width for reasoning display
default_selected_permission = "always_allow_all_sessions" 
# preselected row on the FIRST approval prompt
remember_tool_approvals = true         
# show per-command "Always allow" options on permission prompts;
                                       
# grants are remembered per project (default: true); see 22-permissions-and-safety.md
show_thinking_blocks = true            
# show agent thinking blocks in the TUI (default: true)
group_tool_verbs = true                
# fold runs of read/search/list tool calls and subagent rows
                                       
# , and finished thoughts among them, into one row (default: true)
collapsed_edit_blocks = false          
# show edits as one-line +N/-M diffstat summaries and merge
                                       
# back-to-back same-file edits into one row, expand for the
                                       
# diffs (default: false; pager.toml [scrollback.blocks.edit]
                                       
# expanded_by_default/line_summary override its fold shape)
page_flip_on_send = true               
# pin a just-sent prompt at the top of the viewport so the
                                       
# response starts on a fresh page (default: true); set false
                                       
# so sending never moves the scroll position
follow_up_behavior = "queue"           
# mid-turn follow-ups: "queue" (wait for turn end; default) or
                                       
# "steer" (plain Enter still queues visibly, then injects at the
                                       
# next tool/model safe gap). See Keyboard Shortcuts → Mid-turn.
screen_mode = "fullscreen"             
# default render mode: "fullscreen" | "minimal"
                                       
# (unset → fullscreen); set via /settings → Default screen mode

[features]
telemetry = false                      
# anonymous usage telemetry
feedback = true                        
# feedback system (default: true)
lsp_tools = false                      
# expose the lsp tool
codebase_indexing = true               
# code graph indexing (default: true)
two_pass_compaction = true             
# prefire two-pass compaction (default: true)
remote_fetch = true                    
# allow optional online model-catalog fetches (default: true;
                                       
# set false for firewalled/air-gapped deployments; background
                                       
# managed-config sync has its own switch: managed_config)

[session]
auto_compact_threshold_percent = 85    
# auto-compact at this % of context window (default: 85)
load_envrc = true                      
# load .envrc environment variables

[tools]
respect_gitignore = false              
# default: false; set true to make every tool skip gitignored files

# Optional caps on parallel media generation in a single model step.
# Per tool name. First 2×-or-more burst: discard that step and retry once.
# Any other over-cap (including a second 2× burst) keeps the first K.
# Defaults: image 8, video 4.
# Env vars GROK_MAX_PARALLEL_IMAGE_GEN_CALLS / GROK_MAX_PARALLEL_VIDEO_GEN_CALLS
# override these values (see environment-variables doc).
# [tools.media_gen]
# max_parallel_image_gen_calls = 8
# max_parallel_video_gen_calls = 4

#מצב קלט

ההגדרה [ui] simple_mode שולטת באופן עריכת הטקסט ב-prompt, עורך הקלט. אין לה שום קשר לאופן שבו אתה נע ב-scrollback: לכך משמש vim_mode.

כדי להעביר את ה-prompt לעריכה בסגנון vim:

[ui]
simple_mode = false

ניתן גם להחליף זאת מחלונית ההגדרות (/settings → Disable vim input mode). Grok כותב את הבחירה שלך אל [ui] simple_mode. ההגדרות simple_mode ו-vim_mode בלתי תלויות: האחת שולטת בעורך ה-prompt, והשנייה שולטת בניווט ב-scrollback. ראה קיצורי מקשים למדריך המקשים המלא.

#הרשאה נבחרת כברירת מחדל

כאשר הסוכן מבקש להריץ פקודה (או לבצע פעולת כלי אחרת), תפריט האישור מדגיש שורה אחת כברירת מחדל. ההגדרה [ui] default_selected_permission קובעת איזו שורה זו תהיה בבקשת האישור הראשונה של הפעלה.

[ui]
default_selected_permission = "allow_once"

לאחר שתענה על בקשת האישור הראשונה, הסמן הופך לדביק (sticky): כל בקשת אישור מאוחרת יותר בוחרת מראש את מה שאישרת לאחרונה (בחירה ב-"No" פעם אחת תגרום לכך שבקשות האישור הבאות יתחילו בשורת הדחייה שלהן), והדבר נשמר על פני בקשות אישור של edit / bash / MCP עד להפעלה מחדש. לכן הגדרה זו קובעת רק את נקודת ההתחלה.

הערכים מותאמים ללא תלות ברישיות אותיות (case-insensitively). ערך לא מוגדר או לא מזוהה חוזר אל always_allow_all_sessions. השורה allow_command_always מוגבלת תמיד לפעולה הספציפית המאושרת (פקודה / כלי / תחום / edit-session), ולעולם אינה אישור גורף לכל דבר, לשם כך נועדה השורה always_allow_all_sessions. שים לב ששורות "Always allow" לכל פקודה מופיעות כל עוד [ui] remember_tool_approvals מופעל (ברירת המחדל. הגדר כ-false כדי להסתיר אותן). ראה 22-permissions-and-safety.md.

ניתן גם לדרוס זאת באמצעות GROK_DEFAULT_SELECTED_PERMISSION, דבר שימושי עבור הרצות headless או הרצות בדיקה של סוכנים שלא אמורות לשנות את config.toml. סדר קדימויות: משתנה סביבה → config.toml → always_allow_all_sessions.

#מצב Vim

ההגדרה [ui] vim_mode שולטת אם קיצורי מקשים בסגנון vim פעילים בחלונית ה-scrollback. היא אינה משפיעה על ה-prompt.

החלף מצב זה בזמן ריצה באמצעות /vim-mode, או מתוך /settings → Vim scrollback navigation. Grok כותב את השינוי אל [ui] vim_mode מיד ומחיל אותו על כל הפעלת pager עתידית, כולל סוכנים חדשים וסוכני משנה באותו תהליך. אין דריסה ברמת ההפעלה הבודדת: config.toml הוא מקור האמת בהפעלה הבאה. vim_mode בלתי תלוי ב-simple_mode.

#מצב מסך

ההגדרה [ui] screen_mode היא מצב הרינדור המוגדר כברירת מחדל עבור הפעלות רגילות של grok. הגדר אותו מתוך /settings → Default screen mode (נדרשת הפעלה מחדש) או ערוך את config.toml ידנית, שני האופנים כותבים לקובץ. דגלי CLI (כגון --minimal / --fullscreen) ופקודות לוכסן (/minimal / /fullscreen) תקפים לרמת ההפעלה הנוכחית בלבד ואינם כותבים למפתח זה. לאחר החלפה באמצעות פקודת לוכסן, הפקודה ההפוכה מחזירה אותך עבור אותה הפעלה בלבד.

דגל CLI תמיד מנצח את ערך התצורה עבור אותה הפעלה.

#הצמדת ה-prompt לראש המסך בעת שליחה

כברירת מחדל, שליחת prompt גוללת אותו לראש אזור התצוגה (viewport) כך שהתגובה מתחילה בעמוד חדש. הגדר [ui] page_flip_on_send = false (או החלף את מצב Snap prompt to top on send ב-/settings → Appearance) כדי לא לשנות את מיקום הגלילה בעת שליחה. ההגדרה נכנסת לתוקף בשליחה הבאה, ללא צורך בהפעלה מחדש.

#גלילה

ארבע הגדרות [ui] מכווננות את הגלילה באמצעות גלגלת העכבר ומשטח המגע (trackpad). כולן חלות באופן מיידי וניתנות לעריכה מחלונית ההגדרות (/settings → Scroll speed / Scroll input / Scroll lines / Invert scroll).

[ui]
scroll_speed = 50
scroll_mode = "auto"     
# auto | wheel | trackpad
invert_scroll = false
# scroll_lines is unset by default: the per-terminal profile stays in charge.
# scroll_lines = 3

לכל הגדרה יש גם דריסה באמצעות משתנה סביבה, המוחלת בטעינה הראשונה בלבד (שוב, שימושי עבור הרצות headless או בדיקות): GROK_SCROLL_SPEED, GROK_SCROLL_MODE, GROK_INVERT_SCROLL (1/true/0/false), ו-GROK_SCROLL_LINES. סדר קדימויות: משתנה סביבה → config.toml → ברירת מחדל. ערכים לא מזוהים חוזרים לברירת המחדל, ומספרים מחוץ לטווח נחתכים לגבולות הטווח.

#תצורת כלים

[toolset.bash]
timeout_secs = 120.0                   
# foreground command timeout in seconds (default: 120)
output_byte_limit = 20000              
# max captured output in bytes (default: 20000)

[toolset.ask_user_question]
timeout_enabled = true                 
# false = wait forever for answers (default: true)
timeout_secs = 1800                    
# seconds to wait when enabled (default: 1800 / 30 min)

[toolset.web_fetch]
proxy_endpoint = "https://proxy.example.com"   
# egress proxy URL
allowed_domains = ["docs.rs", "x.ai"]          
# override the built-in allowlist
allow_local = false                            
# true = allow localhost / 127.0.0.0/8 / ::1 only

[toolset.web_search]
# Restrict web_search to these domains (max 5). Mutually exclusive with excluded_domains.
allowed_domains = ["docs.x.ai", "arxiv.org"]
# ...or block these domains instead (leave allowed_domains unset):
# excluded_domains = ["reddit.com", "pinterest.com"]

ההגדרה allow_local כבויה כברירת מחדל (חסימת SSRF בעת כשל). אם תפעיל אותה (או תגדיר GROK_WEB_FETCH_ALLOW_LOCAL=1), הכלי web_fetch יוכל לגשת למארחי loopback מפורשים בלבד: טווחי כתובות פרטיות, קישור מקומי (link-local) ומטא-דאטה של ענן נשארים חסומים. סדר הכרעה: TOML > משתנה סביבה > כבוי כברירת מחדל.

[toolset.web_search] מגביל את התחומים של הכלי web_search: רשימת ההיתרים/חסימות שתחתיה החיפוש עצמו רץ (ולא סינון לאחר מעשה). allowed_domains ו-excluded_domains הם בלעדיים הדדית (mutually exclusive). אם תגדיר את שניהם, רשימת ההיתרים מנצחת ורשימת החסימות מושמטת עם אזהרה. רשימה ריקה או חסרה אינה מגבילה. הדבר חל הן על חיפוש המתארח בצד השרת (מודלים עם חיפוש בצד השרת) והן על מנגנון הגיבוי בצד הלקוח. מדיניות מוגדרת היא מוסמכת (authoritative): המודל אינו יכול לעקוף אותה, וה-allowed_domains של המודל עצמו בכל קריאה אינו נלקח בחשבון בכל פעם שהגדרת כאן allowed_domains או excluded_domains (כך שרשימת חסימה היא חסימה אמיתית). רשימת ההיתרים של המודל לכל קריאה חלה רק כאשר לא הגדרת דבר. סדר הכרעה: requirements → קובץ config.toml של המשתמש → managed → ברירת מחדל (לא מוגדר). התצורה נקראת בתחילת ההפעלה, לכן ערוך אותה לפני תחילת ההפעלה, שינויים אינם חלים באמצע הפעלה.

[toolset.ask_user_question] מכובד לרוחב requirements.toml, managed config וקובץ ה-config.toml של המשתמש שלך. סדר קדימויות: requirements → משתנה סביבה (GROK_ASK_USER_QUESTION_TIMEOUT_ENABLED / GROK_ASK_USER_QUESTION_TIMEOUT_SECS) → תצורת משתמש → managed → ברירות מחדל. הגדר timeout_enabled = false בתצורת המשתמש שלך כדי להשבית את פסק הזמן האוטומטי של השאלון עבור עצמך. timeout_secs חייב להיות מספר שלם חיובי. ניתן גם לשנות את timeout_enabled מתוך /settings → Ask-Question timeout (תחת Agent & Approval), שינויים חלים על הפעלות חדשות שמתחילות.

#אימות

ראה אימות לפרטים המלאים.

[auth]
auth_provider_command = "/usr/local/bin/my-auth-provider"
auth_provider_label = "Acme Corp"
auth_token_ttl = 3600

[grok_com_config.oidc]
issuer = "https://acme.okta.com"
client_id = "0oa1b2c3d4e5f6g7h8i9"
# scopes = ["openid", "profile", "email", "offline_access", "api:access"]
# audience = "https://api.acme.com"

#מודלים מותאמים אישית

הוסף נקודות קצה של מודלים מותאמים אישית כדי להשתמש בספקים חלופיים או במודלים באירוח עצמי.

[model.my-model]
model = "model-id"                    
# model identifier sent to API
base_url = "https://api.example.com/v1"  
# OpenAI-compatible endpoint
name = "Display Name"                 
# shown in model picker
description = "Model description"      
# optional
api_key = "sk-..."                    
# API key for this provider
env_key = "XAI_API_KEY"               
# env var(s) holding the API key; string or array (first set, non-empty wins)
temperature = 0.7                     
# sampling temperature (0.0-2.0)
top_p = 0.95                          
# nucleus sampling parameter
max_completion_tokens = 8192          
# max tokens per response
context_window = 128000               
# context window size (for auto-compact)
query_params = { api-version = "2026-07-22" } 
# query params appended to every request URL
env_http_headers = { "X-Tenant" = "TENANT_TOKEN" }    
# request headers from env vars, resolved at client build

סדר הכרעת אישורים: api_key > env_key > טוקן הפעלה מחובר (signed-in session token) > XAI_API_KEY. ראה מודלים מותאמים אישית עבור query_params ו-env_http_headers, וכן מצב Sandbox עבור [shell_environment_policy], המגביל את משתני הסביבה שתהליכי משנה של כלים יורשים.

כדי לדרוס מודל מובנה, השתמש בשמו כמפתח המקטע והגדר רק את השדות הדרושים לך:

[model.grok-4.6]
api_key = "my-api-key"

#שרתי MCP

הגדר שילובי כלים חיצוניים מעל פרוטוקול Model Context Protocol.

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }
enabled = true                        
# enable/disable (default: true)
startup_timeout_sec = 30              
# init timeout in seconds (default: 30)
tool_timeout_sec = 6000              
# tool call timeout in seconds (default: 6000)
tool_timeouts = { create_issue = 120 }  
# per-tool timeout overrides

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]

[mcp_servers.my-streamable-server]
url = "https://mcp.example.com/api/mcp"  
# HTTP/SSE transport
headers = { "x-mcp-session-id" = "{{session_id}}" }

שרתים מרוחקים (HTTP/SSE) מקבלים כותרת ברירת מחדל User-Agent: grok-cli/<version>, וערך User-Agent תקין תחת headers דורס אותה (שרתי Figma מקבלים grok-cli בלבד). ראה שרתי MCP לפרטים.

ניתן להגדיר שרתי MCP גם ברמת הפרויקט בתוך .grok/config.toml. תצורה ברמת הפרויקט תורמת כללי [mcp_servers], [plugins] ו-[permission]. כל מקטע אחר נטען אך ורק מתוך ~/.grok/config.toml.

עדיפות עבור [mcp_servers] ו-[plugins]: .grok/config.toml (תיקייה נוכחית) > <repo-root>/.grok/config.toml > ~/.grok/config.toml. כללי [permission] אינם נדרסים לפי עדיפות: הם מתמזגים על פני כל הקבצים לפי סדר deny > ask > allow (ראה 22-permissions-and-safety.md).

#זיכרון

שמירת ידע בין הפעלות שונות. הפעל זאת באמצעות [memory] enabled = true או GROK_MEMORY=1. ערך מפורש של [memory] enabled = false מכבה זאת גם כאשר הגדרה מנוהלת מרוחקת מפעילה זאת. הערות שנרשמו על ידי גרסאות קודמות מועברות אוטומטית. ראה 13-memory.md.

[memory]
enabled = true

[memory.session]
save_on_end = true                    
# write metadata summary on session end

[memory.watcher]
enabled = true                        
# watch memory files for external edits

[memory.search]
max_results = 6                       
# default number of results
min_score = 0.7                       
# minimum relevance score

[memory.initial_injection]
enabled = true                        
# auto-inject memory on first turn
min_score = 0.9                       
# score threshold for first-turn injection

[memory.embedding]
# model is unset by default, so retrieval uses full-text search only
dimensions = 1024                     
# vector dimensions

#סוכני משנה

[subagents]
enabled = true
sampling_limit = 12                   
# concurrent in-flight subagent sampling calls per process; defaults to max_concurrent (32) when unset (GROK_SUBAGENT_SAMPLING_LIMIT)

[subagents.toggle]
explore = true                        
# enable/disable specific types
plan = false

[subagents.models]
explore = "grok-4.6"               
# route to different models

כדי לקבע את המודל שסוכן משנה משתמש בו, הגדר את הרשומה שלו תחת [subagents.models].

#מצב יעד ותהליכי עבודה ברקע

ל-/goal יש שני מנהלי התקן (drivers), הנבחרים לפי הגדרת תהליכי העבודה ברקע (background-workflows). כאשר תהליכי עבודה מופעלים, מנוע תהליכי העבודה שבבעלות המארח מעריך סבבים ומנהל אימות השלמה. כאשר הם מושבתים, /goal נסוג לכלי הישן הפונה למודל update_goal. שאלת הזמינות של /goal בכלל היא מתג נפרד (הגדרת תכונת ה-goal).

תהליכי עבודה ברקע: הכלי workflow, סקריפטים בעלי שם ב-.grok/workflows/*.rhai, והפעלות של /deep-research ו-/workflow, מופעלים כברירת מחדל. השבת אותם באמצעות תצורה, משתנה סביבה או הגדרות מרוחקות.

[workflows]
enabled = false                       
# disable background workflows (or GROK_WORKFLOWS=0)

תהליכי עבודה של הפרויקט מתגלים מתוך <repo-root>/.grok/workflows/, ותהליכי עבודה של המשתמש מתוך ~/.grok/workflows/. הגילוי וההפעלה נקבעים לפי ה-meta.name של הסקריפט, לכן שמור על התאמה בין כל שם קובץ לבין ה-meta.name שלו. שמות מובנים מנצחים שמות של פרויקט, ושמות של פרויקט מנצחים שמות של משתמש, לכן שמור על שמות ייחודיים בין הטווחים השונים.

כל הפעלה מקבלת מזהה תצוגה ייחודי להפעלה כגון deep-research-2. מזהה זה הוא מה שאתה רואה בלוח הבקרה /workflow runs ומעביר אל /workflow pause, resume או stop: מזהי הריצה הפנימיים לעולם אינם מופיעים בפקודות. מזהה ממוספר אינו שם הגדרה הניתן לשימוש חוזר, ולכן לוח הבקרה משבית את אפשרות ה-save עד שתבחר meta.name ייחודי חדש ותשמור את הסקריפט הערוך בעצמך. ראה פקודות לוכסן לדוגמאות.

#מיומנויות (Skills)

[skills]
paths = ["~/my-team-skills"]          
# additional directories to scan
ignore = ["~/my-team-skills/wip"]     
# paths to exclude
disabled = ["wip-skill"]              
# skill names to keep listed but inactive

#תאימות סביבות הרצה (Harness compatibility)

שליטה בתאימות ספקים עבור Cursor, Claude ו-Codex. כל תא מוגדר כברירת מחדל ל-true. תאי sessions נשארים בהמתנה (staged) וללא פעילות עד שסורק הפעלות זרות צורך אותם, וכל כלי זקוק הן לתא ה-sessions שלו והן למיומנות התואמת resume-claude, resume-codex או resume-cursor: מיומנות חסרה פירושה אפס פעולות קלט/פלט של מערכת קבצים עבור הפעלות זרות.

[compat.cursor]
skills = true     
# scan ~/.cursor/skills/ and <cwd>/.cursor/skills/
rules = true      
# scan ~/.cursor/rules/ and <dir>/.cursor/rules/
agents = true     
# scan ~/.cursor/ for named instruction files
mcps = true       
# scan ~/.cursor/mcp.json and <cwd>/.cursor/mcp.json
hooks = true      
# scan ~/.cursor/hooks.json and <cwd>/.cursor/hooks.json
sessions = true   
# staged; no scanner consumer yet

[compat.claude]
skills = true     
# scan ~/.claude/skills/ and <cwd>/.claude/skills/
rules = true      
# scan ~/.claude/rules/ and <dir>/.claude/rules/
agents = true     
# scan ~/.claude/ and <dir>/.claude/CLAUDE*.md
mcps = true       
# scan ~/.claude.json for MCP servers
hooks = true      
# scan ~/.claude/settings.json for hooks
sessions = true   
# staged; no scanner consumer yet

[compat.codex]
sessions = true   
# staged; no scanner consumer yet

התאים skills, rules, agents, mcps ו-hooks של Codex שמורים וכעת אינם פעילים: הם אינם מפעילים גילוי של .codex.

עבור Claude ו-Cursor, ההגדרות rules ו-agents בלתי תלויות זו בזו: כיבוי קובצי הוראות בעלי שם אינו משבית את תיקיית הכללים של תיקיית הבית או הפרויקט, וכיבוי הכללים אינו משבית קבצים בעלי שם. תא ה-agents של Claude שולט בקבצים בעלי שם ברמת הבית ב-~/.claude/ ובקובצי הפרויקט <dir>/.claude/CLAUDE*.md. קבצים כלליים ברמה העליונה כגון Claude.md, CLAUDE.md ו-CLAUDE.local.md נשארים מזוהים. נתיבי כללי הפרויקט נסרקים בכל תיקייה החל משורש המאגר ועד לתיקייה הנוכחית.

ניתן להגדיר כל תא באמצעות משתנה סביבה או ב-config.toml. ראה את מדריך משתני הסביבה לקבלת השמות. סדר הכרעה: משתנה סביבה > config.toml > ברירת מחדל (פעיל).

הפקודה grok inspect מדווחת על תאים שעדיין זקוקים להכרעה בתחילת ההפעלה כ-? עד שערך הופך לזמין. תאים בעלי ערך מפורש ממשתנה סביבה או מ-TOML משתמשים באותו ערך. רשומות גילוי מושפעות מדווחות על compatibilityStatus: "unresolved" ב-JSON ועל [compat unresolved] בפלט קריא לאדם.

#תוספים (Plugins)

[plugins]
paths = ["~/my-plugins/custom-tools"]
disabled = ["user/a1b2c3d4/noisy-plugin"]

#רמזים (Hints)

המקטע [hints] שומר העדפות ממשק משתמש קטנות שנשמרות לצמיתות: תשובות שנזכרו ופריסת חלונות מודאליים. Grok כותב אותן עבורך תוך כדי שימוש ב-TUI, אך באפשרותך לערוך או למחוק אותן ידנית. הסרת מפתח משחזרת את ברירת המחדל.

המקטע [hints] נקרא מתוך מיזוג התצורה בפועל (effective config merge), לפי סדר הקדימויות הרגיל: מנוהל מערכתי → managed_config.toml של המשתמש → config.toml של המשתמש → requirements.toml של המשתמש → requirements.toml מערכתי, כאשר שכבות גבוהות יותר מנצחות. ה-TUI כותב הגדרות אלו אך ורק לקובץ ~/.grok/config.toml של המשתמש שלך.

[hints]
memory_modal_fullscreen = false        
# remember the memory modal fullscreen state
new_session_worktree_mode = "never"    
# /new worktree prompt: "ask" | "always" | "never"
fork_worktree_mode = "ask"             
# /fork worktree prompt: "ask" | "always" | "never"

#התראות

שליחת התראות מסוף כאשר הסוכן מסיים תור או זקוק לאישור. הן משתמשות בפרוטוקולים טבעיים למסוף (OSC 9, OSC 99, OSC 777 או BEL) ומותנות במיקוד כברירת מחדל, כך שהן מופעלות רק כאשר אינך צופה במסוף.

[ui.notifications]
method = "auto"           
# auto|osc9|osc99|osc777|bel|none
condition = "unfocused"   
# unfocused|always|never
idle_threshold_secs = 3   
# seconds unfocused before a notification fires
events = ["turn_complete", "approval_required"]
sleep_prevention = true   
# prevent display sleep during agent turns
progress_bar = true       
# show tab progress bar (OSC 9;4)

[ui.notifications.title]
enabled = true
items = ["action-required", "spinner", "activity", "session-name", "grok"]

#מטריצת תמיכה במסופים

כאשר method = "auto", Grok מזהה את סוג המסוף ובוחר את הפרוטוקול הטוב ביותר. הגדר את method במפורש כדי לדרוס זאת.

#ווי התראות (Notification hooks)

הפעל פקודות משלך בעת התרחשות אירועים. ווים (hooks) מקבלים את $GROK_EVENT, $GROK_MESSAGE ו-$GROK_SESSION_ID בסביבה.

# macOS native notification
[[ui.notifications.hooks]]
command = "terminal-notifier -title 'Grok' -message '$GROK_MESSAGE'"
events = ["turn_complete", "approval_required"]
only_unfocused = true
timeout_secs = 10

# Push to ntfy server
[[ui.notifications.hooks]]
command = "curl -s -d '$GROK_MESSAGE' ntfy.sh/my-grok-alerts"
events = ["turn_complete"]
only_unfocused = true
timeout_secs = 10

# Play a sound
[[ui.notifications.hooks]]
command = "afplay /System/Library/Sounds/Glass.aiff"
events = ["turn_complete"]
only_unfocused = true
timeout_secs = 5

#פתרון בעיות

הפעל את /doctor בהפעלה המושפעת. הפקודה מציגה את בעיות ההתראה והמיקוד שזוהו, את קובץ התצורה הרלוונטי ואת הצעדים לפתרונן. ערך מפורש של method = "bel" מטופל כפעולה מכוונת. הערך method = "none" מכבה ממצאי התראות ומיקוד.

מניעת מצב שינה אינה נכנסת לתוקף: ב-macOS, מניעת שינה משתמשת ב-IOPMAssertionCreateWithName באמצעות CoreFoundation. ב-Linux נעשה שימוש ב-systemd-inhibit (אשר חייב להיות ב-$PATH). ודא שהכלי הרלוונטי זמין. המניעה פעילה רק במהלך תורות פעולה של הסוכן ומשתחררת אוטומטית כשהתור מסתיים.

#שורת מצב (Status line)

שורה אופציונלית בתחתית ה-pager במסך מלא, מושבתת כברירת מחדל. ניתן להפעיל באמצעות [ui.status_line]:

[ui.status_line]
type = "builtin"                
# builtin | command | disabled
items = ["cwd", "model", "context"]

המפתחות הנוספים הם items (אילו מקטעים מובנים יוצגו, לפי הסדר), command, padding ו-refresh_interval (בשניות, מריץ מחדש שורת command לפי טיימר, כך שהודעת תקרית או סטטוס CI יגיעו להפעלה ללא פעילות). מדריך שורת המצב מתעד את כולם, יחד עם חוזה ה-JSON שסקריפט command קורא ב-stdin וסקריפט לדוגמה.

במצב minimal אין שורת מצב: במקום זאת נעשה שימוש בכותרת לשונית המסוף (ראה התראות תחת title.items).

#קיצורי מקשים

קיצורי מקשים אינם ניתנים להגדרה: כל הקיצורים מובנים במערכת. ראה קיצורי מקשים לקבלת המדריך המלא.

#טלמטריה

אלו הם מתגים בלתי תלויים (ראה ניטור שימוש):

• [features] telemetry / GROK_TELEMETRY_ENABLED: מתג העל של ניתוח נתוני מוצר (product-analytics). הפקודה /privacy אינה משנה אותו.
• נתוני קידוד, שמירה ואימון: שורת ההגדרות ש-/privacy פותחת: שיתוף נתוני קידוד, בנפרד מטלמטריה.
• [telemetry] trace_upload / GROK_TELEMETRY_TRACE_UPLOAD: עקבות הפעלה (session traces), פועל לפי טלמטריה כאשר אינו מוגדר.
• [telemetry] otel_* / GROK_EXTERNAL_OTEL: נתוני OTEL חיצוניים לאספן שלך (להלן).

כאשר טלמטריה מופעלת, ארגונים המפעילים אספן משלהם יכולים לנתב אותה מחדש או לכבות חלקים ממנה תחת [telemetry]:

[telemetry]
events_url = "https://telemetry.your-company.com/events"  
# send events to your own collector
events_api_key = "your-collector-token"                   
# auth for your collector, if required
mixpanel_enabled = false                                  
# disable Mixpanel product analytics
trace_upload = false                                      
# disable session/trace uploads (inherits the telemetry toggle when unset)

הגדר ערכים אלו רק כדי לכוון את הטלמטריה לתשתית שלך או לכבות חלקים מסוימים. נקודת הקצה ופרטי האימות המובנים מנוהלים על ידי Grok, השאר אותם לא מוגדרים כדי להשתמש בברירות המחדל.

אותה טבלת [telemetry] מגדירה גם את זרם ה-OpenTelemetry החיצוני, מנגנון הצטרפות בלתי תלוי (אינו דורש את מתג הטלמטריה שלעיל) שמעביר סכמת שימוש ייעודית וללא תוכן לאספן ה-OTLP שלך. אימות האספן מגיע מ-OTEL_EXPORTER_OTLP_HEADERS ולעולם אינו נשמר בדיסק. ראה ניטור ושימוש לסכמה המלאה, משתני הסביבה ומודל הפרטיות.

[telemetry]
otel_enabled = true                                       
# external OTEL master switch (= GROK_EXTERNAL_OTEL)
otel_metrics_exporter = "otlp"                            
# otlp | console | none
otel_logs_exporter = "otlp"                               
# otlp | console | none
otel_endpoint = "https://collector.corp.example:4318"     
# OTLP base endpoint
otel_protocol = "http/protobuf"                           
# http/protobuf | grpc
otel_certificate = "/etc/ssl/corp-ca.pem"                 
# optional: trust private CA (path only)
otel_client_certificate = "/etc/ssl/client.crt"           
# optional: mTLS client cert (path only)
otel_client_key = "/etc/ssl/client.key"                   
# optional: mTLS client key (path only)
otel_log_user_prompts = false                             
# content gate (admins pin via requirements)
otel_log_assistant_responses = false                      
# unset follows prompts; pin false for prompts-only
otel_log_tool_details = true                              
# metadata/preview; enterprise default on for SIEM join
otel_log_tool_content = false                             
# full-body gate; independent of details, does not imply names/paths

מפתחות [telemetry] otel_* המופיעים בקובץ requirements.toml חתום מבצעים נעילה (pin) על פני משתני הסביבה של התהליך (נעילת יעד). הקובץ managed_config.toml אינו עושה זאת. אין מפתח headers: טוקנים של אספן נשארים ב-OTEL_EXPORTER_OTLP_HEADERS. ראה ניטור ושימוש.

#קיבוע גרסאות

שליטה באילו גרסאות ה-CLI רשאי לעדכן אוטומטית ואילו גרסאות רשאיות לרוץ. הגדר ערכים אלו ב-[cli], או בשכבה מנוהלת עבור מדיניות ברמת כלל הצי. לכל אחת מהן יש דריסה באמצעות משתנה סביבה שיכולה רק להחמיר את הגבול, עבור CI ובדיקות.

שינוי: minimum_version אינו חוסם עוד את ההפעלה. כעת הוא רף תחתון רך למניעת שנמוך (downgrade) עבור מנגנון העדכון. עבור רף קשיח שמונע מגרסאות ישנות לפעול, השתמש ב-required_minimum_version.

[cli]
minimum_version = "0.2.109"          
# updater won't downgrade below this
maximum_version = "0.2.180"          
# updater won't install above this
required_minimum_version = "0.2.100" 
# refuse to start below this
required_maximum_version = "0.2.200" 
# refuse to start above this

• minimum_version (GROK_MINIMUM_VERSION) הוא רף תחתון רך למניעת שנמוך. מנגנון העדכון מדלג על יעד שמתחתיו ושומר על הגרסה הנוכחית. הוא לעולם אינו חוסם את ההפעלה.
• maximum_version (GROK_MAXIMUM_VERSION) הוא תקרה רכה. מנגנון העדכון מגביל את היעד אליה ולעולם אינו מתקין מעליה.
• required_minimum_version (GROK_REQUIRED_MINIMUM_VERSION) ו-required_maximum_version (GROK_REQUIRED_MAXIMUM_VERSION) הם גבולות קשיחים. אם הגרסה שרצה נמצאת מחוץ לטווח, ה-CLI יוצא בעת ההפעלה ומנחה את המשתמש להתקין גרסה מאושרת. הפקודות grok update ו-grok --version ממשיכות לעבוד כך שהתקנה מחוץ לטווח תוכל להתאושש.
• גבולות נקבעים בין שכבות התצורה על ידי החמרה בלבד: רף תחתון לוקח את הערך הגבוה ביותר ותקרה לוקחת את הערך הנמוך ביותר, כך שלא ניתן להקל גבול מנוהל, וגבול של משתמש או סביבה אינו יכול לבטל גבול קשיח מנוהל. ערך לא חוקי זוכה להתעלמות כך שמדיניות שגויה לא תחסום את ההפעלה.
• פקודה מפורשת grok update --version X מורשית מעל התקרה, כדי להתאושש מהתקנה של גרסה חדשה מדי, ונדחית מתחת לרף הקשיח.

#פריסה ארגונית

תצורה מלאה לשימוש ארגוני:

[cli]
auto_update = false

[auth]
auth_provider_command = "/usr/local/bin/my-company-auth-provider"
auth_provider_label = "Acme Corp"
auth_token_ttl = 3600

[models]
default = "company-grok"

[model.company-grok]
model = "grok-4.6"
base_url = "https://grok-proxy.acme.com/"
name = "Grok 4.6 (Proxy)"
context_window = 128000

[features]
telemetry = false

#pager.toml (תצורת מראה)

מיקום: ~/.grok/pager.toml. קובץ זה שולט על המראה והתחושה של ה-TUI. שינויים חלים בהפעלה מחדש.

#מסוף

[terminal]
alt_screen = "auto"                   
# fullscreen mode: "auto", "always", "never"

• auto (ברירת מחדל): שימוש במסך החלופי (alternate screen) כאשר המסוף תומך בכך.
• always: שימוש תמיד במסך החלופי.
• never: הפעלה משולבת (inline) במאגר ה-scrollback הראשי של המסוף.

#הנפשה

[animation]
fps = 30                              
# animation frame rate (ticks per second)
wave_rows = 32                        
# rows per wave cycle for accent animation

#Prompt

[prompt]
collapse_unfocused = true             
# collapse prompt when scrollback is focused
mouse_hover = true                    
# show hover highlight on the prompt widget
show_prefix = true                    
# show the prompt prefix character

מצב קומפקטי (Compact mode) אינו נשמר כאן לצמיתות: שליטה בו בזמן ריצה מתבצעת באמצעות [ui] compact_mode או הפקודה /compact-mode.

#Scrollback

[scrollback.layout]
outer_vpad = 1                        
# vertical padding
outer_hpad_left = 2                   
# left horizontal padding
outer_hpad_right = 2                  
# right horizontal padding
block_pad_left = 2                    
# padding inside block, left of content
block_pad_right = 2                   
# padding inside block, right of content

[scrollback.scrollbar]
enabled = true                        
# show scrollbar
gap_left = 0                          
# gap between content and scrollbar
gap_right = 0                         
# gap between scrollbar and screen edge

[scrollback.scroll]
margin = 0                            
# minimum context lines above/below selection
min_page_fraction = 0                 
# minimum scroll as % of viewport (0-100)
follow_indicator = "center"           
# ▼/▲ scroll indicators: "center" or "none"
follow_auto_select = true             
# auto-select latest entry in follow mode
follow_by_overscroll = true           
# scrolling past bottom engages follow mode
anchor_on_fold = true                 
# keep block position when folding
respect_manual_folds = true           
# opt-in (default: false): keep manually folded blocks as-is during streaming/finish; expanding while following stops auto-scroll

[scrollback.display]
sticky_headers = true                 
# pin user prompts as sticky headers
tab_width = 4                         
# spaces per tab character
expandable_indicator = true           
# show expand indicator on foldable entries
expandable_indicator_running = true   
# show indicator on running entries
expandable_indicator_char = "›"       
# character for the expand indicator (default: "›")
selection_buttons = false             
# show copy/view buttons on selection
line_under_last_entry = false         
# horizontal line below last entry
group_selection_split = true          
# split selection box for expanded blocks
highlight_overlays_border = false     
# highlight extends over selection box border
dim_accent = 0.5                      
# dimming factor for collapsed accents (0.0-1.0)

ההגדרה respect_manual_folds כבויה כברירת מחדל. אם תפעיל אותה, בלוק שתקפל ידנית יהיה מקובע: עדכוני הזרמה ואירועי סיום (למשל, בלוק חשיבה שמסתיים) לא ישנו את מצב הקיפול שלו, והרחבת בלוק בזמן שמצב מעקב (follow-mode) עוקב אחרי תוכן חדש תעצור את הגלילה האוטומטית כך שהתצוגה תישאר במקומה. המעקב מתחדש באמצעות Shift+G, מקש j ברשומה האחרונה, גלילה מעבר לתחתית, או שליחת prompt חדש. המקשים Shift+E מנקים את כל הקיבועים, ו-Ctrl+E מנקה קיבועים על בלוקי חשיבה.

#תצורת בלוקים

[scrollback.blocks.edit]
indent = true                         
# indent diff content
vpad = false                          
# vertical padding
# expanded_by_default = true          
# unset: follows [ui] collapsed_edit_blocks in config.toml
                                      
# (flag on = collapsed one-liner); uncomment to pin either shape
dual_line_numbers = false             
# two-column line numbers (old + new)
# line_summary = false                
# show +N/-M in the collapsed header; unset follows the same flag
hunk_separator = "…"                  
# separator between diff hunks (default: "…")

[scrollback.blocks.prompt]
vpad = true                           
# vertical padding
show_prefix = true                    
# show prompt prefix character
min_lines = 2                         
# minimum content lines in sticky mode

[scrollback.blocks.thinking]
animate = true                        
# animated accent while thinking
truncated_lines = 3                   
# lines in truncated mode

#תוספים (Plugins)

[plugins]
disable_plugins = false               
# hide hooks/plugins UI entirely

#משתני סביבה

העיקריים שבהם. ראה את ה-README לרשימה המלאה.

#אימות

#נקודות קצה

#תכונות

#רישום יומנים (Logging)

#נתיבים

#טלמטריה

#מיקומי קבצים

#תצורה ברמת הפרויקט

הגדרות מסוימות ניתנות להגדרה ברמת הפרויקט על ידי הצבת קבצים בתוך .grok/ במאגר שלך:

שרתי MCP ברמת הפרויקט דורסים שרתים גלובליים בעלי אותו שם (החלפה מלאה, ולא מיזוג).

#שרתי LSP

שרתי שפה (Language servers) מפעילים אבחון פסיבי ואת כלי ה-lsp האופציונלי (ראה את דגל התכונה lsp_tools). הגדרות מגיעות משלושה מקורות ומתמזגות לפי שם השרת:

כאשר אותו שם שרת מגיע מיותר ממקור אחד, הוא נקבע לפי העדיפות הגבוהה ביותר תחילה:

1. פרויקט: .grok/lsp.json
2. משתמש: ~/.grok/lsp.json
3. תוספים: קובץ .lsp.json, ולאחר מכן בלוק lspServers מוטבע, לפי סדר טעינת התוספים

רשומות של פרויקט ושל משתמש מחליפות רשומות בעלות עדיפות נמוכה יותר עם אותו שם. רשומות של תוספים מוסיפות רק שרתים ששמותיהם עדיין אינם מוגדרים על ידי קובץ מקומי, כך שקובץ lsp.json מקומי תמיד מנצח תוסף. שרתי LSP של תוספים נטענים רק לאחר שהתוסף מוגדר כמהימן (ראה תוספים).