הגדרה ותצורה

איפה יושבות ההגדרות

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

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

הגדרות בדשבורד

פתחו את הסוכן שלכם בפורטל הקולי ועברו ל-Settings (הגדרות). באזור Configuration (תצורה) נמצאות ההגדרות שרוב הצוותים משנים:

• Greeting (ברכת פתיחה): המשפט הראשון שהמתקשרים שומעים בשיחה נכנסת. הסוכן אומר אותו בדיוק כפי שנכתב, אז כתבו אותו כמו שאתם רוצים שיישמע. כתבו עד 300 תווים: הסוכן אומר רק את 300 התווים הראשונים, ומירכאות כפולות מוסרות.
• Outbound greeting (פתיחה בשיחות יוצאות): משפט הפתיחה כשהסוכן מוציא שיחה. עד 500 תווים. אפשר לשלב בו משתנים כמו {{name}} לשם האדם שאליו מתקשרים ו-{{amount_due}} לכל עובדה שנשלחה עם השיחה. אם למשתנה אין ערך בשיחה מסוימת, הסוכן פותח בפתיחת ברירת המחדל שלו במקום להגיד משפט חסר.
• Voice (קול) ו-Language (שפה): ראו שפות.
• Call mode (מצב שיחה) ו-Your phone number (המספר שלכם): מצב public עונה לכל אחד ומתייחס לכל מתקשר כאל מתקשר מהציבור. מצב Private עונה רק למספר הטלפון שהזנתם, והמתקשר מהמספר הזה מקבל גישה מלאה של בעל העסק. כל מספר אחר נדחה, ואם לא הוגדר מספר, נדחית כל שיחה.
• Call direction (כיוון השיחות): נכנסות ויוצאות (ברירת המחדל), נכנסות בלבד או יוצאות בלבד.
• Model ו-Temperature, תחת Advanced (מתקדם).

באותו דף נמצאים גם המתגים של ההקלטה והתמלול. הם נפרדים: אפשר לשמור תמלולים בלי לשמור שמע.

התקנת רכיב השיחות על שרת משלכם

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

1. מפיקים טוקן התקנה ב-Settings, Installation (התקנה). הטוקן תקף ל-15 דקות.
2. מריצים את פקודת ההתקנה על המכונה שבה הסוכן רץ (Linux על x86_64 או arm64, או macOS):

   curl -sSL https://api.talktomyagent.io/install.sh | bash -s -- --token <YOUR_TOKEN> --accept-license

3. מחכים לסימני ה-✓. תוכנית ההתקנה מורידה את רכיב השיחות, מקימה את המנהרה, כותבת את .env ואת config.json, יוצרת פלייבוק קולי ראשוני אם אין לכם אחד, ומפעילה את השירות.
4. מוציאים שיחת בדיקה למספר של הסוכן.

במכונה עם כמה סוכנים, תוכנית ההתקנה שואלת לאיזה מהם להתחבר. כדי לבחור בלי התפריט, הוסיפו --agent <id>.

מה יש בדיסק אחרי ההתקנה

~/ninja-talk/                  install directory (main agent)
  config.json                  operator settings (this guide)
  CONFIG-REFERENCE.md          field reference written by the installer
  .env                         credentials, written by the installer
  start.sh                     what the service runs
  sync-config.sh               pulls dashboard settings into config.json

~/.openclaw/workspace/         the agent's workspace
  SOUL.md  IDENTITY.md  USER.md  MEMORY.md
  protocols/dojo-voice-agent-playbook.md
  data/voice-context-sources.json
  memory/kb/

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

config.json

התקנה חדשה כותבת קובץ כזה:

{
  "callMode": "public",
  "ownerPhone": null,
  "greetingPrompt": null,
  "voice": "Kore",
  "language": "en-US",
  "recordingEnabled": true,
  "maxCalls": 2,
  "callTimeoutMinutes": 60,
  "idleTimeoutSeconds": 120,
  "schemaVersion": 1,
  "audio":    { ... },
  "context":  { "files": ["SOUL.md", "IDENTITY.md", "USER.md"], "voicePlaybook": null },
  "features": { ... }
}

בקובץ יש שני סוגים של שדות, וכל סוג פועל לפי כללים אחרים.

• שדות ברמה העליונה, כמו callMode, voice ו-greetingPrompt, הם הערכים שרכיב השיחות עולה איתם. הדשבורד גובר עליהם בסוכן הפעיל, ו-ninja-talk sync כותב את ערכי הדשבורד בחזרה לקובץ. את השדות האלה עורכים בדשבורד, לא כאן.
• הסעיפים המקוננים audio, context ו-features הם מקומיים בלבד. הדשבורד אף פעם לא שולח אותם, וסנכרון אף פעם לא נוגע בהם.

maxCalls, callTimeoutMinutes ו-idleTimeoutSeconds מקומיים בפועל: הדשבורד לא שולח אותם, ולכן סנכרון משאיר את מה שכתוב בקובץ.

context: מה נטען לכל שיחה

context.files מפרט את קובצי סביבת העבודה שנכנסים להנחיות של הסוכן בכל שיחה. בהתקנה חדשה נטענים SOUL.md, IDENTITY.md ו-USER.md. הוסיפו את MEMORY.md אם הסוכן צריך להביא לשיחות את הזיכרון לטווח ארוך שלו. USER.md משמש רק בשיחות של בעל העסק ובשיחות שהסוכן מוציא, אף פעם לא בשיחות ציבוריות.

"context": {
  "files": ["SOUL.md", "IDENTITY.md", "USER.md", "MEMORY.md", "brand-tone.md"],
  "voicePlaybook": null
}

כל פריט נוסף ברשימה חייב להיות קובץ .md בתוך סביבת העבודה, עד 10 KB, ולא קישור סימבולי. פריט שלא עומד בזה מדולג ונרשם בלוג. voicePlaybook מפנה לקובץ פלייבוק אחר. ראו פלייבוקים.

features: המתגים של רכיב השיחות

audio: כוונון הקו

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

החלת שינוי

תוכנית ההתקנה מוסיפה פקודה לניהול השירות, ninja-talk:

ninja-talk config      # open config.json in your editor
ninja-talk restart     # restart so config.json changes take effect
ninja-talk logs -f     # follow the service log
ninja-talk sync        # pull dashboard settings into config.json, then restart
ninja-talk doctor      # quick health check
ninja-talk update      # install the latest gateway (playbook, config and workspace untouched)
ninja-talk rollback    # go back to the binary before the last update

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

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

[ninja-talk:context] System instruction built {"mode":"public","totalBytes":21844,
  "agentName":"Alex","hasMemory":false,"hasPlaybook":true,"hasStaticSources":true,
  ...,"truncated":false,"stubMode":false,...}

hasPlaybook: false אומר שהפלייבוק לא נמצא או נדחה. truncated: true אומר שההנחיות חרגו מהתקציב ומשהו נחתך. ראו פלייבוקים.

איזה ערך גובר

1. רק בסעיפים audio, context ו-features: משתנה סביבה NINJA_TALK_* שהוגדר לשירות. זו עקיפה לשעת חירום, וכמעט אף פעם אין בה צורך. שדות ברמה העליונה תמיד מגיעים מהקובץ.
2. הערך ב-config.json.
3. ברירת המחדל שמקומפלת לתוך רכיב השיחות.

בהגדרות שהדשבורד מנהל, ערך הדשבורד מחליף את הערך שאיתו רכיב השיחות עלה, ברגע שרכיב השיחות משך אותו.

כשמשהו לא משתנה

• ערכתם את config.json ושום דבר לא קרה. הפעילו מחדש את השירות. אחר כך בדקו שהקובץ תקין: jq . ~/ninja-talk/config.json. קובץ לא תקין מונע מהשירות לעלות.
• שיניתם הגדרה בדשבורד, והסוכן עדיין עובד לפי הערך הישן. חכו חמש דקות והתקשרו שוב. אם עדיין לא השתנה, הריצו ninja-talk doctor (שירות, פורט, קובצי סביבת עבודה ומנהרה) ובדקו בלוג אם יש שגיאות במשיכת התצורה.
• נראה שערך מסוים לא נקלט. חפשו עקיפת NINJA_TALK_* שנשכחה בסביבת השירות, וודאו שהמספרים בטווח המותר: ערך מחוץ לטווח חוזר לברירת המחדל.
• פרטי גישה נראים שגויים. הפיקו טוקן חדש והריצו שוב את תוכנית ההתקנה. לעולם אל תערכו את .env ידנית.

עוד בדף פתרון תקלות.