AI Agent平臺 新手指南

為什么用 AI Agent平臺？

AI Agent平臺 是一個開源 AI 自動化框架，能本地運行，也能跨平臺編排任務。它支持 WhatsApp、Telegram、Discord 等 30+ 平臺，不依賴單一服務。你用 Claude、GPT 或本地大模型（比如 Llama 3、Phi-3）都行，模型調用邏輯統一，切換成本低。

本地部署 = 數據不離手

所有消息解析、AI 推理、任務調度都在你自己的機器上完成。配置文件、聊天記錄、API 密鑰全存在本地，沒有后臺上傳行為。適合處理敏感信息或離線場景。

跨平臺不是拼湊，是統一抽象

每個平臺在 AI Agent平臺 里都映射為一個 Platform 實例：Telegram 用 bot token 和 chat_id，WhatsApp 用 WhatsApp Business API 憑據，Discord 用 bot token 和 channel ID。任務腳本里調用 oc.send_message()，底層自動路由到對應平臺，不用寫三套發送邏輯。

模型即插即用，不綁定供應商

ai-agent.models 提供標準接口：generate(prompt)、stream(prompt)、embed(text)。只要封裝好 GPTModel、ClaudeModel 或 LlamaCppModel，任務腳本里換一行初始化代碼就能切模型。本地模型走 llama.cpp 或 Ollama，云端模型走官方 SDK，AI Agent平臺 只管輸入輸出格式。

安裝步驟

前提條件

• Windows / macOS / Linux
• Python 3.7+
• Git

安裝流程

1. 確認 Python

python --version
# 輸出應為 Python 3.7.x 或更高

沒裝？去 python.org/downloads 下載安裝包，勾選 “Add Python to PATH”。

2. 確認 Git

git --version
# 輸出應為 git version 2.30+

沒裝？去 git-scm.com/downloads 下載安裝。

3. 克隆代碼

git clone https://github.com/your-repo/AI Agent平臺.git

4. 安裝依賴

cd AI Agent平臺
pip install -r requirements.txt

常見報錯？試試：

• pip install --upgrade pip
• Windows 上如果提示 Microsoft Visual C++ 14.0 缺失，裝 Build Tools for Visual Studio
• macOS 上如果 llama-cpp-python 編譯失敗，先 brew install llvm，再 export CC=/opt/homebrew/opt/llvm/bin/clang

5. 配置環境變量

# Linux/macOS
export OPENCLAW_API_KEY=sk-xxx
export OPENCLAW_TELEGRAM_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# Windows PowerShell
$env:OPENCLAW_API_KEY="sk-xxx"
$env:OPENCLAW_TELEGRAM_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

密鑰存 .env 文件也行（需 pip install python-dotenv），但環境變量更直接，啟動時自動加載。

快速上手：發一條 Telegram 消息

1. 配置 Telegram

編輯 config.yaml：

telegram:
  token: "${OPENCLAW_TELEGRAM_TOKEN}"
  chat_id: "-1001234567890"

chat_id 獲取方式：把 bot 加進群，訪問 https://api.telegram.org/bot<TOKEN>/getUpdates，看返回 JSON 里的 message.chat.id。

2. 寫個任務腳本

在 tasks/hello_world.py 里：

from ai-agent import AI Agent平臺

def main():
    oc = AI Agent平臺()
    oc.send_message("Hello from AI Agent平臺 ??")

if __name__ == "__main__":
    main()

3. 運行它

python tasks/hello_world.py

成功的話，目標 Telegram 群/私聊會收到消息。失敗？看終端報錯——通常是 config.yaml 字段名寫錯、環境變量沒生效，或網絡連不上 Telegram API。

4. 加入 AI 生成

改寫 hello_world.py：

from ai-agent import AI Agent平臺
from ai-agent.models import GPTModel

def main():
    oc = AI Agent平臺()
    model = GPTModel(model="gpt-4o-mini")
    response = model.generate("用一句話解釋 AI Agent平臺 的核心價值")
    oc.send_message(f"?? {response.strip()}")

if __name__ == "__main__":
    main()

注意：GPTModel 會自動讀取 OPENCLAW_API_KEY；本地模型換成 LlamaCppModel(model_path="./models/phi-3-mini.Q4_K_M.gguf") 即可。

故障排查

消息沒發出去？

• 檢查 config.yaml 里 telegram.token 和 telegram.chat_id 是否正確（尤其注意 -100 開頭的群 ID）
• 運行 python -c "import os; print(os.getenv('OPENCLAW_TELEGRAM_TOKEN'))" 確認環境變量已加載
• 手動 curl 測試 Telegram API：curl "https://api.telegram.org/bot${OPENCLAW_TELEGRAM_TOKEN}/getMe"

ModuleNotFoundError: No module named 'ai-agent'

• 確保你在 AI Agent平臺/ 目錄下運行命令
• 或者 pip install -e . 把項目安裝為可編輯模式

本地模型加載慢或 OOM？

• LlamaCppModel 默認用 4-bit 量化，加參數 n_gpu_layers=1 讓部分層跑 GPU（需 CUDA 支持）
• 內存不足時，加 n_ctx=2048 限制上下文長度

下一步

• 看 examples/ 目錄：定時提醒、多平臺轉發、PDF 總結、RAG 檢索都有現成腳本
• 改 config.yaml 加 WhatsApp 或 Discord，復用同一套任務邏輯
• 在 models/ 目錄下注冊新模型類，只要實現 generate() 方法就能接入

資源

• AI Agent平臺 GitHub 倉庫
• AI Agent平臺 文檔
• Python 官網
• Git 官網