📘 תיעוד 152

הכתבה קולית

דברו את ההנחיות שלכם ב-CLI של Claude Code עם הכתבה קולית במצב החזקה להקלטה או הקשה להקלטה.

דברו את ההנחיות שלכם במקום להקליד אותן ב-CLI של Claude Code. הדיבור שלכם מתומלל בזמן אמת לתוך שדה ההנחיה, כך שאפשר לשלב קול והקלדה באותה הודעה. הפעילו הכתבה עם /voice, ואז או החזיקו מקש בזמן שאתם מדברים, או הקישו פעם אחת כדי להתחיל ופעם נוספת כדי לשלוח.

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

#דרישות

הכתבה קולית משדרת את השמע המוקלט לשרתים של Anthropic לתמלול. השמע לא מעובד באופן מקומי. נדרש כל מה שמופיע בהמשך:

• חשבון Claude.ai: שירות הדיבור לטקסט זמין רק כשאתם מאמתים עם חשבון כזה, והוא לא זמין כש-Claude Code מוגדר להשתמש ישירות במפתח API של Anthropic, ב-Amazon Bedrock, ב-Agent Platform של Google Cloud, או ב-Microsoft Foundry.
• מיקרופון מקומי: הכתבה קולית לא עובדת בסשנים בענן או בסשני SSH.
• WSLg, אם אתם מריצים את Claude Code ב-WSL: WSLg כלול ב-WSL2 כשההתקנה נעשית מ-Microsoft Store ב-Windows 10 או 11. אם WSLg לא זמין, למשל ב-WSL1, הריצו את Claude Code ב-Windows מקורי במקום זאת.

התמלול לא צורך הודעות או טוקנים של Claude ולא נספר במגבלות שמוצגות ב-/usage. ראו שימוש בנתונים לאופן שבו Anthropic מטפלת בנתונים שלכם.

הקלטת שמע משתמשת במודול מקורי מובנה ב-macOS, ב-Linux וב-Windows. ב-Linux, אם המודול המקורי לא מצליח להיטען, Claude Code עובר ל-arecord מ-ALSA utils או ל-rec מ-SoX. אם אף אחד מהם לא זמין, /voice מדפיס פקודת התקנה עבור מנהל החבילות שלכם.

תוסף VS Code של Claude Code תומך גם הוא בהכתבה קולית עם אותה דרישת חשבון claude.ai. הוא לא זמין בסשנים מרוחקים של VS Code, כולל SSH, Dev Containers ו-Codespaces, כי המיקרופון נמצא במחשב המקומי שלכם והתוסף רץ על המארח המרוחק.

#הפעלת הכתבה קולית

הריצו /voice כדי להפעיל הכתבה. כשאתם מפעילים אותה, Claude Code מריץ בדיקת מיקרופון. ב-macOS, זה מפעיל את בקשת ההרשאה למיקרופון של המערכת עבור הטרמינל אם היא מעולם לא ניתנה.

/voice
Voice mode enabled (hold). Hold space to record. Dictation language: en (/config to change).

/voice מקבל ארגומנט מצב אופציונלי:

הכתבה קולית נשמרת בין סשנים. הגדירו אותה ישירות בקובץ הגדרות המשתמש במקום להריץ /voice:

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

בשלושת הסשנים הראשונים שבהם הכתבה קולית מופעלת, הכותרת התחתונה של הקלט מציגה רמז hold space to speak כשההנחיה ריקה. הרמז משקף את הקישור הנוכחי voice:pushToTalk ומתעדכן אם אתם מקשרים מחדש את מקש ההכתבה. טקסט הרמז זהה בשני המצבים, והוא לא מופיע אם מוגדר אצלכם שורת סטטוס מותאמת.

התמלול מכוון לאוצר מילים של תכנות בשני המצבים. מונחי פיתוח נפוצים כמו regex, OAuth, JSON ו-localhost מזוהים נכון, ושם הפרויקט הנוכחי ושם ענף ה-git מתווספים אוטומטית כרמזי זיהוי.

#החזקה להקלטה

מצב החזקה הוא דיבור בלחיצה: ההקלטה רצה כל עוד אתם מחזיקים את המקש ונעצרת כשאתם משחררים אותו. זה מצב ברירת המחדל.

החזיקו Space כדי להתחיל הקלטה. Claude Code מזהה מקש מוחזק על ידי מעקב אחר אירועי חזרה מהירה של מקשים מהטרמינל, ולכן יש חימום קצר לפני שההקלטה מתחילה. הכותרת התחתונה מציגה keep holding… במהלך החימום, ואז listening… כשההקלטה פעילה. בזמן ההקלטה, סמן ההנחיה הופך לפס שעולה ויורד לפי עוצמת המיקרופון, אלא אם prefersReducedMotion מופעל.

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

החזקה או הקשה על Space מתחילה הכתבה רק במקום שבו לחיצת המקש הייתה מקלידה אחרת לתוך ההנחיה. במציג התמליל, Space מדפדף בשיחה, ובמצב vim מחוץ ל-INSERT זה פקודה. שילוב עם מקש צירוף שמקושר מחדש כמו meta+k אף פעם לא מקליד טקסט, ולכן הוא מתחיל הכתבה גם מהמקומות האלה.

טיפ: כדי לדלג על החימום, עברו למצב הקשה עם /voice tap, או קשרו מחדש לשילוב עם מקש צירוף כמו meta+k. שילובים עם מקש צירוף מתחילים הקלטה בלחיצה הראשונה.

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

> refactor the auth middleware to ▮
  # hold space, speak "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

כברירת מחדל, כשאתם משחררים את המקש, Claude Code מכניס את התמליל ומחכה שתלחצו Enter. הגדירו "autoSubmit": true באובייקט ההגדרות voice כדי לשלוח את ההנחיה אוטומטית כשאתם משחררים את המקש, כל עוד התמליל באורך של לפחות שלוש מילים.

#הקשה להקלטה ולשליחה

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

הפעילו מצב הקשה עם /voice tap. כשקלט ההנחיה ריק, הקישו Space כדי להתחיל הקלטה. הכותרת התחתונה מציגה ● REC · tap to send בזמן ההקלטה. הקישו Space שוב כדי לעצור.

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

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

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

#ביטול הקלטה

לחצו Esc או Ctrl+C כדי לבטל הכתבה במקום לסיים אותה. Claude Code עוצר את המיקרופון, משליך את התמליל, ומשחזר את ההנחיה למה שהיא החזיקה לפני שההקלטה התחילה.

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

אף אחד מהמקשים לא עושה דבר נוסף בלחיצה שמבטלת: Esc לא קוטע את התשובה של Claude, ו-Ctrl+C לא מנקה את ההנחיה ולא נספר כלחיצה הראשונה מבין שתי הלחיצות שיוצאות מ-Claude Code.

#שינוי שפת ההכתבה

הכתבה קולית משתמשת באותה הגדרת language ששולטת בשפת התשובה של Claude. אם ההגדרה הזו ריקה, ההכתבה ברירת המחדל שלה היא אנגלית. בתוסף VS Code, אם language ריק, ההכתבה משתמשת בהגדרה accessibility.voice.speechLanguage של VS Code לפני שהיא עוברת לאנגלית כברירת מחדל.

#שפות הכתבה נתמכות

הגדירו את השפה ב-/config או ישירות בהגדרות. אפשר להשתמש בקוד שפה BCP 47 או בשם השפה:

{
  "language": "japanese"
}

אם הגדרת language שלכם לא ברשימה הנתמכת, /voice מזהיר אתכם בהפעלה ועובר לאנגלית עבור ההכתבה. תשובות הטקסט של Claude לא מושפעות מהמעבר הזה.

#קישור מחדש של מקש ההכתבה

מקש ההכתבה קשור ל-voice:pushToTalk בהקשר Chat וברירת המחדל שלו היא Space. אותו קישור שולט גם במצב החזקה וגם במצב הקשה. קשרו אותו מחדש ב-~/.claude/keybindings.json:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+k": "voice:pushToTalk",
        "space": null
      }
    }
  ]
}

הפעולה voice:pushToTalk משתמשת במקש אחד בכל פעם. כשאתם קושרים מקש מותאם, הוא מחליף את קישור ברירת המחדל Space ולא מוסיף מפעיל שני, כך ששורת "space": null בדוגמה הזו היא לבהירות ואפשר להשמיט אותה בלי לשנות את ההתנהגות.

במצב החזקה, הימנעו מקישור מקש אות חשוף כמו v כי זיהוי ההחזקה נשען על חזרת מקשים והאות מוקלדת לתוך ההנחיה במהלך החימום. השתמשו ב-Space, או השתמשו בשילוב עם מקש צירוף כמו meta+k כדי להתחיל הקלטה בלחיצה הראשונה בלי חימום. למצב הקשה אין חימום, ולכן רוב המקשים עובדים.

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

#פתרון בעיות

בעיות נפוצות כשההכתבה הקולית לא מופעלת או לא מקליטה:

• Unknown command: /voice: /voice זמין רק כאשר חשבון claude.ai הוא ההתחברות הפעילה שלך. אם אינך מחובר עם חשבון כזה, הרץ /login. אם ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, הגדרת apiKeyHelper, או ספק צד שלישי בשימוש, זה מקבל עדיפות על פני התחברות claude.ai, ולכן הסר את זה והפעל מחדש את Claude Code.
• Voice mode requires a Claude.ai account: Claude Code לא מצא התחברות claude.ai שמישה כשהרצת /voice או התחלת הקלטה. הרץ /login כדי להתחבר שוב.
• Voice mode is disabled by your organization's policy: מדיניות מנהל של הארגון שלך מכבה את ההכתבה הקולית. פנה למנהל הארגון כדי לוודא אם ההכתבה הקולית זמינה לארגון שלך.
• Microphone access is denied: הענק הרשאת מיקרופון לטרמינל בהגדרות המערכת. ב-macOS, עבור אל System Settings → Privacy & Security → Microphone והפעל את אפליקציית הטרמינל, ואז הרץ /voice שוב. ב-Windows, עבור אל Settings → Privacy & security → Microphone והפעל גישת מיקרופון לאפליקציות שולחן עבודה, ואז הרץ /voice שוב. אם הטרמינל שלך לא מופיע בהגדרות macOS, ראה הטרמינל לא מופיע בהגדרות המיקרופון של macOS.
• Voice mode requires SoX for audio recording ב-Linux: מודול השמע המקורי לא נטען ואין חלופה מותקנת. התקן את SoX עם הפקודה שמוצגת בהודעת השגיאה, לדוגמה sudo apt-get install sox.
• Voice mode requires a microphone, but SoX could not open an audio capture device: SoX מותקן, אבל למארח אין התקן לכידת שמע, לדוגמה שרת ללא ממשק או קונטיינר. הרץ את Claude Code במכונה עם מיקרופון. החל מ-v2.1.195, Claude Code ב-Linux מדווח הודעה זו במצב הזה. גרסאות קודמות ביקשו להתקין את SoX גם כשהוא כבר היה מותקן.
• Voice mode could not find a working audio recorder in WSL: WSLg מנתב שמע דרך PulseAudio ולא דרך התקן ALSA, ולכן SoX צריך שרכיב ה-backend של PulseAudio שלו יותקן במפורש. הרץ sudo apt install sox libsox-fmt-pulse. התקנה של sox לבד מושכת את רכיב ה-backend של ALSA, שאינו יכול להקליט ב-WSL כי אין התקן /dev/snd.
• Voice input is failing repeatedly and has been paused: ההכתבה הקולית נתקלה בשלושה כשלים בתוך 10 שניות. Claude Code משהה את ההכתבה עד שיעברו 10 שניות מאז הראשון מבין הכשלים האלה. בדרך כלל זה אומר שהמיקרופון או מחסנית השמע במארח הזה לא יכולים ללכוד שמע, לדוגמה שרת ללא ממשק, מעטפת מרוחקת בלי העברת שמע, או הרשאת מיקרופון שנדחתה. ודא התקן קלט שעובד, תקן את הסיבה לפי הרשומות למעלה, ואז הפעל שוב את הקול. לפני v2.1.202, רק כשלי הפעלה נספרו להשהיה.
• כלום לא קורה כשמחזיקים את Space במצב החזקה: עקוב אחרי קלט ההנחיה בזמן שאתה מחזיק. אם רווחים ממשיכים להצטבר, ההכתבה הקולית כנראה כבויה. הרץ /voice hold כדי להפעיל אותה. אם מופיעים רק רווח אחד או שניים ואז כלום, ההכתבה הקולית דלוקה אבל זיהוי ההחזקה לא מופעל. זיהוי החזקה דורש שהטרמינל ישלח אירועי חזרה על מקש, ולכן הוא לא יכול לזהות מקש מוחזק אם חזרת המקשים כבויה ברמת מערכת ההפעלה. עבור למצב הקשה עם /voice tap כדי להימנע מדרישת חזרת המקשים.
• הקשה על Space מקלידה רווח במקום הקלטה במצב הקשה: ההקשה הראשונה מתחילה הקלטה רק כאשר קלט ההנחיה ריק. נקה תחילה את הקלט, או בדוק שאתה במצב הקשה על ידי הרצת /voice tap.
• No audio detected from microphone: ההקלטה התחילה אבל לכדה שקט. ודא שהתקן הקלט הנכון מוגדר כברירת המחדל של המערכת ושעוצמת הקלט שלו לא מושתקת ולא קרובה לאפס. ב-Windows, פתח Settings → System → Sound → Input ובחר את המיקרופון. ב-macOS, פתח System Settings → Sound → Input.
• Voice connection failed: ההקלטה שלך לא הגיעה לשירות התמלול כי החיבור נכשל. בדוק את הרשת ונסה שוב. הקלטה שלא לוכדת שמע מדווחת No audio detected from microphone במקום הודעה זו. לפני v2.1.200, מיקרופון שקט יכול היה לדווח על כשל חיבור, מה שרמז לבעיית רשת כשהבעיה בפועל הייתה התקן הקלט.
• Dictation error: WebSocket error: ואחריה שגיאת אישור כגון unable to get local issuer certificate: ראה ההכתבה או לשונית Web נכשלת מאחורי פרוקסי שבודק TLS בדף VS Code.
• Voice stream error: WebSocket upgrade rejected with HTTP <status>: שרת סירב לחיבור שלך עם סטטוס ה-HTTP המוצג, ולכן זו אינה תקלת רשת. סטטוס בטווח 400 בדרך כלל אומר התחברות לא מעודכנת, או שפרוקסי או שירות להגנה מפני בוטים עונה במקום שירות התמלול. הרץ /login כדי לרענן את ההתחברות, ובדוק אם יש VPN או פרוקסי בנתיב הרשת אם הסטטוס נמשך. אם אתה עדיין מקליט כשהדחייה מגיעה, Claude Code מנסה שוב פעם אחת סטטוס שמחוץ לטווח 400 לפני הצגת הודעה זו. הוא לא מנסה שוב סטטוס בטווח 400. ב-v2.1.229 עד v2.1.231, בניות native לא הציגו את ההודעה הזו: Claude Code המשיך להקליט, הכותרת התחתונה של מצב החזקה עדיין הראתה listening…, והוא דיווח Voice connection failed אחרי שהפסקת את ההקלטה.
• No speech detected: השמע הגיע לשירות התמלול אבל לא זוהו מילים. דבר קרוב יותר למיקרופון, הפחת רעשי רקע, וודא ששפת ההכתבה תואמת לשפה שבה אתה מדבר.
• Dictation stopped: no speech recognized for 15 seconds או Dictation stopped at its 2-minute limit: בתוסף VS Code, הקלטה מסתיימת אחרי 15 שניות בלי מילים שזוהו, או שתי דקות אחרי שהיא מתחילה. אם דיברת במהלך 15 השניות האלה, נסה את התיקונים עבור No speech detected. מילים שכבר זוהו נשארות בתיבת ההנחיה ולא נשלחות. כדי להוסיף עוד, לחץ שוב על כפתור המיקרופון.
• התמלול משובש או בשפה שגויה: ברירת המחדל של ההכתבה היא אנגלית. אם אתה מכתיב בשפה אחרת, הגדר אותה קודם ב-/config. ראה שינוי שפת ההכתבה.

#הטרמינל לא מופיע בהגדרות המיקרופון של macOS

אם אפליקציית הטרמינל שלך לא מופיעה תחת System Settings → Privacy & Security → Microphone, אין מתג שאפשר להפעיל. אפס את מצב ההרשאה של הטרמינל כדי שההרצה הבאה של /voice תפעיל בקשת הרשאה חדשה של macOS.

1. איפוס הרשאת המיקרופון לטרמינל שלך

הרץ tccutil reset Microphone <bundle-id>, והחלף את <bundle-id> במזהה של הטרמינל: com.apple.Terminal עבור Terminal המובנה, או com.googlecode.iterm2 עבור iTerm2. לטרמינלים אחרים, אתר את המזהה עם osascript -e 'id of app "AppName"'.

[!WARNING]

אפשר להריץ tccutil reset Microphone בלי מזהה bundle, אבל זה מבטל את גישת המיקרופון מכל אפליקציה ב-Mac, כולל אפליקציות כמו Zoom או Slack. כל אפליקציה תצטרך לבקש גישה מחדש בשימוש הבא, ולכן אל תריץ את זה במהלך שיחה פעילה.

2. יציאה והפעלה מחדש של הטרמינל

macOS לא יציג בקשה מחדש לתהליך שכבר רץ. צא מאפליקציית הטרמינל עם Cmd+Q, ולא רק סגור את החלונות שלה, ואז פתח אותה שוב.

3. הפעלת בקשה חדשה

הפעל את Claude Code והרץ /voice. macOS מבקש גישה למיקרופון. אשר אותה.

#ראה גם

• התאמה אישית של קיצורי מקלדת: שינוי השיוך של voice:pushToTalk ופעולות מקלדת אחרות ב-CLI
• כל ההגדרות: מפתחות ההגדרות voice, language ואחרים
• מצב אינטראקטיבי: קיצורי מקלדת, מצבי קלט ובקרות סשן
• פקודות: חומר עזר ל-/voice, ל-/config ולכל שאר הפקודות