آموزش Hermes Agent؛ نصب، اتصال مدل هوش مصنوعی و تلگرام (۱۴۰۵)

اگر به دنبال آموزش hermes agent هستید، در این راهنما به‌صورت کامل یاد می‌گیرید که Hermes Agent چیست، چگونه نصب می‌شود، چطور به یک مدل هوش مصنوعی مانند Ollama، OpenAI یا سرویس‌های سازگار متصل می‌شود و چگونه می‌توانید آن را به تلگرام وصل کنید تا یک ربات هوشمند تلگرامی داشته باشید.

این آموزش برای کاربران مبتدی و نیمه‌حرفه‌ای نوشته شده است. حتی اگر قبلاً ربات تلگرامی نساخته‌اید، با دنبال‌کردن مرحله‌به‌مرحله این مقاله می‌توانید Hermes Agent را راه‌اندازی کنید.

نکته: این راهنما بر اساس ساختار رایج پروژه‌های Hermes Agent و عامل‌های هوش مصنوعی مبتنی بر LLM نوشته شده است. اگر نسخه خاصی از Hermes Agent را نصب می‌کنید، ممکن است نام برخی دستورها یا متغیرهای تنظیمات کمی متفاوت باشد. در این صورت فایل README یا env.example. پروژه را بررسی کنید.

فهرست مطالب

Hermes Agent چیست؟
پیش‌نیازهای نصب Hermes Agent
ساخت ربات تلگرام با BotFather
آماده‌سازی مدل هوش مصنوعی
نصب Hermes Agent
تنظیم فایل .env
اجرای Hermes Agent
تست ربات در تلگرام
اتصال Hermes Agent به تلگرام با Webhook
نکات امنیتی و بهینه‌سازی
رفع مشکلات رایج
سوالات متداول
جمع‌بندی

Hermes Agent چیست؟

Hermes Agent یک عامل هوش مصنوعی یا AI Agent است که می‌تواند پیام‌های کاربر را از کانال‌هایی مانند تلگرام دریافت کند، آن‌ها را به یک مدل زبانی بزرگ ارسال کند و پاسخ تولیدشده را دوباره به کاربر برگرداند.

در حالت ساده، Hermes Agent مانند یک پل بین تلگرام و مدل هوش مصنوعی عمل می‌کند:

در نسخه‌های پیشرفته‌تر، Hermes Agent ممکن است امکاناتی مانند موارد زیر داشته باشد:

حافظه مکالمه
اجرای ابزارها
استفاده از Function Calling
اتصال به APIهای خارجی
پردازش فایل، عکس یا صدا
مدیریت چند کاربر
محدودسازی دسترسی کاربران
پشتیبانی از چند مدل
اجرای محلی یا ابری

بنابراین اگر می‌خواهید یک ربات هوشمند تلگرامی بسازید که به مدل‌هایی مانند Hermes 3، Llama، Qwen، Mistral، GPT یا مدل‌های محلی Ollama متصل شود، آموزش hermes agent می‌تواند نقطه شروع بسیار خوبی باشد.

پیش‌نیازهای نصب Hermes Agent

قبل از شروع نصب، مطمئن شوید که موارد زیر را دارید:

۱. سرور یا سیستم مناسب

شما می‌توانید Hermes Agent را روی یکی از محیط‌های زیر نصب کنید:

ویندوز
لینوکس
macOS
سرور مجازی یا VPS
داکر

برای استفاده جدی و دائمی، بهتر است از یک سرور مجازی لینوکسی استفاده کنید. اگر ربات باید همیشه آنلاین باشد، VPS گزینه بهتری نسبت به سیستم خانگی است.

۲. Python یا Docker

بسیاری از عامل‌های هوش مصنوعی با Python اجرا می‌شوند. بنابراین داشتن Python نسخه ۳.۱۰ یا بالاتر توصیه می‌شود.

برای بررسی نسخه Python در لینوکس یا macOS:

python3 --version

یا:

python --version

اگر از Docker استفاده می‌کنید، نیازی به نصب مستقیم Python نیست.

۳. حساب تلگرام

برای اتصال Hermes Agent به تلگرام، به یک حساب تلگرام و یک ربات نیاز دارید.

۴. مدل هوش مصنوعی

شما باید یکی از گزینه‌های زیر را برای مدل هوش مصنوعی انتخاب کنید:

مدل محلی با Ollama
API سرویس OpenAI
API سرویس‌های سازگار با OpenAI
مدل‌های محلی دیگر
APIهای داخلی یا سازمانی

اگر می‌خواهید بدون هزینه و به‌صورت محلی اجرا کنید، Ollama گزینه بسیار مناسبی است.

مرحله ۱: ساخت ربات تلگرام با BotFather

برای اتصال Hermes Agent به تلگرام، ابتدا باید یک ربات تلگرامی بسازید.

مراحل ساخت ربات

۱. در تلگرام عبارت BotFather@ را جستجو کنید.
۲. وارد ربات BotFather شوید.
۳. دستور /newbot را ارسال کنید.
۴. یک نام برای ربات انتخاب کنید.
۵. یک یوزرنیم منحصربه‌فرد برای ربات انتخاب کنید که حتماً با bot تمام شود.

مثال:

Name: My Hermes Agent
Username: my_hermes_agent_bot

۶. پس از موفقیت‌آمیز بودن ساخت ربات، BotFather یک توکن به شما می‌دهد.

مثال توکن:

123456789:AAExampleTelegramBotTokenExampleToken

این توکن را در جای امن ذخیره کنید. هر کسی به این توکن دسترسی داشته باشد، می‌تواند ربات شما را کنترل کند.

مرحله ۲: دریافت User ID

برای محدود کردن دسترسی ربات به خودتان یا کاربران مشخص، بهتر است User ID داشته باشید.

پیدا کردن User ID عددی

برای محدودسازی دسترسی، به User ID عددی خودتان نیاز دارید (نه یوزرنیم). ساده‌ترین راه رسمی:

۱. در تلگرام به @userinfobot پیام دهید.

۲. این ربات فوراً User ID عددی شما را برمی‌گرداند (مثلاً 123456789).

۳. این عدد را یادداشت کنید.

تفاوت با نسخهٔ قبلی: در روش رسمی Hermes، به‌جای Chat ID و متغیر ALLOWED_CHAT_IDS، از User ID و متغیر TELEGRAM_ALLOWED_USERS استفاده می‌شود.

مرحله ۳: آماده‌سازی مدل هوش مصنوعی

در آموزش hermes agent، یکی از مهم‌ترین بخش‌ها اتصال مدل هوش مصنوعی است. شما دو انتخاب اصلی دارید:

گزینه الف: استفاده از مدل محلی با Ollama

اگر سیستم قوی دارید یا می‌خواهید بدون ارسال داده به سرویس خارجی، مدل را محلی اجرا کنید، Ollama گزینه مناسبی است.

نصب Ollama در لینوکس و mac

curl -fsSL https://ollama.com/install.sh | sh

نصب Ollama در ویندوز

برای نصب Ollama در ویندوز می‌توانید از طریق دستور زیر در PowerShell نصب کنید

irm https://ollama.com/install.ps1 | iex

نصب با فایل اجرایی

با مراجعه به آدرس زیر می‌توانید فایل نصبی را دانلود و اجرا نصب کنید:

https://ollama.com/download/

بررسی نصب

ollama --version

دانلود مدل

می‌توانید از مدل‌های مختلف استفاده کنید. برای مثال:

ollama pull qwen2.5

بررسی مدل‌های نصب‌شده

ollama list

تست سریع مدل

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes3",
    "messages": [
      {"role": "user", "content": "سلام، خودت را معرفی کن."}
    ]
  }'

اگر خروجی JSON دریافت کردید، یعنی Ollama آماده است.

گزینه ب: استفاده از API سازگار با OpenAI

اگر نمی‌خواهید مدل را محلی اجرا کنید، می‌توانید از API استفاده کنید.

مثلاً:

OpenAI API
Azure OpenAI
سرویس‌های سازگار با OpenAI
APIهای داخلی شرکتی

در این حالت معمولاً به موارد زیر نیاز دارید:

API Key
Base URL
Model Name

مثال برای OpenAI:

Base URL: https://api.openai.com/v1
Model: gpt-4o-mini

مثال برای Ollama محلی:

Base URL: http://localhost:11434/v1
Model: hermes3

مرحله ۴: نصب Hermes Agent (روش رسمی)

برخلاف بسیاری از عامل‌های هوش مصنوعی که نیاز به ساخت دستی محیط مجازی، نصب Python و مدیریت وابستگی‌ها دارند، نصب‌کنندهٔ رسمی Hermes Agent تقریباً همه‌چیز را خودکار انجام می‌دهد. در این بخش از آموزش hermes agent دقیقاً همان روشی را می‌رویم که در مستندات رسمی توصیه شده است.

پیش‌نیازهای واقعی نصب

برخلاف تصور رایج، شما نیازی ندارید Python، Node.js، ripgrep یا ffmpeg را دستی نصب کنید. نصب‌کننده خودش این‌ها را مدیریت می‌کند (Python 3.11 از طریق uv، Node.js v22، ripgrep و ffmpeg).

تنها پیش‌نیاز واقعی این است:

Git (در همهٔ پلتفرم‌ها)
در لینوکس: curl و xz-utils
برای نسخهٔ دسکتاپ: g++ یا build-essential

بررسی Git:

git --version

نصب پیش‌نیازها در دبیان/اوبونتو:

sudo apt install curl xz-utils git
# فقط اگر نسخه دسکتاپ می‌خواهید:
sudo apt install build-essential

روش الف: نصب سریع خط فرمان (پیشنهادی برای سرور/VPS)

لینوکس / macOS / WSL2 / اندروید (Termux):

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

ویندوز (در PowerShell):

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

این اسکریپت به‌صورت خودکار انجام می‌دهد:

نصب وابستگی‌ها (Python، Node.js، ripgrep، ffmpeg)
کلون مخزن
ساخت محیط مجازی
راه‌اندازی دستور سراسری hermes
پیکربندی اولیهٔ ارائه‌دهندهٔ مدل (LLM provider)

روش ب: نصب‌کنندهٔ دسکتاپ (پیشنهادی برای macOS و ویندوز)

اگر محیط گرافیکی می‌خواهید، نصب‌کنندهٔ Hermes Desktop را از سایت رسمی Hermes دانلود و اجرا کنید. این روش هم خط فرمان و هم اپ دسکتاپ را نصب می‌کند.

اگر قبلاً با خط فرمان نصب کرده‌اید و حالا دسکتاپ را می‌خواهید، کافی است بزنید:

hermes desktop

محل نصب فایل‌ها

حالت نصب	محل کد	باینری `hermes`	پوشهٔ داده
کاربر عادی	`~/.hermes/hermes-agent/`	`~/.local/bin/hermes`	`~/.hermes/`
حالت root	`/usr/local/lib/hermes-agent/`	`/usr/local/bin/hermes`	`/root/.hermes/`

فعال‌سازی و بررسی نصب

بعد از پایان نصب، شل را بارگذاری مجدد کنید و دستور hermes را بزنید:

source ~/.bashrc   # یا: source ~/.zshrc
hermes             # شروع چت!

اگر خطای hermes: command not found دیدید، یعنی مسیر ~/.local/bin در PATH شما نیست. راه‌حل:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

برای عیب‌یابی کامل و دیدن اینکه چه چیزی کم است، از دستور رسمی زیر استفاده کنید:

hermes doctor

این دستور دقیقاً می‌گوید چه چیزی نصب نیست و چگونه باید درستش کرد.

مرحله ۵: پیکربندی مدل هوش مصنوعی

در آموزش hermes agent، بعد از نصب باید مشخص کنید Hermes از کدام مدل و کدام ارائه‌دهنده استفاده کند. مستندات رسمی چند راه برای این کار دارند.

راه پیشنهادی: ویزارد راه‌اندازی با Nous Portal

اگر می‌خواهید با یک اشتراک به بیش از ۳۰۰ مدل plus دسترسی به Tool Gateway (جست‌وجوی وب، تولید تصویر، تبدیل متن به گفتار، مرورگر ابری) برسید و درگیر کلیدهای جداگانه نشوید:

hermes setup --portal

این دستور شما را لاگین می‌کند، Nous را به‌عنوان ارائه‌دهنده تنظیم می‌کند و Tool Gateway را روشن می‌کند.

راه عمومی: ویزارد کامل یا تنظیم مدل

برای پیکربندی همه‌چیز یک‌جا:

hermes setup

برای انتخاب/تغییر ارائه‌دهنده و مدل:

hermes model

سایر دستورات پیکربندی رسمی:

hermes tools          # فعال/غیرفعال کردن ابزارها
hermes gateway setup  # راه‌اندازی پلتفرم‌های پیام‌رسان (مثل تلگرام)
hermes config set     # تنظیم یک مقدار خاص
hermes config get     # مشاهدهٔ یک مقدار خاص

استفاده از ارائه‌دهنده‌های مختلف

Hermes با ارائه‌دهنده‌هایی مانند Nous Portal، OpenRouter، OpenAI، Anthropic و سرویس‌های سازگار کار می‌کند. کلید API مربوطه معمولاً در ~/.hermes/.env قرار می‌گیرد. مثال:

hermes config set OPENROUTER_API_KEY your_key_here

نکتهٔ مهم برای مدل محلی: اگر در مرحلهٔ ۳ مقالهٔ قبلی Ollama را آماده کرده‌اید، می‌توانید از طریق hermes model یک ارائه‌دهندهٔ سازگار با OpenAI تعریف کنید و Base URL را روی http://localhost:11434/v1 بگذارید. اما روش رسمی و بی‌دردسرتر برای شروع، استفاده از hermes setup --portal یا یک کلید API ابری است.

تست مدل در خط فرمان

قبل از رفتن سراغ تلگرام، مطمئن شوید مدل درست کار می‌کند:

hermes chat -q "سلام، خودت را معرفی کن."

اگر پاسخ گرفتید، یعنی اتصال مدل سالم است و می‌توانید به مرحلهٔ اتصال تلگرام بروید.

مرحله ۶: اتصال Hermes Agent به تلگرام (Gateway)

روش الف: ویزارد تعاملی (پیشنهادی)

hermes gateway setup

در ویزارد، Telegram را انتخاب کنید، توکن ربات را بچسبانید و User ID خود را وارد کنید.

روش ب: تنظیم دستی در ~/.hermes/.env

# توکن ربات از BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# User ID عددی شما (چند کاربر با کاما)
TELEGRAM_ALLOWED_USERS=123456789

مرحله ۷: اجرای Gateway و تست در تلگرام

تست سریع (در پیش‌زمینه)

اول Gateway را در پیش‌زمینه اجرا کنید تا مطمئن شوید همه‌چیز درست است:

hermes gateway

خروجی مورد انتظار:

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

حالا در تلگرام ربات خود را باز کنید و یک پیام بفرستید. اگر پاسخ گرفتید، یعنی اتصال موفق است. با Ctrl+C متوقفش کنید.

تست‌های کاربردی در تلگرام

بعد از اتصال، این پیام‌ها را امتحان کنید:

سلام، حالت چطوره؟

/model

اگر ربات پاسخ داد، تبریک می‌گویم؛ ربات هوشمند تلگرامی شما با Hermes Agent کار می‌کند.

مرحله ۸: نصب Gateway به‌عنوان سرویس دائمی

برای اینکه ربات بعد از ریستارت سرور یا بستن ترمینال هم آنلاین بماند، آن را به‌عنوان سرویس نصب کنید.

نصب سرویس

hermes gateway install

برای سرویس سطح سیستم در لینوکس (که از زمان بوت اجرا شود):

sudo hermes gateway install --system

این دستور در لینوکس یک سرویس systemd سطح کاربر، در macOS یک سرویس launchd، و با --system یک سرویس سطح سیستم در لینوکس می‌سازد.

مدیریت سرویس (لینوکس، سرویس کاربر)

hermes gateway start
hermes gateway stop
hermes gateway status

مشاهدهٔ لاگ زنده:

journalctl --user -u hermes-gateway -f

نگه‌داشتن سرویس بعد از خروج از SSH

اگر با SSH به سرور وصل می‌شوید، برای اینکه سرویس کاربر بعد از قطع اتصال هم کار کند:

sudo loginctl enable-linger $USER

دستورات سرویس سطح سیستم (لینوکس)

sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

macOS

hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

نکته: plist مربوط به launchd، مسیر PATH شل شما را در زمان نصب ثبت می‌کند. اگر بعداً ابزار جدیدی (مثل Node.js یا ffmpeg) نصب کردید، برای به‌روزرسانی plist دوباره hermes gateway install را بزنید.

مرحله ۹: مدیریت دسترسی کاربران و تیم

اگر ربات را برای تیم می‌سازید، دو روش رسمی برای دادن دسترسی دارید.

روش الف: لیست ثابت (Static Allowlist)

User ID عددی هر عضو تیم را (با @userinfobot) بگیرید و با کاما در .env بنویسید:

TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

بعد از تغییر، Gateway را ری‌استارت کنید:

hermes gateway stop && hermes gateway start
یا
hermes gateway restart

روش ب: جفت‌سازی با DM (پیشنهادی برای تیم)

در این روش نیازی نیست از قبل User IDها را جمع کنید:

۱. عضو تیم به ربات DM می‌دهد؛ چون در لیست نیست، ربات یک کد جفت‌سازی یک‌بارمصرف برمی‌گرداند:

Pairing code: XKGH5N7P

۲. عضو تیم این کد را (از طریق اسلک، ایمیل یا حضوری) به شما می‌دهد.

۳. شما روی سرور تأیید می‌کنید:

hermes pairing approve telegram XKGH5N7P

۴. از همان لحظه ربات به پیام‌های او پاسخ می‌دهد.

مدیریت کاربران جفت‌شده:

hermes pairing list                 # مشاهدهٔ کاربران در انتظار و تأییدشده
hermes pairing revoke telegram 987654321   # لغو دسترسی یک کاربر
hermes pairing clear-pending        # پاک‌سازی کدهای منقضی

مزیت این روش: برای افزودن کاربر جدید نیازی به ری‌استارت Gateway نیست و تأییدها آنی اثر می‌کنند.

ملاحظات امنیتی جفت‌سازی

هرگز روی رباتی که دسترسی ترمینال دارد، GATEWAY_ALLOW_ALL_USERS=true نگذارید؛ وگرنه هرکس ربات را پیدا کند می‌تواند روی سرور شما دستور اجرا کند.
کدهای جفت‌سازی بعد از ۱ ساعت منقضی می‌شوند.
محدودیت نرخ درخواست: هر کاربر هر ۱۰ دقیقه یک درخواست، حداکثر ۳ کد در انتظار per پلتفرم.
بعد از ۵ تلاش تأیید ناموفق، پلتفرم ۱ ساعت قفل می‌شود.
داده‌های جفت‌سازی با دسترسی chmod 0600 ذخیره می‌شوند.

مرحله ۱۰: شخصی‌سازی ربات تلگرام

تنظیم Home Channel

Home Channel جایی است که خروجی کارهای زمان‌بندی‌شده (cron) و پیام‌های فعال ربات ارسال می‌شود. بدون آن، کارهای زمان‌بندی‌شده جایی برای فرستادن خروجی ندارند.

روش ۱: در هر گروه تلگرامی که ربات عضو آن است، دستور /sethome را بزنید.

روش ۲: تنظیم دستی در .env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

برای پیدا کردن ID گروه، @userinfobot را به گروه اضافه کنید تا chat ID گروه را گزارش دهد.

تنظیم میزان نمایش پیشرفت ابزارها

در ~/.hermes/config.yaml:

display:
  tool_progress: new    # off | new | all | verbose

حالت	آنچه می‌بینید
`off`	فقط پاسخ تمیز، بدون فعالیت ابزار
`new`	وضعیت کوتاه برای هر فراخوانی جدید ابزار (پیشنهادی برای پیام‌رسان)
`all`	هر فراخوانی ابزار با جزئیات
`verbose`	خروجی کامل ابزار شامل نتیجهٔ دستورات

کاربر هم می‌تواند در چت با /verbose این مقدار را برای نشست خود تغییر دهد.

شخصیت ربات با SOUL.md

لحن و سبک پاسخ ربات را با ویرایش ~/.hermes/SOUL.md تنظیم کنید:

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries — the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

افزودن زمینهٔ پروژه با AGENTS.md

اگر تیم روی پروژهٔ خاصی کار می‌کند، یک فایل زمینه بسازید تا ربات stack شما را بشناسد:

<!-- ~/.hermes/AGENTS.md -->
# Team Context
- We use Python 3.12 with FastAPI and SQLAlchemy
- Frontend is React with TypeScript
- CI/CD runs on GitHub Actions
- Production deploys to AWS ECS
- Always suggest writing tests for new code

این فایل‌ها به prompt سیستمی هر نشست تزریق می‌شوند. پس مختصر بنویسید؛ هر کاراکتر از بودجهٔ توکن کم می‌کند.

مرحله ۱۱: کار با خط فرمان (CLI) Hermes Agent

CLI رسمی Hermes یک رابط ترمینالی کامل (TUI) است، نه یک رابط وب. برای شروع چت تعاملی:

hermes

یا رابط TUI مدرن با پشتیبانی ماوس:

hermes --tui

حالت‌های اجرای CLI

# چت تعاملی (پیش‌فرض)
hermes

# تک‌پرسش (غیرتعاملی)
hermes chat -q "Hello"

# با مدل خاص
hermes chat --model "anthropic/claude-sonnet-4"

# با ارائه‌دهندهٔ خاص
hermes chat --provider nous
hermes chat --provider openrouter

# با مجموعه ابزار خاص
hermes chat --toolsets "web,terminal,skills"

# با پیش‌بارگذاری skill
hermes -s hermes-agent-dev,github-auth

# ادامهٔ نشست قبلی
hermes --continue          # یا: hermes -c
hermes --resume <session_id>   # یا: hermes -r

کلیدهای میانبر مهم

کلید	عملکرد
`Enter`	ارسال پیام
`Alt+Enter` / `Ctrl+J` / `Shift+Enter`	خط جدید
`Ctrl+V`	چسباندن متن (و در صورت وجود، تصویر کلیپ‌بورد)
`Ctrl+G`	باز کردن بافر ورودی در ویرایشگر خارجی
`Ctrl+C`	قطع عامل (دو بار در ۲ ثانیه = خروج اجباری)
`Ctrl+D`	خروج
`Ctrl+Z`	تعلیق به پس‌زمینه (فقط یونیکس؛ با `fg` برمی‌گردد)
`Tab`	پذیرش پیشنهاد خودکار یا تکمیل slash command

دستورات اسلش پرکاربرد

با تایپ / منوی تکمیل خودکار باز می‌شود. نمونه‌ها:

دستور	توضیح
`/help`	راهنمای دستورات
`/model`	نمایش/تغییر مدل
`/tools`	فهرست ابزارهای فعال
`/skills browse`	مرور hub مهارت‌ها
`/background <prompt>`	اجرای prompt در نشست پس‌زمینه
`/voice on`	فعال‌سازی حالت صوتی
`/reasoning high`	افزایش تلاش استدلال
`/title My Session`	نام‌گذاری نشست
`/status`	اطلاعات نشست
`/sessions`	انتخابگر نشست‌ها
`/personality pirate`	تغییر شخصیت

نشست‌های پس‌زمینه

می‌توانید یک کار را در پس‌زمینه اجرا کنید و هم‌زمان به چت ادامه دهید:

/background Analyze the logs in /var/log and summarize any errors from today

هر کار پس‌زمینه یک نشست کاملاً جداگانه با ID اختصاصی (مثل bg_143022_a1b2c3) می‌سازد و نتیجه به‌صورت یک پنل در ترمینال نمایش داده می‌شود.

فشرده‌سازی خودکار زمینه

نشست‌های طولانی وقتی به حد زمینه نزدیک می‌شوند، خودکار خلاصه می‌شوند. تنظیمات در config.yaml:

compression:
  enabled: true
  threshold: 0.50

هنگام فشرده‌سازی، ۳ پیام اول و ۲۰ پیام آخر همیشه حفظ می‌شوند و پیام‌های میانی خلاصه می‌شوند.

مرحله ۱۲: کارهای زمان‌بندی‌شده (Cron)

با Gateway در حال اجرا، می‌توانید کارهای تکرارشونده تعریف کنید که نتیجه را به کانال تیم می‌فرستند.

مثال: خلاصهٔ standup روزانه

در تلگرام به ربات پیام دهید:

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:
1. Pull requests opened/merged in the last 24 hours
2. Issues created or closed
3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

عامل خودکار یک cron job می‌سازد و نتیجه را به همان چت (یا home channel) می‌فرستد.

مثال: بررسی سلامت سرور

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual.

مدیریت کارهای زمان‌بندی‌شده

hermes cron list      # مشاهدهٔ همهٔ کارها
hermes cron status    # بررسی اجرای زمان‌بند

در چت تلگرام:

/cron list
/cron remove <job_id>

نکته: promptهای cron در نشست‌های کاملاً تازه و بدون حافظهٔ قبلی اجرا می‌شوند. پس هر prompt باید همهٔ زمینهٔ لازم (مسیرها، URLها، آدرس سرور و دستور دقیق) را شامل باشد.

نکات امنیتی مهم در آموزش hermes agent

۱. هرگز GATEWAY_ALLOW_ALL_USERS=true را روی رباتی با دسترسی ترمینال فعال نکنید.

۲. توکن ربات و کلیدهای API را منتشر نکنید و فایل .env را در Git آپلود نکنید.

۳. دسترسی کاربران را محدود کنید با TELEGRAM_ALLOWED_USERS یا DM Pairing.

۴. برای ربات تیمی، از Docker به‌عنوان بک‌اند ترمینال استفاده کنید تا دستورات عامل داخل کانتینر اجرا شوند، نه روی میزبان:

TERMINAL_ENV=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

یا در config.yaml:

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

۵. لاگ‌ها را رصد کنید:

journalctl --user -u hermes-gateway -f   # لینوکس
tail -f ~/.hermes/logs/gateway.log       # macOS

۶. Hermesبروزرسانی از تلگرام /update بفرستید یا روی سرور:

hermes update
hermes gateway stop && hermes gateway start

رفع مشکلات رایج (بر اساس مستندات رسمی)

مشکل	راه‌حل رسمی
`hermes: command not found`	شل را بارگذاری کنید (`source ~/.bashrc`) یا PATH را بررسی کنید
`API key not set`	`hermes model` را اجرا کنید یا `hermes config set OPENROUTER_API_KEY your_key`
Missing config after update	`hermes config check` سپس `hermes config migrate`
`ModuleNotFoundError: No module named 'dotenv'`	دارید `hermes` منبع مخزن را با پایتون سیستم اجرا می‌کنید؛ از لانچر venv استفاده کنید: `~/.hermes/hermes-agent/venv/bin/hermes`
ربات تلگرام پاسخ نمی‌دهد	توکن، `TELEGRAM_ALLOWED_USERS` و اجرای Gateway را بررسی کنید؛ `hermes gateway status`
خطای 409 Conflict	معمولاً تداخل دو نمونهٔ Gateway است؛ یکی را متوقف کنید
ربات در گروه پاسخ نمی‌دهد	ربات را عضو گروه کنید و در صورت نیاز Privacy Mode را در BotFather غیرفعال کنید

برای تشخیص هر مشکل، اول این دستور را بزنید:

hermes doctor

محل لاگ‌ها و داده‌ها

مورد	مسیر
لاگ Gateway	`journalctl --user -u hermes-gateway` (لینوکس) یا `~/.hermes/logs/gateway.log` (macOS)
خروجی cron	`~/.hermes/cron/output/{job_id}/{timestamp}.md`
تعریف cron	`~/.hermes/cron/jobs.json`
دادهٔ جفت‌سازی	`~/.hermes/pairing/`
تاریخچهٔ نشست‌ها	`~/.hermes/sessions/` و `~/.hermes/state.db`

چک‌لیست نهایی نصب Hermes Agent

Git (و در لینوکس curl و xz-utils) نصب است.
Hermes با اسکریپت رسمی نصب شده است.
hermes doctor بدون خطا اجرا می‌شود.
مدل با hermes model یا hermes setup --portal پیکربندی شده است.
hermes chat -q "test" پاسخ می‌دهد.
ربات تلگرام با BotFather ساخته شده است.
User ID عددی با @userinfobot گرفته شده است.
Gateway با hermes gateway setup یا .env تنظیم شده است.
hermes gateway در پیش‌زمینه تست شده است.
Gateway به‌عنوان سرویس نصب شده (hermes gateway install).
loginctl enable-linger اجرا شده است.
دسترسی کاربران با Allowlist یا Pairing محدود شده است.
SOUL.md و AGENTS.md در صورت نیاز تنظیم شده‌اند.
Home Channel برای کارهای cron تنظیم شده است.

سوالات متداول درباره آموزش hermes agent

۱. پیش‌نیاز نصب Hermes Agent چیست؟

در پلتفرم‌های غیر ویندوزی تنها پیش‌نیاز Git است و در لینوکس curl و xz-utils هم لازم‌اند. Python، Node.js، ripgrep و ffmpeg را خود نصب‌کننده مدیریت می‌کند.

۲. دستور نصب رسمی Hermes Agent چیست؟

در لینوکس/macOS: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash و در ویندوز (PowerShell): iex (irm https://hermes-agent.nousresearch.com/install.ps1).

۳. چگونه Hermes Agent را به تلگرام وصل کنم؟

با hermes gateway setup توکن ربات و User ID را وارد کنید، یا دستی در ~/.hermes/.env متغیرهای TELEGRAM_BOT_TOKEN و TELEGRAM_ALLOWED_USERS را تنظیم کنید، سپس hermes gateway را اجرا کنید.

۴. برای آنلاین ماندن دائمی ربات تلگرام چه کنم؟

با hermes gateway install آن را به سرویس تبدیل کنید و در لینوکس با sudo loginctl enable-linger $USER مطمئن شوید بعد از خروج SSH هم کار می‌کند.

۵. چگونه به اعضای تیم دسترسی بدهم؟

یا User ID آن‌ها را در TELEGRAM_ALLOWED_USERS اضافه کنید، یا از DM Pairing استفاده کنید: عضو کد را می‌گیرد و شما با hermes pairing approve telegram CODE تأیید می‌کنید.

۶. چرا ربات Hermes Agent پاسخ نمی‌دهد؟

دلایل رایج: توکن اشتباه، تنظیم نبودن TELEGRAM_ALLOWED_USERS، اجرا نبودن Gateway، یا تداخل دو نمونه. با hermes gateway status و hermes doctor بررسی کنید.

۷. آیا برای تلگرام باید Webhook دستی تنظیم کنم؟

خیر. Gateway خود Hermes اتصال تلگرام را مدیریت می‌کند و نیازی به تنظیم دستی Webhook و گواهی SSL نیست.

جمع‌بندی

در این بخش از آموزش hermes agent که بر اساس مستندات رسمی بازنویسی شد، یاد گرفتید Hermes Agent را با اسکریپت رسمی نصب کنید، با hermes doctor سلامت نصب را بررسی کنید، مدل را با hermes model یا hermes setup --portal پیکربندی کنید، ربات تلگرام بسازید، Gateway را با hermes gateway setup راه بیندازید، آن را به سرویس دائمی تبدیل کنید، دسترسی تیم را با Allowlist یا DM Pairing مدیریت کنید، ربات را با SOUL.md و AGENTS.md شخصی‌سازی کنید، کارهای زمان‌بندی‌شده تعریف کنید و با CLI پیشرفتهٔ Hermes (نشست‌های پس‌زمینه، فشرده‌سازی زمینه و دستورات اسلش) کار کنید.

تفاوت کلیدی این نسخه با روش‌های دستی قدیمی این است که تقریباً همهٔ وابستگی‌ها و پیکربندی‌ها توسط ابزار رسمی hermes مدیریت می‌شوند؛ پس به‌جای دست‌وپنجه نرم کردن با محیط مجازی و متغیرهای پراکنده، از دستورات hermes setup، hermes model، hermes gateway و hermes doctor استفاده کنید تا راه‌اندازی سریع، امن و قابل نگهداری باشد.