AI Agent平臺 新手指南：本地 AI 自動化怎么跑起來

什么是 AI Agent平臺？

AI Agent平臺 是一個開源的、可本地運行的 AI 自動化框架。它不依賴云服務，所有數據和推理都在你自己的機器上完成。支持 WhatsApp、Telegram、Discord、Slack、Facebook Messenger 等 30+ 平臺，能統一配置、多端同步執行任務。

它不綁定特定模型：Claude、GPT-3.5/4（通過 API）、Ollama 托管的本地模型（如 Llama 3、Qwen2）、甚至 Hugging Face 上的 Transformers 模型都能接入。調度邏輯寫在 YAML 里，模型切換只需改幾行配置。

本地化部署

沒有后臺服務，沒有數據上傳。消息解析、意圖識別、回復生成全部在本地完成。你控制輸入，也控制輸出——不需要為隱私或延遲妥協。

跨平臺任務編排

你寫一個任務，它就能在多個平臺生效。比如：

• 同一套規則，在 Telegram 和 WhatsApp 上同時監聽關鍵詞
• 同一個工作流，把 Discord 的通知轉發到 Slack，并用本地模型摘要內容
• 不用為每個平臺重寫邏輯，只維護一份 tasks/ 下的 YAML

多模型調度

AI Agent平臺 把模型當“插件”用。你在 config.yaml 里聲明可用模型，任務里指定用哪個：

models:
  default: "ollama:qwen2:7b"
  available:
    - "ollama:llama3:8b"
    - "openai:gpt-4o"
    - "anthropic:claude-3-haiku-20240307"

任務中可以硬編碼模型名，也可以用條件路由（比如短文本走本地小模型，長文檔走 GPT-4o）。

安裝與配置

1. 基礎環境

確保系統滿足：

• Python 3.8+（3.7 已棄用，部分依賴不兼容）
• Git（用于拉代碼）
• 操作系統：Linux/macOS 推薦；Windows 需啟用 WSL2 或用 Conda 環境（PowerShell 原生命令支持有限）

?? 注意：AI Agent平臺 本身不帶大模型。調用本地模型需提前安裝 Ollama 或 vLLM；調用 API 模型需準備對應密鑰。

2. 克隆代碼

git clone https://github.com/yourusername/AI Agent平臺.git
cd AI Agent平臺

別用 ZIP 下載——后續更新、切分支、提 PR 都會卡住。

3. 安裝依賴

pip install -r requirements.txt

依賴包含：

• httpx（異步 HTTP 客戶端，對接各平臺 Webhook）
• pyyaml（讀取配置和任務定義）
• jinja2（模板渲染，用于動態回復）
• ollama（可選，僅當你用 Ollama 模型時需要）

4. 配置平臺與模型

編輯 config/config.yaml：

platforms:
  telegram:
    token: "654321:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    webhook_url: "https://your-domain.com/webhook/telegram"
  whatsapp:
    phone_id: "1234567890"
    verify_token: "my-secret-token"
    access_token: "EAAG..."

models:
  default: "ollama:qwen2:7b"
  openai:
    api_key: "sk-..."
    base_url: "https://api.openai.com/v1"
  anthropic:
    api_key: "sk-ant-..."

• Telegram 需先在 @BotFather 創建 bot 獲取 token
• WhatsApp 需 Meta Developer 賬戶 + Business Manager 配置
• 本地模型（如 ollama:qwen2:7b）要求已運行 ollama run qwen2:7b

5. 啟動

python main.py

啟動后你會看到類似輸出：

? Loaded 2 platforms: telegram, whatsapp
? Loaded 3 models: ollama:qwen2:7b, openai:gpt-4o, anthropic:claude-3-haiku
?? Listening on http://localhost:8000

服務默認監聽 localhost:8000，Webhook 地址需反向代理（如 Nginx）暴露到公網。

寫第一個任務

在 tasks/auto_reply.yaml 里寫：

name: "Hello 回復器"
platforms: [telegram, whatsapp]
trigger:
  type: "message"
  pattern: "^hello|hi|hey$"
  case_sensitive: false
action:
  type: "reply"
  text: "Hello! How can I assist you today?"
  model: "ollama:qwen2:7b"  # 顯式指定模型

• pattern 是正則表達式，^hello|hi|hey$ 匹配獨立單詞
• model 字段可省略，默認用 config 中的 default
• 支持 Jinja2 模板：text: "Hi {{ user.name }}! Time is {{ now | datetime('%H:%M') }}"

保存后重啟 main.py（或發 SIGUSR1 信號熱重載，見 docs/hot-reload.md）。

驗證是否跑通

1. 查看終端日志：啟動無報錯，且顯示 Loaded X tasks
2. 在 Telegram 私聊你的 bot，發 hello
3. 等待 1–3 秒（取決于本地模型加載速度），收到回復
4. 同樣測試 WhatsApp（需先完成 Meta 認證流程）

如果沒響應：

• 檢查平臺 Webhook 是否成功注冊（Telegram 用 getWebhookInfo，WhatsApp 查 Cloud API 日志）
• curl -X POST http://localhost:8000/debug/log 查最近 10 條處理記錄
• 用 --log-level debug 啟動看詳細鏈路：python main.py --log-level debug

常見問題

AI Agent平臺 啟動失敗

• 報 ModuleNotFoundError：確認 pip install 在當前 Python 環境執行（which python 和 which pip 是否一致）
• 報 ConnectionRefusedError：檢查 config.yaml 中 webhook_url 是否可訪問（本地測試用 ngrok http 8000 臨時暴露）
• 報 ValidationError：YAML 縮進錯誤，用 YAML Lint 校驗

自動回復不觸發

• 觸發詞被平臺過濾（如 WhatsApp 對短消息限頻），換長一點的 pattern："how are you doing today"
• Telegram Bot 設置了 Privacy Mode（默認開啟），需在 @BotFather 發 /setprivacy → Disable
• 任務文件沒放在 tasks/ 目錄下，或擴展名不是 .yaml

模型返回空或超時

• Ollama 模型未拉取：ollama list 看是否在列表里，不在就 ollama pull qwen2:7b
• OpenAI 密鑰無效：curl https://api.openai.com/v1/models -H "Authorization: Bearer sk-..." 測試
• 本地模型顯存不足：啟動時加 --num-gpu 0 強制 CPU 推理（慢但能跑）

下一步

• 把 auto_reply.yaml 改成調用 action: "run_script"，執行 Python 腳本查天氣、讀 RSS、寫數據庫
• 用 trigger.type: "schedule" 寫定時任務，比如每天早 8 點推送新聞摘要
• 在 models.available 加入 transformers:bert-base-chinese，做中文情感分析再路由
• 看 examples/ 目錄里的真實用例：多輪對話狀態機、跨平臺客服工單同步、自動歸檔 Discord 日志

GitHub 倉庫：https://github.com/yourusername/AI Agent平臺
最新文檔：docs/ 目錄下的 Markdown 文件（比本指南更細）