📘 תיעוד 35

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

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

#מודלים ברירת מחדל

כברירת מחדל, Grok משתמש במודלים שמתארחים ב-SpaceXAI, וסשנים חדשים מתחילים עם grok-4.5. מודלי ברירת מחדל לא דורשים הגדרה. התחברו עם grok login או מפתח API, ואז התחילו סשן.

רשימת כל המודלים הזמינים:

grok models

#בחירת מודל

#דגל CLI

grok -p "Hello" -m grok-4.6

#פקודת סלאש

ב-TUI, החליפו מודל במהלך סשן:

/model grok-4.6

או השתמשו בכינוי:

/m grok-4.6

#בוחר מודלים (Ctrl+M)

לחצו Ctrl+M מחלונית ה-scrollback כדי לפתוח את בוחר המודלים. הוא מציג את כל המודלים הזמינים, גם מובנים וגם מותאמים, ומאפשר לעבור בלחיצת מקש אחת. כשההנחיה בפוקוס, Ctrl+M מחליף קלט רב שורות. השתמשו ב-/model כדי להחליף בלי לעזוב את ההנחיה.

#רשימת היתר של הצי (requirements.toml)

מארחי ארגון יכולים לנעוץ את הקבוצה הניתנת לבחירה, ולא רק את ברירת המחדל, בקובץ requirements.toml חתום. הרשימה הזאת מחליפה כל allowed_models של המשתמש (זו לא איחוד), כך ש-/model, Ctrl+M ו--m לא יכולים להציע מודלים מחוץ לה.

[models]
default = "grok-4.5"
allowed_models = ["grok-4.5", "grok-4*"]

נעיצת צי תואמת את מזהה המודל (לא מפתח קטלוג שהמשתמש בחר), כך שרשומת [model.<name>] מקומית לא יכולה להרחיב את הקבוצה. allowed_models בהגדרות המשתמש עדיין תואם מפתח קטלוג או מזהה מודל. השמיטו את המפתח כדי להשאיר את הגדרות המשתמש במקומן. מערך ריק הוא בלי הגבלה. נעיצה שקיימת אבל לא ניתנת לקריאה נסגרת בכישלון (שום דבר לא ניתן לבחירה). ערך ברירת מחדל או -m מחוץ לקבוצה הנעוצה נדחה אחרי שקטלוג המודלים נמשך. פנו למנהל המערכת. הרשימה לא ניתנת לעריכה על ידי המשתמש.

#ברירת מחדל בהגדרות

הגדירו ברירת מחדל קבועה ב-~/.grok/config.toml:

[models]
default = "grok-4.5"

#צדדי API נתמכים

Grok תומך בשלושה צדדי API. הגדירו api_backend בהגדרות [model.*] כדי לבחור באיזה פרוטוקול המודל משתמש:

כשמשמיטים את api_backend, Grok משתמש ב-chat_completions.

כדי לשלוח אימות או כותרות גרסה ייחודיים לספק, לדוגמה x-api-key של Anthropic, השתמשו בשדה extra_headers שמתואר בהמשך. Grok שולח את הכותרות האלה כלשונן עם כל בקשה לנקודת הקצה.

#הגדרת מודלים מותאמים

הוסיפו נקודות קצה של מודלים מותאמים ב-~/.grok/config.toml תחת מקטעי [model.<name>]:

[model.my-model]
model = "model-id"                        # Model identifier sent to the API
base_url = "https://api.example.com/v1"   # OpenAI-compatible endpoint
name = "Display Name"                     # Shown in the model picker
description = "Model description"          # Optional description
api_key = "sk-..."                        # API key for this provider (optional)
env_key = "XAI_API_KEY"                   # Env var holding the API key (optional; string or array)
api_backend = "chat_completions"          # "chat_completions", "responses", or "messages"
reasoning_summary = "concise"             # Responses API only: "none", "auto", "concise", or "detailed"
temperature = 0.7                         # Sampling temperature
top_p = 0.95                              # Nucleus sampling parameter
max_completion_tokens = 8192              # Maximum tokens per response
context_window = 128000                   # Total context window in tokens
extra_headers = { "x-api-key" = "sk-..." } # Extra request headers, sent verbatim (optional)
query_params = { api-version = "2026-07-22" } # Query params appended to every request URL (optional)
env_http_headers = { "X-Tenant" = "TENANT_TOKEN" }    # Headers from env vars, resolved at client build (optional)

#פתרון אישורים

Grok פותר את מפתח ה-API בסדר הזה:

1. השדה api_key בהגדרות המודל
2. משתנה הסביבה (או המשתנים) ששמם ב-env_key: מחרוזת בודדת או מערך של שמות. הערך הראשון שמוגדר ואינו ריק מנצח (לדוגמה env_key = ["MY_PROVIDER_API_KEY", "LC_MY_PROVIDER_API_KEY"] להעברת SSH מסוג LC_*)
3. אסימון הסשן שאיתו התחברתם (מ-grok login), למודל בלי api_key או env_key משלו
4. משתנה הסביבה XAI_API_KEY (נפילה גלובלית. Grok גם מקבל את GROK_CODE_XAI_API_KEY לתאימות לאחור)

כשמודל מגדיר api_key או env_key משלו אבל המפתח ריק או המשתנים שלו לא מוגדרים, Grok לא שולח את אסימון הסשן שלכם אל base_url שהמודל הגדיר, או את XAI_API_KEY אל api_base_url (base_url כשהוא לא מוגדר) שהמודל הגדיר, אלא אם כתובת ה-URL היא מארח xAI או כתובת [endpoints] התואמת, שבה כל מודל בלי מפתח משלו כבר משתמש. הבקשה אז נושאת בלי מפתח, והיומן מציין מה חסר. במסלול ה-daemon, מודל כזה לא מקבל XAI_API_KEY בנקודת קצה של מודל שאינה מארח xAI ואינה [endpoints] xai_api_base_url. מפתח או עוזר מפתח שהוגדר לנקודת הקצה הזאת עדיין מספק לה מפתח.

#חלון הקשר

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

#מגבלת גודל בקשה

max_request_bytes הוא גוף הבקשה הגדול ביותר שנקודת הקצה מקבלת. Grok מפנה תמונות מוטמעות ישנות יותר מהשיחה כדי להישאר מתחתיה, כך שסשן עם הרבה צילומי מסך ממשיך לעבוד במקום להידחות. כשמשמיטים אותו, Grok בוחר את ברירת המחדל של api_backend: 30 MB עבור messages, ו-50 MiB עבור chat_completions ו-responses. הגדירו אותו רק כשהמארח שלכם אוכף תקרה אחרת.

התקרה היא תכונה של נקודת הקצה, ולכן היא עובדת גם על בלוק [model_providers.<id>] משותף, שבו כל מודל שמצביע על הספק הזה יורש אותה. max_request_bytes על המודל עצמו דורס את ערך הספק.

[model_providers.messages-gateway]
base_url = "https://gateway.example/v1"
api_backend = "messages"
max_request_bytes = 25000000   # every model on this provider inherits it

[model.claude-sonnet]
model = "claude-sonnet"
model_provider = "messages-gateway"   # inherits 25 MB

[model.claude-opus]
model = "claude-opus"
model_provider = "messages-gateway"
max_request_bytes = 20000000   # per-model override

#כותרות ברירת מחדל גלובליות

כדי להחיל את אותן כותרות על כל מודל בקטלוג, מובנה, שנמשך מראש מ-/v1/models, או מותאם, הגדירו אותן פעם אחת תחת המקטע הגלובלי [models] במקום לחזור עליהן לכל מודל:

[models]
extra_headers = { "X-Request-Tags" = "team=example,env=prod" }

אלה משמשות כבסיס לבקשות ההסקה של כל מודל. רשומת [model.<id>].extra_headers לכל מודל דורסת את ברירת המחדל הגלובלית לפי מפתח (התאמה בלי תלות ברישיות): מפתח שמוגדר על המודל מנצח, בעוד שמפתחות שקיימים רק ברמה הגלובלית עדיין עוברים בירושה למודל הזה. כמו השדה לכל מודל, הן נוסעות על קריאות ההסקה של המודל הזה, לא על שירותים נפרדים כמו יצירת תמונות או יצירת וידאו, מה שהופך אותן נוחות לתגיות שיוך (לדוגמה, מעקב עלויות) בלי להצהיר עליהן מחדש בכל פעם שמודל חדש מופיע.

#ערכי ברירת מחדל גלובליים

כמה הגדרות נפוצות לכל מודל אפשר גם להגדיר פעם אחת תחת [models] כברירת מחדל לכל מודל. ערך [model.<id>] לכל מודל תמיד מנצח. הגלובלי רק ממלא מקום שהמודל (או רשימת המודלים של השרת) השאיר את השדה לא מוגדר:

[models]
temperature                 = 0.7
top_p                       = 0.95
max_completion_tokens       = 8192
max_retries                 = 8
rate_limit_retry_threshold  = 4
inference_idle_timeout_secs = 600
subagent_rate_limit_max_attempts = 8
stream_tool_calls           = true

זו קבוצה קטנה וקבועה של כפתורי כוונון ברמת הסביבה. הגדרות שמזהות מודל מסוים (model, base_url, api_key, context_window, ...) אי אפשר להגדיר כברירת מחדל בדרך הזאת, וכמה הגדרות עם הגדרה ייעודית משלהן, דחיסה אוטומטית ([session]), תווית הנחיית המערכת ([agent]), ומאמץ חשיבה ([models].default_reasoning_effort), נשארות במקומן הקיים.

rate_limit_retry_threshold ו-subagent_rate_limit_max_attempts בוחרים נתיבי ניסיון חוזר שונים של 429 עבור סוכני משנה. הגדרת rate_limit_retry_threshold גורמת לדוגם להיות הבעלים של הניסיונות החוזרים האלה ומבטלת את לולאת ההמתנה הנפרדת של סוכן המשנה, כולל תקציב ההמתנה המצטבר של 150 שניות וטלמטריית ההמתנה. subagent_rate_limit_max_attempts חל רק כשסף הדוגם לא מוגדר.

הערה על stream_tool_calls: זה משפיע על צורת הבקשה, לא רק על הדגימה. כמה נקודות קצה (חלק מספקי BYOK) מצפות שהוא יישאר לא מוגדר. אם stream_tool_calls = true גלובלי גורם לבעיות למודל כזה, בטלו את ההצטרפות של המודל עם stream_tool_calls = false בבלוק [model.<id>] שלו.

#פרמטרי שאילתה של בקשה

חלק מהשערים מנתבים או קובעים גרסה לפי מחרוזת השאילתה. query_params מוסיף פרמטרי שאילתה בקידוד אחוזים לכל בקשה ש-Grok שולח עבור מודל. לדוגמה, שער שבוחר גרסת API כך:

[model.my-gateway]
model = "my-model"
base_url = "https://gateway.example/v1"
api_backend = "responses"
env_key = "GATEWAY_API_KEY"
query_params = { api-version = "2026-07-22" }

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

#כותרות ממשתני סביבה

env_http_headers ממפה כותרת בקשה לשם של משתנה סביבה שמספק את הערך שלה, כך שסוד לכל בקשה אף פעם לא חייב להיכתב לתוך config.toml:

[model.gateway]
model = "my-model"
base_url = "https://gateway.example/v1"
env_http_headers = { "X-Tenant-Token" = "GATEWAY_TENANT_TOKEN" }

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

שני השדות עובדים גם על בלוק [model_providers.<id>] משותף. מודל שמצביע על ספק עם model_provider = "<id>" יורש את query_params ו-env_http_headers של הספק כשהוא לא מגדיר משלו, בהתאמה לאופן שבו extra_headers עובר בירושה.

#הודעת מודל

notice שם הודעה מעל ההנחיה כל עוד המודל נבחר. אי אפשר לסגור את הבאנר. הוא נעלם כשעוברים למודל בלי הודעה.

[model.legacy]
model = "legacy-model"
base_url = "https://gateway.example/v1"
notice = { severity = "warning", text = "This model is deprecated on Oct 15. Switch to grok-4.6.", label = "deprecated" }

severity קובע את צבע הבאנר והוא info, warning, או critical. ברירת המחדל היא info. text נדרש, וטקסט ארוך נשבר לשורות. label הוא תג קצר אופציונלי שמוצג לפני הטקסט. נקודת קצה של מודלים מותאמים יכולה לשלוח את אותו אובייקט כ-notice או _meta.notice ברשומת מודל. טבלת [model.<id>] שומרת את ההודעה והתיאור של המודל המובנה או המרוחק שהיא מציינת, לפי מזהה או לפי model, אלא אם היא מגדירה משלה. כדי להסיר הודעה שמודל מובנה או מרוחק נושא, הגדירו notice = { text = "" }. עם auth_provider_command ונקודת קצה של מודלים, טבלאות [model.<id>] מתעלמות וההודעה של נקודת הקצה מוצגת.

#דריסת מודלים מובנים

אפשר לדרוס שדות מסוימים של מודלים מובנים בלי להגדיר הכל מחדש. ציינו רק את השדות שאתם רוצים לשנות. צטטו מזהה מודל שמכיל נקודה, כמו ב-[model."grok-4.6"] (ראו הגדרות).

כדי לדרוס רק את מפתח ה-API של מודל ברירת מחדל:

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

כדי לדרוס את הטמפרטורה ולהוסיף מפתח API מותאם:

[model."grok-4.6"]
temperature = 0.5
api_key = "sk-custom"

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

#סדר עדיפות

1. ההגדרות שלכם ([model.*]): העדיפות הגבוהה ביותר
2. מודלים שנמשכו מראש מ-/v1/models המרוחק
3. ברירות מחדל מקודדות קשיח: העדיפות הנמוכה ביותר

#דוגמאות ספקים

#Anthropic (Claude)

השתמשו במודלי Claude ישירות דרך Anthropic Messages API:

[model.claude-opus]
model = "claude-opus-4-6"
base_url = "https://api.anthropic.com/v1"
name = "Claude Opus 4.6"
api_backend = "messages"
context_window = 200000
extra_headers = { "x-api-key" = "sk-ant-...", "anthropic-version" = "2023-06-01" }

צד ה-messages משתמש בפרוטוקול Anthropic Messages. Anthropic מאמת עם כותרת x-api-key ולא עם Authorization: Bearer, אז העבירו את המפתח דרך extra_headers, ש-Grok שולח כלשונו.

#OpenAI (Chat Completions)

[model.gpt-4o]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
name = "GPT-4o"
env_key = "OPENAI_API_KEY"

api_backend ברירת המחדל היא "chat_completions", אז אין צורך להגדיר אותו במפורש עבור OpenAI.

#OpenAI (Responses API)

אם הספק תומך ב-Responses API החדש יותר:

[model.gpt-4o-responses]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
name = "GPT-4o (Responses)"
api_backend = "responses"
env_key = "OPENAI_API_KEY"

ב-Responses API, Grok מבקש כברירת מחדל סיכום חשיבה concise. מזה מגיע טקסט החשיבה שמוצג בממשק. reasoning_summary משנה את הבקשה: detailed או auto לסיכום מלא יותר, או none כדי להשמיט את השדה עבור שערים שדוחים אותו.

#AWS Bedrock (Mantle)

השער התואם OpenAI של Bedrock דוחה את reasoning.summary, אז הגדירו reasoning_summary = "none". הוא מאמת עם מפתח API של Bedrock כאסימון bearer. הדוגמה למטה מנפיקה אחד קצר מועד דרך ספק אימות בשם:

[auth_provider.bedrock]
command = "aws-bedrock-token"   # prints a Bedrock API key on stdout (e.g. via aws-bedrock-token-generator)
token_ttl_secs = 3600

[model."bedrock-grok-4.6"]
model = "xai.grok-4.6"
base_url = "https://bedrock-mantle.us-west-2.api.aws/openai/v1"
name = "Grok 4.6 (Bedrock)"
api_backend = "responses"
reasoning_summary = "none"
auth_provider = "bedrock"
context_window = 500000

#Ollama (מודלים מקומיים)

הריצו מודלים מקומית עם Ollama:

[model.ollama-codellama]
model = "codellama"
base_url = "http://localhost:11434/v1"
name = "CodeLlama (Ollama)"

ודאו ש-Ollama רץ (ollama serve) והמודל נמשך (ollama pull codellama).

#Together AI

[model.together-mixtral]
model = "mistralai/Mixtral-8x7B-Instruct-v0.1"
base_url = "https://api.together.xyz/v1"
name = "Mixtral 8x7B"
env_key = "TOGETHER_API_KEY"

#שרת מקומי תואם OpenAI

כל שרת שמממש את OpenAI Chat Completions או את Responses API:

[model.local-llama]
model = "llama-3.1-70b"
base_url = "http://localhost:8080/v1"
name = "Local Llama"
temperature = 0.8

#נקודת קצה של מודלים מותאמים

כוונו את Grok לנקודת קצה /v1/models תואמת OpenAI מותאמת במקום ברירת המחדל. השתמשו בזה כשהמודלים שלכם יושבים מאחורי שער ארגוני או שירות הסקה באירוח עצמי.

#משתני סביבה

#הגדרה

export GROK_MODELS_BASE_URL="https://api.acme.com/v1"
export XAI_API_KEY="xai-..."
grok

#חלופת קובץ הגדרות

[endpoints]
models_base_url = "https://api.acme.com/v1"

# Override only the API key for a specific model
[model."grok-4.6"]
api_key = "my-api-key"

כשמשתמשים ב-[endpoints] עם דריסות חלקיות של מודל, Grok יורש את base_url מהגדרות נקודות הקצה. אין צורך לציין אותו בכל מקטע [model.*]. XAI_API_KEY עדיין נדרש. api_key או env_key לכל מודל מאמתים בקשות הסקה עבור המודל הזה. משיכת רשימת המודלים בהפעלה תמיד משתמשת ב-XAI_API_KEY.

#התנהגות אימות

כשמגדירים models_base_url, Grok מאמת את בקשת רשימת המודלים עם XAI_API_KEY בלבד (Authorization: Bearer). הבקשה הזאת אף פעם לא משתמשת בסשן grok login. עם ספק אימות חיצוני (auth_provider_command) ובלי XAI_API_KEY, הוא שולח את האסימון של הספק במקום. אחרת, אם XAI_API_KEY לא מוגדר, המשיכה נכשלת עם שגיאה שמבקשת להגדיר אותו. בקשות הסקה למארח המותאם מאומתות בנפרד. api_key או env_key על כל מודל גורמים לבקשות האלה להשתמש גם במפתח API.

#מודל חיפוש באינטרנט

הכלי web_search משתמש במודל נפרד. מגדירים אותו כך:

[models]
web_search = "grok-4.5"

או דרך משתנה סביבה:

export GROK_WEB_SEARCH_MODEL="grok-4.5"

אם מפנים את חיפוש האינטרנט למודל מותאם, צריך גם רשומת [model.*] כדי שגרוק יוכל להגיע אליו. חיפוש אינטרנט בצד השרת ("backend") רץ רק כשהמודל מגדיר supports_backend_search = true (והבילד מפעיל חיפוש backend). הוא לא תלוי ב-api_backend:

[models]
web_search = "my-custom-model"

[model.my-custom-model]
model = "my-custom-model"
supports_backend_search = true

בנקודת קצה של מודל, הדמון עולה בלי משתני אישורים כמו XAI_API_KEY, GROK_AUTH ו-GROK_CODE_XAI_API_KEY, ולכן מודל חיפוש אינטרנט ש-env_key שלו מציין אחד מהם לא מקבל שם מפתח, וגרוק מזהיר בעת ההפעלה.

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

# List available models (including custom)
grok models

# Use in the TUI via slash command
/model my-model

# Use in headless mode
grok -p "Hello" -m my-model

# Set as default in config.toml:
[models]
default = "my-model"

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

תצורה מלאה לפריסה ארגונית עם מודלים מותאמים:

[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

#פתרון בעיות

#המודל לא נמצא

# List available models
grok models

# Check config.toml for typos in [model.*] sections

#שגיאות חיבור

בדקו שנקודת הקצה נגישה:

curl -s https://api.example.com/v1/models \
  -H "Authorization: Bearer $XAI_API_KEY"

#יומן דיבאג

RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok
tail -f /tmp/grok.log

חפשו רשומות יומן שמכילות model או sampling כדי לעקוב אחרי בחירת המודל וקריאות ה-API.