📘 תיעוד 38

מצב ללא ממשק (Headless) וכתיבת סקריפטים

מצב ללא ממשק (Headless mode) מריץ את Grok באופן לא אינטראקטיבי משורת הפקודה. הוא מקבל הנחיה יחידה, מבצע אותה עם גישה מלאה לכלים, ומחזיר את התוצאה. השתמש בו כדי לבצע אוטומציה של משימות, לכתוב סקריפטים לתהליכי עבודה, לבנות אינטגרציות ולפענח פלט בצורה תכנותית.

#שימוש בסיסי

העברת הנחיה באופן לא אינטראקטיבי מפעילה מצב headless. הדרך הנפוצה ביותר היא הדגל -p (קיצור של --single), וגם הדגלים --prompt-json ו---prompt-file מפעילים אותו:

grok -p "Your prompt here"

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

#אפשרויות שורת הפקודה

הערה: הדגלים --tools, --disallowed-tools, --max-turns ו---agents הם דגלים למצב headless בלבד. אם משתמשים בהם ב-TUI האינטראקטיבי, מודפסת אזהרה והדגל זוכה להתעלמות. הדגלים --reasoning-effort/--effort, --permission-mode, --allow ו---deny פועלים בשני המצבים. לדגלים נוספים (סוכנים ו-worktrees), ראה דגלים נוספים למצב Headless.

#סינון כלים

השתמש ב---tools כדי להגביל את הסוכן לקבוצה מפורשת של כלים (רשימת היתרים), או ב---disallowed-tools כדי להסיר כלים ספציפיים מקבוצת ברירת המחדל (רשימת חסימות). שניהם מקבלים שמות כלים מופרדים בפסיקים.

שמות הכלים הם מזהי כלים פנימיים (למשל כלי המעטפת הוא run_terminal_cmd, לא bash).

# Only allow read-only tools
grok -p "Explain this codebase" --tools "read_file,grep,list_dir"

# Remove web access and file editing
grok -p "Review this code" --disallowed-tools "web_search,web_fetch,search_replace"

# Remove shell access
grok -p "Review this code" --disallowed-tools "run_terminal_cmd"

הדגל --disallowed-tools תומך גם ברשומות Agent מיוחדות כדי לשלוט ביצירת תת-סוכנים:

# Prevent the agent from spawning any subagents
grok -p "Fix this bug" --disallowed-tools "Agent"

# Block only the explore subagent
grok -p "Refactor this module" --disallowed-tools "Agent(explore)"

הדגל --tools משמר את מדיניות ההזרקה של פרופיל הסוכן שנבחר: פרופילים סטנדרטיים (stock) מזריקים כלים אופציונליים מופעלים לפני החלת רשימת ההיתרים, בעוד שפרופילים מוקפדים (curated) נשארים מחמירים. קבוצת הכלים הסופית שומרת על הכלים המבוקשים בתוספת כלי מטא של MCP הפעילים תמיד. כאשר שני הדגלים קיימים, --disallowed-tools מנצח.

#כללי הרשאות (--allow / --deny)

כללי הרשאות קובעים האם הפעלות כלים ספציפיות מאושרות אוטומטית, נדחות, או דורשות אישור משתמש. שלא כמו --disallowed-tools (אשר מסיר כלים לחלוטין), כללי הרשאות משאירים כלים זמינים אך מציבים שער בפני הפעלתם.

הכללים משתמשים בתחביר ToolPrefix(glob_pattern):

עבור כללי נתיב (Read, Edit, Write, Grep), התו * הוא תו כללי לרמה בודדת ו-** הוא רקורסיבי. עבור כללי Bash, התו * תואם לכל התווים כולל רווחים. קידומת חשופה ללא סוגריים תואמת לכל ההפעלות מאותו סוג, והביטוי Bash(cmd:*) שקול להתאמת קידומת על cmd. ראה 22-permissions-and-safety.md עבור סמנטיקת ההתאמה המלאה.

# Deny shell commands matching "rm*"
grok -p "Clean up this project" --deny "Bash(rm*)"

# Allow npm commands, deny sudo
grok -p "Set up the project" --allow "Bash(npm*)" --deny "Bash(sudo*)"

# Allow all bash commands (auto-approve without prompting)
grok -p "Build the project" --allow "Bash"

ניתן לחזור על --allow ו---deny. כללי חסימה (deny) מקבלים עדיפות על פני כללי היתר (allow).

#פורמטי פלט

מצב headless תומך בארבעה פורמטי פלט, הנבחרים באמצעות --output-format.

#plain (ברירת מחדל)

טקסט קריא לבני אדם, מתאים להצגה ישירה או להעברה בצינור (piping):

Here's a summary of the codebase...

#json

אובייקט JSON יחיד הנפלט לאחר השלמת התגובה: טקסט התגובה, סיבת עצירה, מזהה הפעלה, מזהה בקשה (בתוספת thought כאשר קיימת חשיבה). כאשר ההנחיה הגיעה למודל, אותו אובייקט נושא גם שדות עלות ושימוש (usage, num_turns, modelUsage, עלות). השדה stopReason הוא אסימון ACP/Messages בפורמט snake_case (כגון end_turn, max_tokens, ועוד).

{
  "text": "Here's a summary of the codebase...",
  "stopReason": "end_turn",
  "sessionId": "abc123",
  "requestId": "xyz789",
  "num_turns": 7,
  "usage": {
    "input_tokens": 7210,
    "cache_read_input_tokens": 41000,
    "cache_creation_input_tokens": 0,
    "output_tokens": 1893,
    "reasoning_tokens": 412,
    "total_tokens": 50103
  },
  "modelUsage": {
    "grok-4.6": {
      "inputTokens": 7210,
      "outputTokens": 1893,
      "cacheReadInputTokens": 41000,
      "modelCalls": 7,
      "costUSD": 0.01268905
    }
  },
  "total_cost_usd": 0.01268905,
  "total_cost_usd_ticks": 126890500
}

הערות שימוש:

• השדה usage מסכם אסימונים עבור ההנחיה, כולל תת-סוכנים שהסתיימו לפני סיום התור (מופיעים גם תחת מפתחות modelUsage משלהם). דחיסה (compaction) וקריאות מודל צדדיות אחרות אינן נכללות.
• מדיניות שדות אסימונים (תוצאת headless / end / עלות שגיאה):
  • השדות usage.input_tokens ו-modelUsage.*.inputTokens הם עבור אסימונים שלא נשמרו במטמון בלבד.
  • השדות cache_read_input_tokens / cacheReadInputTokens הם פגיעות במטמון (cache hits).
  • השדה total_tokens הוא סך הקלט המלא + הפלט (כולל את שני סלי המטמון): total_tokens = input_tokens + cache_read_input_tokens + cache_creation_input_tokens + output_tokens.
  • השדה _meta.usage.inputTokens ב-ACP (המכונה PromptUsage) הוא עדיין סכום ההנחיה המלא, רק המקרין של headless מחסיר את המטמון. העדף שדות headless עבור אוטומציה של עלויות.
• השדה num_turns סופר סבבי מודל של הסוכן הראשי שנרשמו בספר ההנחיה (סבבי לולאת כלים שדיווחו על שימוש). קריאות דוגם של תת-סוכנים אינן מגדילות אותו. ספירות קריאות לפי מודל (כולל תת-סוכנים) נשארות תחת modelUsage.*.modelCalls. זו אותה משפחת מונים כמו --max-turns, אך אינה ערובה לשוויון מדויק כאשר סבבים חסרים נתוני שימוש או נתקלים בשערים.
• השדה total_cost_usd מופיע רק כאשר השרת דיווח על עלות מלאה. היעדרו מציין עלות שלא דווחה או שאינה מלאה, ולעולם לא עלות חינמית. עלות מוטבעת כיום עבור תעבורת מפתח API, ומסלולי pool/OAuth משמיטים אותה לעיתים קרובות עד שהשרת יטביע עלות. כאשר בחלק מהקריאות הייתה חסרה עלות, cost_is_partial מוגדר כ-true וכל מספרי ה-float של העלות מושמטים (total_cost_usd וכל modelUsage.*.costUSD), כדי שצרכנים לא יוכלו לסכם שורות מודל לחשבון שלם ומזויף.
• השדה total_cost_usd_ticks הוא אותו ערך במספרים שלמים מדויקים של ticks (ערך של 1 דולר אמריקאי = 10^10 טיקים) ומופיע תחת אותם תנאים. השתמש בו להתאמת חיובים: סיכום טיקים לפי הפעלה תואם בדיוק לייצוא השימוש של השרת, דבר שמספרי float של דולרים אינם יכולים להבטיח.
• כאשר לא ניתן היה להחיל שימוש של תת-סוכנים, שימוש של תת-סוכנים מקוננים היה חלקי, או שפעולת הריקון (drain) במסלול ההצלחה חרגה ממגבלת הזמן (עד 120 שניות במשימת התור), השדה usage_is_incomplete מוגדר כ-true ומספרי ה-float של העלות מושמטים באותו אופן (סכומי האסימונים עשויים לספור בחסר תת-סוכנים). פעולת ביטול מצלמת תמונת מצב ללא אותו ריקון ארוך ומסמנת כלא שלם כאשר תת-סוכנים עדיין פעילים. מצב לא שלם ללא אסימונים שנרשמו פולט רק את usage_is_incomplete (ללא אובייקט usage מאופס).
• הנחיה שמעולם לא הגיעה למודל משמיטה את שדות העלות והשימוש.

השדה sessionId שימושי לחידוש השיחה מאוחר יותר.

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

{"type":"error","message":"Couldn't start session: ..."}

#streaming-json

פורמט JSON מופרד בשורות חדשות (Newline-delimited JSON), אובייקט אחד מתויג לפי type לכל שורה, הנגזר מעדכוני הפעלת ACP של הסוכן. שמות שדות העלים (toolCallId, kind, rawInput, rawOutput) עוקבים אחר ACP, והשדה toolName ושורת ה-usage הם תוספות של xAI. צרוך אותו על ידי בדיקת השדה type.

{"type":"thought","data":"Analyzing the directory structure..."}
{"type":"tool_call","toolCallId":"call_1","title":"Read","kind":"read","status":"in_progress","toolName":"read_file","rawInput":{"path":"src/main.rs"},"content":[],"locations":[]}
{"type":"tool_call_update","toolCallId":"call_1","status":"completed","content":[],"rawOutput":{"lines":42},"locations":[]}
{"type":"text","data":"Here's a summary"}
{"type":"usage","messageId":"resp_1","stopReason":"end_turn","usage":{"input_tokens":812,"output_tokens":45,"cache_read_input_tokens":0,"cache_creation_input_tokens":0,"reasoning_tokens":0},"signature":"..."}
{"type":"end","stopReason":"end_turn","sessionId":"abc123","requestId":"xyz789","usage":{...},"num_turns":7,"modelUsage":{...}}

סוגי אירועים:

האירוע end הוא תמיד האירוע האחרון. שדות עלות ושימוש ב-end תואמים למבנה של אובייקט ה-json (שדה input_tokens בפורמט snake_case ללא מטמון, ומספרי float בטוחים של עלות). השדה end.stopReason הוא סיבת עצירת התור בפורמט snake_case (כגון end_turn, max_tokens, max_turn_requests, refusal, cancelled), וסיבת הספק המדויקת לכל תגובה (למשל tool_use, pause_turn) נמצאת ב-stopReason של שורת ה-usage. השדות message_id/stopReason/signature לכל תגובה מאוכלסים בצד השרת של Messages API, וצדדי שרת אחרים מדווחים על מה שהם נושאים.

Grok עשוי לפלוט גם אירועי max_turns_reached ו-auto_compact_*, התייחס לרשימה ככזו שאינה ממצה ובצע בדיקה לפי type.

#streaming-messages-json

פורמט JSON מופרד בשורות חדשות במבנה השידור stream-json של Messages API. משטח נשיאת הנתונים תואם במדויק למבנה של Messages. זה כולל את גופי ההודעות של assistant/user, את usage, את tool_use/tool_result, חיפוש רשת משולב (inline web search), את stop_reason ואת מסגור האירועים של --include-partial-messages. צרכן שמשחזר הודעות, קורא נתוני שימוש ועלות או מזהה שגיאות פועל ללא שינויים.

שורות system/init ושורת ה-result הסופית נושאות מטא-נתונים. Grok פולט את השדות שיש לו עבורם נתונים אמיתיים ומשמיט שדות שהם מצייני מקום בלבד שאינו יכול למלא, במקום למלא אותם באפסים. כתוצאה מכך, שתי שורות אלו עשויות שלא לעבור אימות סכמה קפדני של init/result. השדות הבודדים מפורטים להלן. קרא את הערות הדיוק לפני שתתייחס לשדה כלשהו כמוסמך. עבור תזרים נקי ומקורי של xAI ללא תבניות מצייני מקום, השתמש ב-streaming-json.

התזרים נפתח בשורת system/init, לאחר מכן הודעות assistant שהמערך message.content[] שלהן מכיל בלוקים של text, thinking ו-tool_use, הודעות user הנושאות בלוקים של tool_result, ושורת result סופית:

{"type":"system","subtype":"init","session_id":"abc123","apiKeySource":"user","model":"grok-4.6","cwd":"/repo","permissionMode":"default","tools":["read_file","bash"],"slash_commands":["review"],"mcp_servers":[{"name":"linear","status":"connected"}],"skills":[],"uuid":"..."}
{"type":"assistant","message":{"id":"msg_0","type":"message","role":"assistant","model":"grok-4.6","content":[{"type":"text","text":"Let me read the file."},{"type":"tool_use","id":"call_1","name":"read_file","input":{"path":"src/main.rs"}}],"stop_reason":"tool_use","stop_sequence":null,"usage":{...}},"parent_tool_use_id":null,"session_id":"abc123","uuid":"..."}
{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"call_1","content":"fn main() {}","is_error":false}]},"parent_tool_use_id":null,"session_id":"abc123","uuid":"..."}
{"type":"result","subtype":"success","is_error":false,"duration_ms":0,"duration_api_ms":0,"num_turns":7,"result":"Here's a summary...","stop_reason":"end_turn","total_cost_usd":0.0127,"usage":{"input_tokens":812,"output_tokens":210,"cache_read_input_tokens":0,"cache_creation_input_tokens":0,"server_tool_use":{"web_search_requests":0}},"modelUsage":{},"session_id":"abc123","uuid":"..."}

סוגי הודעות:

הודעות ה-assistant וה-user נושאות את session_id, uuid ו-parent_tool_use_id (המוגדר כ-null עבור השיחה הראשית). שורות ה-system/init ושורת ה-result הסופית נושאות את session_id ו-uuid, אך ללא parent_tool_use_id.

השדה uuid בכל שורה מיוצר מחדש עבור כל שורה שנפלטת. הוא אינו מזהה ספק, הודעה או אירוע, ואינו מפתח התאמה (correlation key). הוא אינו תואם ל-message.id של הספק (ערך זה נמצא ב-assistant.message.id). הוא ייחודי לכל שורה, אפילו עבור שורות המתארות את אותה ההודעה, והוא אינו נושא זהות בין שורות או בין הרצות שונות. אל תשתמש בו כדי לבצע התאמה או מניעת כפילויות.

מקטעי טקסט וחשיבה מקובצים להודעת assistant אחת לכל תגובת מודל. בלוקי tool_result מקביליים של תגובה מקובצים להודעת user בודדת. השדה result.result הוא טקסט הודעת ה-assistant האחרונה. תגובת מודל שאינה מייצרת בלוקי תוכן אינה פולטת שורת assistant במצב ברירת המחדל. רק הדגל --include-partial-messages מציג תגובה כזו, כמעטפת message_start עד message_stop ריקה.

באירוע init, השדה skills פעיל. הוא מפרט את שמות המיומנויות הניתנות להפעלה על ידי המשתמש בהפעלה זו, תת-קבוצה של slash_commands שמקורה בפקודות שההפעלה מפרסמת, או [] כאשר ההפעלה אינה מציגה מיומנויות. שורת ה-init נפלטת פעם אחת, תוך השהייתה לשורת הפלט הראשונה כדי שתלכוד את ה-tools, slash_commands ו-skills המפורסמים של ההפעלה. סכמת Messages אינה מגדירה init שני, ולכן רשימת פקודות שמשתנה לאחר תחילת התזרים אינה מפורסמת מחדש.

שאר שדות ה-init נושאים נתונים אמיתיים:

• apiKeySource מוגדר כ-user עבור אימות באמצעות מפתח API, ו-oauth בכל מצב אחר. Grok אינו מבדיל בין מקורות project, org ו-temporary של הסכמה.
• permissionMode הוא מצב ה-headless הפעיל הממופה ל-enum של Messages: הערך של --permission-mode, או bypassPermissions תחת --yolo, אחרת default. מצבים ייחודיים ל-Grok כמו auto מתכנסים ל-default.
• mcp_servers[].status משקף הגדרה, ולא מצב חיבור חי. שרת מוגדר מדווח תמיד על "connected", מכיוון שמצב לחיצת היד (handshake) של כל שרת אינו מיושב עד למועד שבו init נפלט.

Grok משמיט שדות init של הסכמה שהם מצייני מקום בלבד שאין לו נתונים עבורם, במקום לפלוט ערכי דמה: claude_code_version, output_style ו-plugins.

השדה result כולל את duration_ms, duration_api_ms, num_turns, stop_reason, total_cost_usd, usage (במבנה message.usage של Messages API), ואת modelUsage. הוא כולל גם את errors[] בתת-סוגי שגיאה. Grok משמיט את השדה הריק תמיד של הסכמה permission_denials, מכיוון שאינו אוסף דחיות הרשאה. השדה structured_output (יחד עם --json-schema) מופיע בפורמט snake_case, בהתאם לסכמה.

השדה model מופיע ב-init ובכל מסגרת של assistant. זהו מזהה המודל האמיתי כאשר הוא ידוע, והמחרוזת המילולית "unknown" רק כאשר לא ידוע אף מודל בזמן הפליטה.

השדה stop_sequence של מסגרת ה-assistant מחווט מקצה לקצה. הוא נושא את רצף העצירה התואם של הספק כאשר המודל עצר ברצף מוגדר (stop_reason: "stop_sequence"), והוא null בכל סיבת עצירה וצד שרת אחרים. במסגור של --include-partial-messages, הרצף התואם מועבר גם במסגרת ה-assistant שנשטפה וגם ב-message_delta.stop_sequence החלקי, כך שבנייה מחדש חלקית תואמת למסגרת. רק השדה message_start.stop_sequence החלקי נשאר null, מכיוון שהרצף התואם אינו ידוע בפתיחת ההודעה.

תת-סוגי השגיאה הנפלטים הם error_max_turns, error_during_execution ו-error_max_structured_output_retries. תת-הסוג error_max_budget_usd של הסכמה לעולם אינו נפלט, מכיוון של-Grok אין תכונת תקציב.

השדה result.usage מדווח על מבנה message.usage של Messages כאשר שלושת סלי האסימונים נפרדים זה מזה: input_tokens (ללא מטמון), cache_read_input_tokens ו-cache_creation_input_tokens. Grok גוזר אותם מספר החשבונות המצטבר של התור, המעוצב מחדש לסלים אלו. יצירת מטמון של תת-סוכנים נכללת ב-cache_creation_input_tokens. ספר החשבונות המצטבר עוקב אחריו כסל עצמאי משלו, ולכן הוא אינו מקופל עוד לתוך input_tokens.

השדה result.usage פולט תמיד סלים מספריים, גם כאשר נתונים חסרים. הדבר קורה כאשר ספר השימוש של התור אינו מלא (אותו תנאי שמציג את usage_is_incomplete בפורמט json), או כאשר אף ספר חשבונות מצטבר לא הגיע למצמצם (reducer) כלל. כל סל ש-Grok אינו יכול לחשב נסוג ל-0, מכיוון שלסכמת Messages API אין סימון עבור שימוש חלקי או חסר. המצמצם מתעד אזהרה ל-stderr בשני המקרים. יש לקרוא שדה usage שכולו אפסים כאן כ-"לא ידוע", ולא כ-"חינמי".

מונה ה-server_tool_use המקונן מאוכלס. השדה web_search_requests מייצג את מספר חיפושי הרשת המוצלחים בצד השרת שנפלטו בהרצה זו. חיפושים שנכשלו ופעולות WebSearch שאינן חיפוש כגון open_page אינן נכללות, בהתאם ל-Messages API, שאינו מחייב על חיפושים שגוים. חיפוש צד שרת שנכשל עדיין פולט web_search_tool_result במבנה שגיאה (content.type: "web_search_tool_result_error"), אך אינו נספר. ערך ה-error_code שלו הוא מציין מקום קבוע מסוג "unavailable", ולא קוד שהועבר מהשרת. אין מפתח web_fetch_requests, מכיוון של-Grok אין web_fetch בצד השרת, ולכן מציין המקום מושמט.

חיפוש רשת בצד השרת הוא משולב (inline). הוא מתקפל לתוך אותה מסגרת assistant שבה נמצא הטקסט המקיף אותו. המסגרת נושאת בלוק server_tool_use (הכולל name: "web_search", input.query) ומיד לאחריו בלוק web_search_tool_result. השדה tool_use_id של בלוק תוצאה זה תואם ל-server_tool_use.id, והתוכן שלו (content) הוא מערך תוצאות web_search_result של {type, url, title}. הדבר תואם למבנה כלי צד שרת משולב של Messages API במקום לפצל את התגובה בין מסגרות.

חיפוש ב-X ומתורגמן קוד (code interpreter) מהווים חריגה מתועדת. הם נשארים כלליים, ומוצגים כבלוק tool_use של לקוח בתוספת tool_result של user, מכיוון ש-Messages API אינו מגדיר עבורם סוג בלוק משולב. כל שאר כלי הלקוח שומרים באופן דומה על ההפרדה בין tool_use ל-tool_result.

הדגל --include-partial-messages פולט את מסגור האירועים הגולמי כך שצרכן יכול לבנות מחדש כל הודעה באמצעות צובר התזרים של Messages. המסגור כולל את message_start, content_block_start/content_block_delta/content_block_stop, message_delta ו-message_stop. הוא נושא את האירועים המבניים שצובר זקוק להם. השינויים (deltas) גסים יותר מתזרים ברמת האסימון של Messages API: קלט כלים מגיע כ-input_json_delta יחיד, ו-citations_delta אינו מיוצר לעולם (ראה להלן). התוצאה היא שחזור נאמן של כל הודעה ולא שידור חוזר אסימון אחר אסימון.

בצד השרת של Messages API, המסגור נאמן למקור. השדה message_start נושא את ה-message.id האמיתי של הספק ואת ה-usage בצד הקלט. בלוק חשיבה פולט את ה-signature_delta שלו לפי הסדר, לפני ה-content_block_stop של הבלוק. צד הקלט של message_start.usage מדווח על כל שלושת סלי צד ההנחיה הידועים בעת פתיחת ההודעה: input_tokens (החלק שאינו במטמון), cache_read_input_tokens ו-cache_creation_input_tokens. פגיעה במטמון גלויה לפיכך ב-message_start, במקום להופיע רק מאוחר יותר ב-message_delta/result. השדה output_tokens מתחיל שם ב-0 ומסתיים סופית ב-message_delta. תגובה שמתחילה אך אינה מייצרת תוכן עדיין פולטת את מעטפת message_start עד message_stop ללא בלוקי תוכן.

חלק מצדדי השרת מציגים מטא-נתונים לכל תגובה רק בסוף התור. צדדי שרת אלו נסוגים ל-message_start.id מסונתז ולשימוש (usage) קלט שמאופס ל-0. הם דוחים את ה-signature של החשיבה לשורת ה-assistant הסופית, שהיא הקובעת במקרה זה.

קלט של קריאת כלי נפלט כ-input_json_delta יחיד הנושא את ה-JSON המלא של הארגומנטים, ולאחריו content_block_stop. אין זה רצף של מקטעים ברמת האסימון. זוהי סטייה מכוונת מתזרים ה-partial_json ההדרגתי של Messages API. מסלול קריאות הכלים ב-ACP של Grok מספק כל קריאת כלי כאובייקט JSON מאומת יחיד ברגע שהארגומנטים פוענחו במלואם, ולכן דלתא יחידה היא הייצוג המדויק. צרכן שמשרשר partial_json מרכיב מחדש את אותו אובייקט זהה בכל מקרה. השדה input.query של בלוק server_tool_use של חיפוש רשת בצד השרת נפלט באותו אופן, כ-input_json_delta יחיד.

השדה citations_delta של Messages API נושא ציטוטים משולבים עבור קטעי טקסט מצוטטים, כגון אלו שמקורם בחיפוש רשת. תזרים זה אינו מייצר אותו. דלתות התוכן של Messages ב-Grok מוגבלות לטקסט, חשיבה, חתימה ו-JSON של קלט כלים, כך שאין נתוני ציטוט להצגה כ-citations_delta. כתובות URL של מקורות חיפוש רשת בצד השרת מדווחות במקום זאת בתוך בלוק ה-web_search_tool_result שהושלם (ראה לעיל), ולא כציטוטי טקסט לכל קטע.

הסתייגויות דיוק חלות על מספר שדות.

השדה duration_ms הוא זמן השעון בפועל (wall clock) של ביצוע ההנחיה. השדה duration_api_ms הוא סכום זמני המודל המדווחים לכל קריאה. קריאת מודל שאינה מדווחת על משך הזמן שלה תורמת 0, ולכן duration_api_ms יכול לספור בחסר את זמן ה-API האמיתי.

השדות num_turns ו-total_cost_usd מוסמכים כאשר הם ידועים. כאשר אינם ידועים, num_turns נסוג לספירת תגובות המודל שהושלמו בתור זה, ו-total_cost_usd נסוג ל-0. תגובה שהושלמה אך ללא תוכן אינה פולטת שורת assistant, אך עדיין נספרת כתור. עלויות ושימוש לעולם אינם מדווחים ביתר.

השדה modelUsage נושא את שדות האסימונים והעלות לכל מודל ש-Grok עוקב אחריהם, בתוספת webSearchRequests המיוחסים למודל הפעיל. המצמצם עוקב אחר ספירת חיפושי רשת גלובלית יחידה ולא לפי מודל, ולכן הספירה כולה משויכת למודל הנוכחי או האחרון ושורות אחרות נשארות 0. ערך modelUsage.*.costUSD עבור מודל מסוים הוא 0 כאשר העלות של אותו מודל אינה ידועה או מעוכבת. זוהי אותה התנהגות נסיגה לאפס כמו total_cost_usd ברמה העליונה. פורמט ה-json משמיט מספרי float של עלות לחלוטין כאשר היא חלקית, אך תזרים זה שומר על קיום השדה וערכו 0. השדה contextWindow הוא חלון ההקשר הכולל האמיתי של המודל הנוכחי (אותו ערך שבו Grok משתמש לדחיסה אוטומטית), והוא מופיע רק בשורה של המודל הנוכחי. שורות אחרות משמיטות אותו, וכך גם השורה הנוכחית כאשר החלון אינו ידוע. ל-maxOutputTokens אין קטלוג ב-Grok, ולכן מפתח זה מושמט לחלוטין. השדה modelUsage הוא {} כאשר אין פירוט זמין לפי מודל.

בדומה ל-streaming-json, תזרים זה הוא לקריאה בלבד. אישורי כלים ותהליכים דו-כיווניים אחרים משתמשים בממשק ACP (grok agent).

#ניהול הפעלות במצב Headless

כברירת מחדל, כל הפעלה של grok -p יוצרת הפעלה חדשה. כדי לשמור על הקשר בין קריאות, השתמש בדגלי הפעלה.

#הפעלות בעלות שם (-s)

כדי להעביר הקשר בין קריאות headless, השתמש ב--r/--resume או ב--c/--continue. השתמש ב--s/--session-id רק עבור הפעלה חדשה עם UUID (מחזיר שגיאה אם אינו UUID או שכבר נמצא בשימוש תחת ספריית היעד). התנהגות עבר נסתרת של -s לעדכון או חידוש אינה קיימת עוד. השתמש ב--r/-c כדי להמשיך. יחד עם -r/-c, הדגל -s דורש את --fork-session:

# Start a headless session and capture its ID
grok -p "Review the changes in this PR" --output-format json | jq -r '.sessionId'

# Continue in the same session
grok -p "Now check for security issues" --resume "<id>"

# Optional: create with a client-chosen UUID (must not already exist)
grok -p "hello" --session-id "$(uuidgen | tr '[:upper:]' '[:lower:]')" --output-format json

הערה: הדגל -s/--session-id יוצר הפעלה חדשה בלבד (UUID תקין, שגיאה אם כבר בשימוש). השתמש ב--r לחידוש הפעלה.

#חידוש הפעלה (-r)

הדגל -r/--resume מחדש הפעלה ספציפית לפי מזהה, או לפי כותרת עבור הספרייה הנוכחית כאשר הערך אינו מזהה, תוך התעלמות מאותיות גדולות או קטנות (התאמה יחידה ששמה שונה ידנית מנצחת בין כפילויות, כפילויות שנותרו מחזירות שגיאה עם המזהים שלהן, ערכים במבנה UUID תמיד פונים למסלול המזהה, ולכן סקריפטים צריכים להעדיף מזהים). הדגל מחזיר שגיאה אם ההפעלה אינה קיימת:

# Get the session ID from a previous JSON response
grok -p "Remember: the secret number is 42" --output-format json
# Output includes "sessionId": "abc123"

# Resume that exact session
grok -p "What's the secret number?" --resume abc123

#המשך הפעלה (-c)

הדגל -c/--continue ממשיך את ההפעלה האחרונה בספריית העבודה הנוכחית:

grok -p "Continue where we left off" -c

#חילוץ מזהי הפעלה

השתמש ב---output-format json ופענח את השדה sessionId:

grok -p "Hello" --output-format json | jq -r '.sessionId'

#צינורות קלט ופלט (Piping)

מצב headless פועל באופן טבעי עם צינורות (pipes) והפניות פלט של Unix.

#פלט סטנדרטי (Standard Output)

# Pipe output to a file
grok -p "Generate a README" > README.md

# Parse JSON output with jq
grok -p "List files" --output-format json | jq -r '.text'

#קלט סטנדרטי (Standard Input)

מצב headless אינו קורא קלט סטנדרטי (stdin) שהועבר בצינור לתוך ההנחיה. העבר תוכן חיצוני באמצעות החלפת פקודה (command substitution) או באמצעות --prompt-file:

# Include git diff as context via command substitution
grok -p "Write a concise commit message for these changes:

$(git diff --staged)"

# Or read the prompt from a file
grok --prompt-file ./prompt.txt

#דוגמאות לשילוב ב-CI/CD

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

grok -p "Review changes for bugs and security issues." \
  --output-format json --yolo | jq -r '.text' > review.md

#Hook של Pre-Commit

grok -p "Review staged changes for obvious bugs. Reply OK if fine, or list issues." \
  --yolo --output-format json | jq -r '.text' | grep -q "^OK" || exit 1

#עיבוד באצווה (Batch Processing)

for file in src/*.js; do
  grok -p "Migrate $file from CommonJS to ES modules." --yolo
done

#דפוסי כתיבת סקריפטים

#מעטפת Python

ניתן לעטוף את מצב ה-headless של Grok כ-API להשלמת שיחה התואם ל-OpenAI:

import asyncio
import json
import os

class GrokChat:
    """Simple OpenAI-compatible wrapper using headless mode."""

    def __init__(self, cwd="."):
        self.cwd = cwd
        self.env = {**os.environ}

    def _build_cmd(self, prompt, model, stream):
        return ["grok", "-p", prompt, "-m", model, "--cwd", self.cwd,
                "--output-format", "streaming-json" if stream else "json",
                "--yolo"]

    async def create(self, messages, model="grok-4.6", stream=False):
        prompt = messages[-1]["content"] if len(messages) == 1 else "\n".join(
            f"{m['role']}: {m['content']}" for m in messages
        )
        cmd = self._build_cmd(prompt, model, stream)

        if stream:
            return self._stream(cmd)

        proc = await asyncio.create_subprocess_exec(
            *cmd, env=self.env, stdout=asyncio.subprocess.PIPE
        )
        stdout, _ = await proc.communicate()
        data = json.loads(stdout.decode()) if stdout else {"text": ""}
        return {
            "choices": [{
                "message": {"role": "assistant", "content": data.get("text", "")},
                "finish_reason": "stop"
            }]
        }

    async def _stream(self, cmd):
        proc = await asyncio.create_subprocess_exec(
            *cmd, env=self.env, stdout=asyncio.subprocess.PIPE
        )
        async for line in proc.stdout:
            if not line.strip():
                continue
            event = json.loads(line)
            if event.get("type") == "text":
                yield {"choices": [{"delta": {"content": event["data"]}}]}
            elif event.get("type") == "end":
                yield {"choices": [{"delta": {}, "finish_reason": "stop"}]}


async def main():
    client = GrokChat(cwd=".")
    response = await client.create(
        [{"role": "user", "content": "What files are here?"}]
    )
    print(response["choices"][0]["message"]["content"])

asyncio.run(main())

#סקריפט Shell

#!/bin/bash
# Run a code review and exit with failure if issues are found

RESULT=$(grok -p "Review this PR for bugs. Output JSON with 'issues' array." \
  --output-format json --yolo | jq -r '.text')

ISSUE_COUNT=$(echo "$RESULT" | jq '.issues | length' 2>/dev/null || echo "0")

if [ "$ISSUE_COUNT" -gt 0 ]; then
  echo "Found $ISSUE_COUNT issues"
  echo "$RESULT" | jq '.issues[]'
  exit 1
fi

echo "No issues found"

#אישור תמידי עבור אוטומציה

הדגל --always-approve (כינוי נוסף --yolo, זהה ל---permission-mode bypassPermissions) מריץ קריאות לכלים ללא בקשות אישור אינטראקטיביות. כללי חסימה (deny), הוקים (hooks) ונעילות מנהל עדיין חלים (ראה הרשאות ובטיחות).

grok -p "Format all files" --always-approve
grok -p "Run the tests and fix any failures" --cwd ~/projects/my-app --always-approve

עבור שרתי סוכנים וערכות פיתוח (SDK), ראה מצב סוכן.

#משתני סביבה למצב Headless

משתני סביבה מרכזיים המשפיעים על מצב headless:

עבור סביבות CI ללא גישה לדפדפן, הגדר את XAI_API_KEY עם מפתח API מתוך console.x.ai:

export XAI_API_KEY="xai-..."
grok -p "Run the test suite" --yolo

#קודי יציאה

#אימות עבור סביבות Headless

עבור שימוש ב-headless, בצע אימות באחת מהדרכים הבאות:

• XAI_API_KEY: הפשוט ביותר עבור CI. ראה משתני סביבה למצב Headless לעיל.
• grok login --device-auth (או --device-code): אין צורך בדפדפן במכונת היעד. ראה אימות > תהליך קוד מכשיר.
• grok login: אימות OAuth2 מבוסס דפדפן במכונות בעלות ממשק גרפי (GUI).

אם התחברת בעבר, נעשה שימוש אוטומטי באישורים השמורים במטמון.

#טיפים

• מצב headless מתחיל הפעלה חדשה כברירת מחדל. השתמש ב--r/--resume או ב--c/--continue כדי לשמור על הקשר בין קריאות.
• התגובה של --output-format json כוללת תמיד את sessionId שבו תוכל להשתמש עם --resume עבור קריאות המשך.
• שלב את --yolo עם --rules כדי להגדיר גבולות הגנה: grok -p "..." --yolo --rules "Never delete files".
• לצורך ניפוי שגיאות, העלה את רמת הרישום ולכוד את stderr: RUST_LOG=debug grok -p "..." 2> debug.log.

#זיהוי שורש הפרויקט

כאשר Grok מתחיל, הוא מזהה את שורש הפרויקט על ידי מעבר כלפי מעלה מ---cwd (או מהספרייה הנוכחית) עד שהוא מוצא ספריית .git.

הערה: אם --cwd מקונן בתוך מאגר גדול (כגון monorepo), Grok מזהה מאגר זה כשורש הפרויקט ותוחם את פעולות הזיהוי שלו (AGENTS.md, מיומנויות, היסטוריית git) אליו, מה שעלול להאט את העלייה. כוון את --cwd לתת-הפרויקט הספציפי שבו תרצה לעבוד כדי לשמור על היקף קטן.

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

Grok שומר נתונים ב-~/.grok (דריסה באמצעות GROK_HOME, ראה משתני סביבה למצב Headless):

#קריאה בלבד ב-~/.grok

עבור קונטיינרים או CI, עגן את ~/.grok במצב קריאה בלבד:

• אכלס מראש את auth.json או השתמש ב-XAI_API_KEY
• שמירת הפעלות נכשלת באופן שקט (ארעית / ephemeral)
• בדיקות עדכונים רושמות אזהרה ומדלגות

export XAI_API_KEY="xai-..."
export GROK_DISABLE_AUTOUPDATER=1
grok -p "..." --no-auto-update

#השבתת בדיקות עדכונים

הגדרת GROK_DISABLE_AUTOUPDATER לערך שקרי (כגון 0, false, off, no, או ריק, בכל שילוב אותיות) נחשבת כאינה מוגדרת. ערכות הפיתוח (SDKs) של הסוכן מזריקות GROK_DISABLE_AUTOUPDATER=1 עבור סוכנים שאינם מובילים שהן מפעילות (ערך שקרי בסביבת הבידוד של ה-SDK משאיר עדכונים פעילים), וסוכן ה-stdio מדלג על עדכון הרקע שלו אלא אם הוא רץ מההתקנה המנוהלת ($GROK_HOME/bin/grok).

הודעות עדכון נשלחות ל-stderr. ערוץ stdout נשאר נקי עבור --output-format json. ראה גם משתני סביבה למצב Headless.

#דגלים נוספים למצב Headless

דגלים אלו משלימים את טבלת אפשרויות שורת הפקודה לעיל. דגלים שכבר מפורטים שם (--prompt-json, --prompt-file, --verbatim, --sandbox, --no-auto-update) אינם חוזרים על עצמם כאן.

#הרצות Headless שהופסקו

בעת קבלת SIGINT או SIGTERM:

• מצב ההפעלה נשמר עד לקריאת הכלי האחרונה שהושלמה
• שינויים בקבצים שבוצעו על ידי כלים אינם מבוטלים (not rolled back)
• קוד היציאה הוא 130 עבור SIGINT (128 + 2) ו-143 עבור SIGTERM (128 + 15), צינורות CI יכולים להבדיל בין מקרים אלו לבין שגיאה רגילה (קוד יציאה 1)
• חידוש: grok -p "continue" --resume "<id>" או grok -p "continue" --continue

ראה ניהול הפעלות במצב Headless לפרטים על הפעלות בעלות שם והדגלים -s/-r/-c.