📘 תיעוד 115

הכתבה קולית

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

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

הכתבה פועלת גם ב-agent view. החזק או הקש על מקש ה-push-to-talk שלך כאשר שדה ה-dispatch או תשובה בחלון ההצצה (peek-panel) נמצאים בפוקוס, כדי להכתיב להפעלה שרצה ברקע.

#דרישות

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

• חשבון Claude.ai: שירות הדיבור לטקסט זמין רק כאשר אתה מתחבר עם חשבון כזה, ואינו זמין כאשר Claude Code מוגדר להשתמש ישירות במפתח API של Anthropic, ב-Amazon Bedrock, ב-Google Cloud's Agent Platform או ב-Microsoft Foundry.
• מיקרופון מקומי: הכתבה קולית אינה פועלת בסביבות מרוחקות, כגון Claude Code באינטרנט או בהפעלות 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 מתווספים אוטומטית כרמזי זיהוי.

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

מצב החזקה פועל בתצורת push-to-talk: ההקלטה פועלת בזמן שאתה מחזיק את המקש לחוץ, ומפסיקה ברגע שאתה משחרר אותו. זהו מצב ברירת המחדל.

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

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

טיפ: כדי לדלג על החימום, עבור אל מצב הקשה באמצעות /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 שניות של שקט או לאחר שתי דקות בסך הכל.

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

הכתבה קולית משתמשת באותה הגדרת 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 מציג שגיאה אם מנסים למפות אותו. ראה התאמה אישית של קיצורי מקשים לתחביר המיפוי המלא ולרשימת קיצורי הדרך השמורים.

#פתרון בעיות

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

• Voice mode requires a Claude.ai account: אתה מחובר באמצעות מפתח API או ספק צד שלישי. הרץ /login כדי להתחבר עם חשבון Claude.ai.
• 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 זקוק להתקנה מפורשת של רכיב ה-PulseAudio שלו. הרץ sudo apt install sox libsox-fmt-pulse. התקנת sox לבדו מתקינה את רכיב ה-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, מיקרופון שקט עלול היה לדווח על כשל בחיבור, מה שיצר רושם של תקלת רשת אף שהבעיה האמיתית הייתה בהתקן הקלט.
• Voice stream error: WebSocket upgrade rejected with HTTP <status>: שרת דחה את החיבור שלך עם סטטוס ה-HTTP המוצג, לכן אין מדובר בהשבתת רשת. סטטוס בטווח 400 מעיד לרוב על חיבור שפג תוקפו, או על שרת פרוקסי או שירות הגנה מבוטים שעונה במקום שירות התמלול. הרץ /login כדי לרענן את ההתחברות שלך, ובדוק אם יש VPN או פרוקסי ברשת אם הסטטוס נמשך. אם אתה עדיין מקליט בעת קבלת הדחייה, Claude Code מנסה שוב פעם אחת עבור סטטוס מחוץ לטווח 400 לפני הצגת הודעה זו; הוא אינו מנסה שוב עבור סטטוס בטווח 400. בגרסאות v2.1.229 עד v2.1.231, גרסאות מקוריות לא הציגו הודעה זו: Claude Code המשיך להקליט, החלק התחתון במצב החזקה המשיך להציג listening…, והודעת Voice connection failed הופיעה רק לאחר שעצרת את ההקלטה.
• No speech detected: השמע הגיע לשירות התמלול אך לא זוהו מילים. דבר קרוב יותר למיקרופון, הפחת רעשי רקע, וודא ש-שפת ההכתבה שלך תואמת לשפה שבה אתה מדבר.
• התמלול משובש או בשפה הלא נכונה: ברירת המחדל של ההכתבה היא אנגלית. אם אתה מכתיב בשפה אחרת, הגדר אותה תחילה ב-/config. ראה שינוי שפת ההכתבה.

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

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

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

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

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

3. הפעלת בקשת הרשאה חדשה: הפעל את Claude Code והרץ /voice. מערכת macOS תבקש גישה למיקרופון; אשר אותה.

#ראה גם

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