📘 תיעוד 51

הפעלת סשנים מקישורים

פתחו סשן מסוף של Claude Code מתוך כתובת URL. הטמיעו קישורי claude-cli:// בחוברות הפעלה (runbooks), בהתראות ובלוחות בקרה, כך שלחיצה תפתח את Claude Code במאגר הנכון עם הפרומפט הנכון.

קישור עמוק (deep link) הוא כתובת URL עם claude-cli:// שפותחת את Claude Code בחלון מסוף חדש. כתובת ה-URL יכולה להכיל ספריית עבודה ופרומפט למילוי מראש.

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

מכיוון שקישור עמוק הוא כתובת URL, אתם יכולים למקם אותו בכל מקום שבו קישור יכול להופיע:

• שלב בחוברת הפעלה (runbook) של תקרית שפותח את מאגר הקוד של השירות המושפע עם פרומפט אבחון
• התראת ניטור או לוח בקרה שמקשרים לפרומפט חקירה עבור מדד מסוים
• דף README או דף ויקי שפותח את הפרויקט עם פרומפט קליטה (onboarding)
• הודעת כשל ב-CI שממלאת מראש את שם המשימה שנכשלה

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

#כיצד פועלים קישורים עמוקים

הקידומת claude-cli:// היא סכמת URL מותאמת אישית ש-Claude Code רושם במערכת ההפעלה שלכם, בדומה לאופן שבו קישורי mailto: פותחים את תוכנת הדוא״ל שלכם. כאשר אתם לוחצים על קישור עמוק:

1. הדפדפן או האפליקציה מעבירים את כתובת ה-URL למערכת ההפעלה שלכם.
2. מערכת ההפעלה מזהה את הקידומת claude-cli:// ומפעילה את Claude Code במחשב שלכם.
3. חלון מסוף חדש נפתח עם Claude Code שרץ בספרייה שצוינה בקישור, וטקסט הפרומפט מהקישור כבר מופיע בתיבת הקלט.
4. אתם קוראים את הפרומפט, עורכים אותו אם תרצו, ולוחצים על Enter כדי לשלוח אותו.

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

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

#מה מוצג בסשן שהופעל

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

כאשר הסשן נפתח, שורת אזהרה מתחת לתיבת הקלט מציגה Prompt from an external link ונשארת גלויה עד שתשלחו או תנקו את הפרומפט. עבור פרומפטים באורך של מעל 1,000 תווים, האזהרה כוללת את מספר התווים ומורה לכם לגלול ולבדוק את הטקסט המלא לפני הלחיצה על Enter, מכיוון שפרומפטים ארוכים עלולים לדחוק הנחיות אל מחוץ למסך. כללי הרשאות, CLAUDE.md, ובקשות אישור אמון (trust prompts) עבור הספרייה שנבחרה חלים באותו אופן כמו בכל סשן אחר.

#בניית קישור

כל קישור עמוק מתחיל ב-claude-cli://open, שהוא הנתיב היחיד שהמטפל מקבל, ולאחריו פרמטרי שאילתה אופציונליים. הצורה המינימלית פותחת את Claude Code בספריית הבית שלכם עם פרומפט ריק:

claude-cli://open

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

הוסיפו פרמטרים כדי לשלוט במקום שבו הסשן מתחיל ובמה שתיבת הפרומפט מכילה:

cwd ו-repo הן שתי דרכים להגדיר את ספריית העבודה. אם תעבירו את שתיהן, cwd מקבל עדיפות ומתעלמים מ-repo, גם אם הנתיב של cwd אינו קיים.

הקישור הבא מצביע על מאגר בשם acme/payments עם פרומפט אבחון בן שתי שורות. החליפו את acme/payments במזהה ה-owner/name של המאגר שלכם כאשר אתם בונים קישור משלכם:

claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.

לחיצה עליו פותחת חלון מסוף חדש, מפעילה את Claude Code בשיבוט המקומי שלכם של acme/payments, וממלאת את תיבת הפרומפט בטקסט המפוענח:

Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.

אתם יכולים לערוך את הפרומפט לפני הלחיצה על Enter כדי לשלוח אותו. ראו בחירה בין cwd לבין repo לפרטים על האופן שבו הנתיב המקומי נבחר כאשר יש לכם מספר שיבוטים (clones) או עצי עבודה (worktrees).

#בחירה בין cwd לבין repo

השתמשו ב-cwd כאשר לכל מי שלוחץ על הקישור יש את הפרויקט באותו נתיב מוחלט, כגון devcontainer או קובץ תמונה של מכונה וירטואלית (VM image) סטנדרטיים.

השתמשו ב-repo כאשר הקישור משותף וכל אדם משבט למיקום שונה. ‏Claude Code מפענח את המזהה לנתיב מקומי באופן הבא:

• repo פותח את השיבוט או את עץ העבודה (worktree) של המאגר המקושר שבו הרצתם את claude לאחרונה. בכל פעם שאתם מריצים את claude במאגר Git, ‏Claude Code רושם את נתיב הספרייה הזו כנגד מזהה ה-owner/name ב-GitHub של המאגר. ‏Claude Code עוקב בנפרד אחר שיבוטים ועצי עבודה.
• הקישור אינו משנה איזה ענף (branch) נמצא במצב checked out. הסשן נפתח בכל מצב שבו הספרייה נמצאת כעת.

כותרת הפתיחה מציגה איזה נתיב נבחר כדי שתוכלו לוודא שהשיבוט הנכון נפתח.

#דוגמאות

הסעיפים להלן מציגים שתי דרכים נפוצות להשתמש בקישור עמוק: כקישור Markdown במסמך וכפקודה בסקריפט או בכינוי מעטפת (shell alias).

#הטמעת קישור בחוברת הפעלה (runbook)

קישור עמוק בחוברת הפעלה (runbook) מעניק למי שמבצע מיון וטיפול ראשוני (triage) דרך בלחיצה אחת להתחיל לחקור במאגר הנכון עם פרומפט מוכן מראש. הפלטפורמה שמציגה את חוברת ההפעלה חייבת לאפשר סכמות URL מותאמות אישית. ‏Markdown שמוצג ב-GitHub אינו מאפשר claude-cli://, ולכן קישור עמוק ב-README, ב-issue או בוויקי של GitHub מציג רק את התווית שלו ללא קישור לחיץ. ראו את הערת פתרון הבעיות עבור פתרון עוקף.

הפרומפט הוא חלק מכתובת ה-URL וחובה לקודד אותו בקידוד URL. כדי להפיק את הערך המקודד, העבירו את טקסט הפרומפט שלכם דרך encodeURIComponent במסוף הדפדפן או בכל כלי לקידוד URL.

הדוגמה להלן מוסיפה נקודת כניסה לחקירה לחוברת הפעלה של תקרית עבור שירות בשם web-gateway:

## High 5xx rate on web-gateway

1. Acknowledge the page in PagerDuty.
2. [Open Claude Code in the gateway repo](claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated%20on%20web-gateway.%20Check%20recent%20deploys%2C%20error%20logs%20from%20the%20last%2030%20minutes%2C%20and%20open%20incidents%20in%20Linear.)
3. Post initial findings in #incident.

כדי להשתמש בזה בחוברת הפעלה משלכם, החליפו את acme/web-gateway במזהה המאגר של השירות שלכם. הדבר מאפשר למהנדסים ש-Claude Code מותקן אצלם ויש להם שיבוט מקומי של אותו מאגר ללחוץ על שלב 2 ולהתחיל לחקור כשהפרומפט מוכן לשליחה.

#פתיחת קישור מהמעטפת (shell)

באפשרותכם גם לפתוח קישור עמוק מתוך סקריפט מעטפת, כינוי (alias) או אוטומציה במקום ללחוץ עליו. קראו לפקודת פתיחת כתובות ה-URL של מערכת ההפעלה שלכם עם הקישור כארגומנט. פקודות אלו מסתמכות על המטפל ש-Claude Code רושם כאשר אתם שולחים את הפרומפט הראשון שלכם בסשן אינטראקטיבי במחשב.

#macOS

הפקודה המובנית open מעבירה את כתובת ה-URL למטפל ה-claude-cli:// הרשום:

open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

בהצלחה, חלון מסוף חדש נפתח עם Claude Code שרץ והפרומפט ממולא מראש.

#Linux

רוב סביבות שולחן העבודה מספקות את xdg-open, שמעבירה את כתובת ה-URL למטפל הרשום:

xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

בהצלחה, חלון מסוף חדש נפתח עם Claude Code שרץ והפרומפט ממולא מראש. אם המעטפת מדווחת ש-xdg-open לא נמצאה, ראו פתרון בעיות.

#Windows

ב-PowerShell, הפקודה Start-Process מעבירה את כתובת ה-URL למטפל הרשום:

Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

ב-cmd.exe, הפקודה start מתייחסת לארגומנט המצוטט הראשון ככותרת חלון, לכן העבירו כותרת ריקה לפני כתובת ה-URL:

start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

בהצלחה, חלון מסוף חדש נפתח עם Claude Code שרץ והפרומפט ממולא מראש.

#רישום ופלטפורמות נתמכות

Claude Code רושם את מטפל ה-claude-cli:// במערכת ההפעלה שלכם ב-macOS, ב-Linux וב-Windows כאשר אתם שולחים את הפרומפט הראשון שלכם בסשן אינטראקטיבי. הפעלת claude ויציאה מבלי לשלוח פרומפט אינן רושמות את המטפל. אין צורך להריץ פקודת התקנה נפרדת. הרישום כותב למיקומים ברמת המשתמש בלבד:

המטפל מפעיל את Claude Code באמולטור מסוף שזוהה. ב-macOS, ‏Claude Code זוכר את המסוף מהסשן האינטראקטיבי האחרון שלכם ומשתמש בו שוב, עם תמיכה ב-iTerm2, ב-Ghostty, ב-kitty, ב-Alacritty, ב-WezTerm וב-Terminal.app. ב-Linux הוא מתחשב במשתנה הסביבה $TERMINAL, לאחר מכן ב-x-terminal-emulator, ולאחר מכן ברשימה של אמולטורים נפוצים. ב-Windows הוא מעדיף את Windows Terminal, לאחר מכן את PowerShell, ולאחר מכן את cmd.exe.

כדי למנוע רישום לחלוטין, הגדירו את disableDeepLinkRegistration לערך "disable" בתוך settings.json. כדי לאכוף זאת ברחבי ארגון כך שמשתמשים לא יוכלו להפעיל זאת מחדש, הגדירו זאת ב-הגדרות מנוהלות (managed settings) במקום זאת.

#פתיחת לשונית VS Code במקום מסוף

תוסף VS Code רושם מטפל משלו בכתובת vscode://anthropic.claude-code/open, אשר פותח לשונית עורך של Claude Code במקום חלון מסוף. ראו הפעלת לשונית VS Code מכלים אחרים עבור הפרמטרים של כתובת URL זו.

#פתרון בעיות

#לחיצה על הקישור אינה עושה דבר

סביר להניח שהמטפל עדיין אינו רשום. הרישום מתבצע כאשר אתם שולחים את הפרומפט הראשון שלכם בסשן אינטראקטיבי, ולא כאשר הסשן מתחיל. התחילו סשן claude אינטראקטיבי באותו מחשב, שלחו פרומפט כלשהו, צאו, ונסו את הקישור שוב. אם אתם ב-Linux ללא סביבת שולחן עבודה, ייתכן של-xdg-open אין יעד לשגר אליו.

#xdg-open אינה נמצאת ב-Linux

הפקודה xdg-open היא חלק מחבילת xdg-utils, שתמונות שרת מינימליות, קונטיינרים והפצות WSL לעיתים קרובות משמיטים. התקינו את xdg-utils באמצעות מנהל החבילות של ההפצה שלכם, לדוגמה sudo apt install xdg-utils, ולאחר מכן הריצו את הפקודה שוב. אם הפקודה רצה אך שום דבר אינו נפתח, ייתכן של-xdg-open אין סביבת שולחן עבודה לשגר אליה; ראו לחיצה על הקישור אינה עושה דבר.

#הקישור מוצג כטקסט רגיל במקום להיות לחיץ

מנועי עיבוד Markdown מסוימים מאפשרים רק קישורי http ו-https ומסירים סכמות URL אחרות. ‏GitHub עושה זאת בקובצי README, ב-issues, ב-pull requests ובוויקי: [label](claude-cli://...) מוצג רק כ-label, ללא קישור וכאשר כתובת ה-URL הוסרה. בפלטפורמות אלו, הציבו את הקישור העמוק בתוך בלוק קוד כדי שהקוראים יוכלו לראות את כתובת ה-URL ולהדביק אותה בשורת הכתובות של הדפדפן שלהם.

#הסשן נפתח בספריית הבית שלי במקום במאגר

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

#הקישור פותח את המסוף הלא נכון

ב-macOS, הפעילו את claude במסוף המועדף עליכם פעם אחת והקישור העמוק הבא ישתמש בו. ב-Linux, הגדירו את משתנה הסביבה $TERMINAL לשם הפקודה של האמולטור המועדף עליכם. ב-Windows, הסדר קבוע: התקינו את Windows Terminal אם ברצונכם שקישורים ייפתחו שם במקום בחלון של PowerShell או של cmd.exe.

#מידע נוסף

דפים אלה מכסים דרכים קשורות להפעלה או להרחבה של סשנים של Claude Code:

• Skills: אחסנו פרומפט ארוך של חוברת הפעלה בתור /skill במאגר, כך שפרמטר ה-q של הקישור העמוק יצטרך רק לציין את שמו.
• מצב לא אינטראקטיבי (Non-interactive mode): הריצו את Claude מתוך סקריפט ולכדו את הפלט מבלי לפתוח מסוף.