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

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