איך יוצרים תת-סוכן ייעודי בקלוד קוד (Claude Code) עם טלגרם — מדריך מלא

כדי להפוך את קלוד קוד (Claude Code) לתת-סוכן ייעודי בטלגרם, מקימים דמון קטן שרץ ברקע ב-long-polling: הוא מאזין להודעות בבוט טלגרם, ולכל הודעה מריץ claude -p במצב headless עם --append-system-prompt שנועל את הסוכן למטרה אחת קבועה, מגביל את הכלים עם --allowedTools, ומחזיר את התשובה לצ'אט. הבוט נעול ל-chat id שלכם בלבד, והדמון רץ תמיד עם launchd (ב-macOS) או systemd (ב-Linux). התוצאה: בוט אחד שעושה עבודה אחת — מצוין.

גילוי נאות: זה המשך ישיר של לחבר את Claude Code לטלגרם. שם בנינו צ'אט כללי; כאן נועלים אותו לתפקיד אחד.

מה זה "תת-סוכן ייעודי" ולמה זה חזק

חיבור רגיל של קלוד קוד (Claude Code) לטלגרם נותן לכם צ'אט־כל־יכול: אתם שולחים "תפרסם את המאמר", "תבדוק סטטוס", "תריץ בדיקות" — כל משימה שעולה לכם. זה נהדר, אבל זה גם דורש מכם לחשוב ולנסח בכל פעם מחדש.

תת-סוכן ייעודי הפוך: בוט אחד = מטרה אחת. במקום צ'אט פתוח, יש לכם עובד ממוקד: "סוכן סינון לידים", "סוכן דוח יומי", "סוכן רעיונות תוכן". אתם זורקים לתוכו קלט גולמי — הוא כבר יודע מה לעשות איתו, כי התפקיד שלו נעול. היתרונות:

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

הארכיטקטורה בקצרה

הזרימה פשוטה וקווית:

טלגרם  →  דמון (long-polling)  →  claude -p  →  תשובה  →  טלגרם

1. טלגרם מחזיק את ההודעות שלכם בבוט.
2. הדמון (סקריפט bash קטן שרץ ברקע) שואל את טלגרם "יש הודעה חדשה?" ומקבל את הטקסט.
3. claude -p מריץ את קלוד קוד (Claude Code) במצב headless — הוראה אחת, בלי חלון אינטראקטיבי — עם ה-system-prompt הייעודי.
4. הפלט חוזר לצ'אט. הדמון חוזר להאזין. זהו — לולאה אינסופית.

בניגוד לחיבור הרגיל שבו אתם מנהלים את הלולאה בעצמכם, כאן הדמון הוא רכיב עצמאי שרץ תמיד ברקע. זה בדיוק העיקרון של אוטומציה מתוזמנת ל-Claude Code — headless + מתזמן — רק שכאן הטריגר הוא הודעת טלגרם ולא שעון.

איך פותחים בוט בטלגרם צעד-אחר-צעד

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

1. פותחים את BotFather. בטלגרם, חפשו @BotFather (הבוט הרשמי של טלגרם ליצירת בוטים, עם וי כחול). לחצו Start.
2. יוצרים בוט חדש. שלחו /newbot.
3. בוחרים שם תצוגה. למשל Leads Filter. זה השם שיופיע בצ'אט.
4. בוחרים שם משתמש. חייב להיות ייחודי ולהסתיים ב-bot, למשל my_leads_filter_bot.
5. מקבלים טוקן. BotFather יחזיר טוקן שנראה כך: 8927:AAH.... זה המפתח לכל ה-API — כמו סיסמה. שמרו אותו, ואל תשתפו.
6. מוצאים את ה-chat id שלכם. שלחו הודעה כלשהי לבוט החדש (למשל "היי"), ואז פתחו בדפדפן: https://api.telegram.org/bot<הטוקן>/getUpdates בתשובת ה-JSON תראו "chat":{"id":123456789,...}. המספר הזה הוא ה-chat id שלכם.
7. נועלים את הבוט לעצמכם. את ה-chat id הזה נשמור, ומאותו רגע הדמון יתעלם מכל הודעה שלא הגיעה ממנו. כך אף אחד אחר לא יכול להפעיל את הסוכן שלכם.

שומרים את שני הפרטים בקובץ מקומי — לא בקוד ולא ב-git:

# ~/.telegram-agent-creds
TG_TOKEN=הטוקן-שקיבלתם-מ-BotFather
TG_CHAT=123456789          # ה-chat id שלכם מ-getUpdates

chmod 600 ~/.telegram-agent-creds   # רק אתם יכולים לקרוא

אם הטוקן דלף אי פעם — /revoke ב-BotFather מייצר טוקן חדש ומבטל את הישן.

מוח הסוכן: --append-system-prompt

זה הלב של תת-הסוכן הייעודי. במקום להסביר לקלוד מה לעשות בכל הודעה, מדביקים לו תפקיד קבוע עם --append-system-prompt. הנה שורת הרנר שהדמון מריץ לכל הודעה:

REPLY="$(claude -p "$MSG" \
  --append-system-prompt "אתה סוכן סינון לידים. קרא את ההודעה, סווג את הליד ל'חם', 'פושר' או 'קר' לפי כוונת קנייה, והחזר שורה אחת בלבד: הסיווג + נימוק קצר. אל תסביר את התהליך." \
  --allowedTools "Read" \
  --max-turns 4)"

מה קורה כאן:

• "$MSG" — הטקסט שהמשתמש שלח בטלגרם, נכנס כפרומפט.
• --append-system-prompt — הוראת התפקיד הקבועה. היא נדבקת לכל ריצה, כך שהסוכן תמיד מסנן לידים, בלי קשר לניסוח ההודעה.
• הפלט ($REPLY) נשלח בחזרה לטלגרם עם sendMessage.

רוצים סוכן אחר? משנים רק את מחרוזת ה-system-prompt. אותה תשתית בדיוק, תפקיד אחר.

read-only מול full access: --allowedTools

כאן קובעים כמה כוח יש לסוכן — וזו החלטת אבטחה, לא נוחות. --allowedTools מגביל בדיוק אילו כלים קלוד קוד (Claude Code) רשאי להפעיל:

• סוכן read-only (מסכם, מסנן, מסווג): --allowedTools "Read" או --allowedTools "Read" "Bash(git log:*)". הוא יכול לקרוא ולדווח — אבל לא לכתוב, לערוך או למחוק. זו ברירת המחדל הבטוחה לרוב הסוכנים.
• סוכן full access (מפרסם, מעדכן קבצים, מריץ פריסה): --allowedTools "Read" "Edit" "Write" "Bash". נותנים לו רק את מה שהוא באמת צריך למשימה — לא הכל "ליתר ביטחון".

שני כללי זהב:

1. התחילו נעול, פתחו רק כשצריך. אם הסוכן רק מדווח, אל תיתנו לו כלי כתיבה בכלל.
2. הבוט נעול ל-chat id אחד. גם אם הסוכן חזק, רק אתם מפעילים אותו. שילוב של --allowedTools מצומצם + נעילת chat id הוא ההגנה הכפולה.

זיכרון מצטבר: ledger

סוכן שרץ שוב ושוב מרוויח הרבה מזיכרון. במקום להתחיל מאפס בכל הודעה, מחזיקים קובץ יומן פשוט (ledger) שהסוכן קורא ומעדכן:

LEDGER="${HOME}/.leads-agent-ledger.md"
REPLY="$(claude -p "ליד חדש: $MSG" \
  --append-system-prompt "אתה סוכן סינון לידים. קרא את היומן ב-$LEDGER לפני שאתה מסווג, וכתוב לתוכו שורה על הליד החדש (תאריך, סיווג, נימוק) בסיום." \
  --allowedTools "Read" "Edit($LEDGER)" \
  --max-turns 6)"

עכשיו הסוכן זוכר לידים קודמים, מזהה כפילויות, ולומד לאורך זמן — בלי מסד נתונים, רק קובץ Markdown אחד. שימו לב: פה נתנו הרשאת כתיבה רק לקובץ היומן (Edit($LEDGER)), לא לכל הפרויקט.

להריץ תמיד: launchd / systemd

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

• macOS — launchd. יוצרים קובץ LaunchAgent עם KeepAlive=true, כך שהדמון עולה מחדש אוטומטית אם קרס, וגם אחרי אתחול.
• Linux — systemd. יוצרים unit עם Restart=always. systemctl --user enable ידאג שהוא ירוץ תמיד ברקע.

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

שלוש דוגמאות לסוכנים ייעודיים

אותה תשתית, שלושה תפקידים — כל ההבדל הוא ה-system-prompt וה---allowedTools:

1. סורק תמלולים → רעיונות תוכן. שולחים לו תמליל של פגישה או פרק פודקאסט; ה-system-prompt: "קרא את התמליל, חלץ 5 רעיונות לפוסטים עם כותרת וזווית." read-only. מקבלים רעיונות מוכנים בטלגרם.
2. מסנן לידים. שולחים פרטי פנייה; ה-system-prompt: "סווג ל'חם/פושר/קר' לפי כוונת קנייה, החזר שורה אחת." read-only + ledger לזיהוי כפילויות. חוסך את המיון הידני.
3. דוח יומי. בבוקר שולחים "דוח"; ה-system-prompt: "קרא את הלוגים והמדדים של אתמול והחזר סיכום של 4 שורות." read-only + Bash מוגבל לקריאה. מדד יומי בלי לפתוח דשבורד.

שורה תחתונה

תת-סוכן ייעודי בקלוד קוד (Claude Code) הוא דמון long-polling קטן שמאזין לבוט טלגרם ומריץ claude -p headless עם --append-system-prompt שנועל אותו למטרה אחת, --allowedTools שקובע כמה כוח יש לו, ונעילה ל-chat id שלכם. פותחים את הבוט ב-BotFather, כותבים את הדמון פעם אחת, ומריצים אותו תמיד עם launchd או systemd. בוט אחד = עבודה אחת, מצוין.

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

שאלות נפוצות

מה ההבדל בין חיבור טלגרם רגיל לתת-סוכן ייעודי? חיבור רגיל הוא צ'אט כללי שמבצע כל משימה. תת-סוכן ייעודי הוא בוט אחד עם מטרה אחת נעולה (--append-system-prompt) — עקבי, בטוח ופשוט להפעלה. בוט אחד = עבודה אחת.

איך פותחים בוט ומקבלים chat id? /newbot ל-BotFather → שם + שם משתמש שמסתיים ב-bot → טוקן. אז שולחים הודעה לבוט ופותחים getUpdates — ה-chat id שלכם מופיע ב-JSON. נועלים את הדמון אליו.

read-only או full access? מתחילים read-only (--allowedTools "Read") לכל סוכן שרק קורא ומדווח. נותנים כתיבה או Bash רק כשהמשימה באמת דורשת, ורק על מה שצריך — למשל Edit($LEDGER) בלבד.

איך גורמים לו לרוץ תמיד? launchd עם KeepAlive=true ב-macOS, או systemd unit עם Restart=always ב-Linux. הדמון עולה אחרי אתחול ומתאושש אם קרס.