AI Agent平臺(tái) 新手指南

為什么用 AI Agent平臺(tái)？

AI Agent平臺(tái) 是一個(gè)開源 AI 自動(dòng)化框架，能本地運(yùn)行，也能跨平臺(tái)編排任務(wù)。它支持 WhatsApp、Telegram、Discord 等 30+ 平臺(tái)，不依賴單一服務(wù)。你用 Claude、GPT 或本地大模型（比如 Llama 3、Phi-3）都行，模型調(diào)用邏輯統(tǒng)一，切換成本低。

本地部署 = 數(shù)據(jù)不離手

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

跨平臺(tái)不是拼湊，是統(tǒng)一抽象

每個(gè)平臺(tái)在 AI Agent平臺(tái) 里都映射為一個(gè) Platform 實(shí)例：Telegram 用 bot token 和 chat_id，WhatsApp 用 WhatsApp Business API 憑據(jù)，Discord 用 bot token 和 channel ID。任務(wù)腳本里調(diào)用 oc.send_message()，底層自動(dòng)路由到對應(yīng)平臺(tái)，不用寫三套發(fā)送邏輯。

模型即插即用，不綁定供應(yīng)商

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

安裝步驟

前提條件

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

安裝流程

1. 確認(rèn) Python

python --version
# 輸出應(yīng)為 Python 3.7.x 或更高

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

2. 確認(rèn) Git

git --version
# 輸出應(yīng)為 git version 2.30+

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

3. 克隆代碼

git clone https://github.com/your-repo/AI Agent平臺(tái).git

4. 安裝依賴

cd AI Agent平臺(tái)
pip install -r requirements.txt

常見報(bào)錯(cuò)？試試：

• 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. 配置環(huán)境變量

# 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），但環(huán)境變量更直接，啟動(dòng)時(shí)自動(dòng)加載。

快速上手：發(fā)一條 Telegram 消息

1. 配置 Telegram

編輯 config.yaml：

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

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

2. 寫個(gè)任務(wù)腳本

在 tasks/hello_world.py 里：

from ai-agent import AI Agent平臺(tái)

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

if __name__ == "__main__":
    main()

3. 運(yùn)行它

python tasks/hello_world.py

成功的話，目標(biāo) Telegram 群/私聊會(huì)收到消息。失敗？看終端報(bào)錯(cuò)——通常是 config.yaml 字段名寫錯(cuò)、環(huán)境變量沒生效，或網(wǎng)絡(luò)連不上 Telegram API。

4. 加入 AI 生成

改寫 hello_world.py：

from ai-agent import AI Agent平臺(tái)
from ai-agent.models import GPTModel

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

if __name__ == "__main__":
    main()

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

故障排查

消息沒發(fā)出去？

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

ModuleNotFoundError: No module named 'ai-agent'

• 確保你在 AI Agent平臺(tái)/ 目錄下運(yùn)行命令
• 或者 pip install -e . 把項(xiàng)目安裝為可編輯模式

本地模型加載慢或 OOM？

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

下一步

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

資源

• AI Agent平臺(tái) GitHub 倉庫
• AI Agent平臺(tái) 文檔
• Python 官網(wǎng)
• Git 官網(wǎng)