Windows 10部署AI Agent平臺-CN龍蝦v0.8.2本地AI助手完整教程
Windows 10 部署 AI Agent平臺-CN（龍蝦）v0.8.2：從零開始的終極指南
你可能遇到的問題
想在本地跑個自己的 AI 助手，但搜到的教程要么過時、要么漏步驟、要么一跑就報錯？尤其在 Windows 10 上，權(quán)限問題、環(huán)境變量、飛書接口配置……每一步都可能卡你半天。
這篇教程基于 2026 年 3 月發(fā)布的 v0.8.2 版本，手把手帶你走完從安裝到調(diào)試的全過程。讀完之后，你會有一個能在飛書里對話的本地 AI 機器人。
方案概覽
AI Agent平臺-CN（龍蝦）是一個本地化部署的 AI 助手框架，支持接入飛書、釘釘?shù)绕脚_。核心流程：
- 準(zhǔn)備環(huán)境（Python + Docker）
- 安裝 AI Agent平臺-CN
- 獲取飛書機器人憑證
- 配置并啟動服務(wù)
- 用日志和診斷工具排查問題
第一步：準(zhǔn)備環(huán)境
AI Agent平臺-CN 依賴 Python 3.10+ 和 Docker Desktop。Docker 的作用是把數(shù)據(jù)庫、消息隊列這些復(fù)雜組件打包好，省得你自己折騰。
檢查 Python 版本：
python --version輸出應(yīng)該是 Python 3.10.x 或更高。如果沒有，去 python.org 下載安裝，安裝時勾選 "Add Python to PATH"——這一步很多人漏掉，后面命令全找不到。
安裝 Docker Desktop：
去 docker.com 下載安裝，裝完重啟電腦。打開 Docker Desktop，等左下角顯示綠色的 "Engine running"。
驗證 Docker 正常：
docker --version
docker run hello-world看到 "Hello from Docker!" 就說明沒問題。
第二步：安裝 AI Agent平臺-CN
用 pip 安裝龍蝦的命令行工具：
pip install ai-agent-cn==0.8.2指定版本號是因為不同版本的配置格式可能不兼容，鎖定版本能避免"教程能跑但我跑不了"的問題。
安裝完成后驗證：
ai-agent-cn --version應(yīng)該輸出 ai-agent-cn 0.8.2。
然后初始化項目目錄：
mkdir C:\ai-agent
cd C:\ai-agent
ai-agent-cn init這個命令會在當(dāng)前目錄生成 config.yaml、docker-compose.yml 等配置文件。
第三步：獲取飛書 App ID 和 App Secret
這是整個流程中最關(guān)鍵的一步。龍蝦通過飛書機器人接口接收和回復(fù)消息，你需要在飛書開放平臺創(chuàng)建一個應(yīng)用。
操作步驟：
- 打開 飛書開放平臺，登錄你的飛書賬號
- 點擊「創(chuàng)建應(yīng)用」→ 選擇「企業(yè)自建應(yīng)用」
- 填寫應(yīng)用名稱（比如"我的龍蝦助手"），點擊創(chuàng)建
- 在應(yīng)用詳情頁，找到「憑證與基礎(chǔ)信息」，復(fù)制 App ID 和 App Secret
為什么要用自建應(yīng)用而不是機器人模板？ 自建應(yīng)用的權(quán)限更靈活，你可以精確控制它能讀哪些消息、在哪些群里回復(fù)。
配置權(quán)限（必須做）：
在應(yīng)用詳情頁 → 「權(quán)限管理」，搜索并開啟以下權(quán)限：
im:message— 讀取消息im:message:send_as_bot— 以機器人身份發(fā)消息im:chat— 獲取群信息
發(fā)布應(yīng)用：
在「版本管理與發(fā)布」中創(chuàng)建版本并提交審核（企業(yè)內(nèi)部應(yīng)用通常秒過）。審核通過后，機器人才能正常收發(fā)消息。
第四步：配置龍蝦
打開 C:\ai-agent\config.yaml，找到飛書相關(guān)配置段：
feishu:
app_id: "cli_xxxxxxxxxxxxxx" # 替換成你的 App ID
app_secret: "xxxxxxxxxxxxxxxxxxxxxxxx" # 替換成你的 App Secret
encrypt_key: "" # 如果沒設(shè)置加密，留空
verification_token: "" # 同上，留空
安全權(quán)限修復(fù)（v0.8.2 新增）：
Windows 上常見的一個坑是文件權(quán)限問題。龍蝦的配置文件包含密鑰，如果權(quán)限太寬松，啟動時會報錯拒絕讀取。
運行內(nèi)置的權(quán)限修復(fù)命令：
ai-agent-cn doctor --fix這個命令會自動檢測并修復(fù)以下問題：
- 配置文件權(quán)限過寬（修復(fù)為僅當(dāng)前用戶可讀寫）
- Docker 容器端口沖突
- 缺少必要的環(huán)境變量
- Python 依賴版本不匹配
輸出示例：
[?] Config file permissions fixed
[?] Docker port 8080 is available
[!] Missing OPENAI_API_KEY — please set it in config.yaml
[?] Python dependencies OK看到 [!] 的條目需要你手動處理，[?] 的已經(jīng)自動修好了。
第五步：啟動服務(wù)
ai-agent-cn up這個命令會用 Docker Compose 拉取鏡像并啟動所有服務(wù)（數(shù)據(jù)庫、消息隊列、龍蝦核心）。第一次運行需要下載鏡像，可能要等幾分鐘。
啟動成功的標(biāo)志是看到類似這樣的輸出：
[+] Running 4/4
? Container ai-agent-db Started
? Container ai-agent-redis Started
? Container ai-agent-core Started
? Container ai-agent-feishu Started第六步：測試機器人
在飛書中找到你創(chuàng)建的應(yīng)用，給它發(fā)一條消息："你好"。
如果一切正常，幾秒內(nèi)會收到回復(fù)。
遇到問題？用日志和診斷工具
查看實時日志：
ai-agent-cn logs --follow--follow 參數(shù)會持續(xù)輸出最新日志，類似 Linux 的 tail -f。你可以另開一個終端窗口運行這個命令，然后在飛書里發(fā)消息，觀察日志里有沒有報錯。
常見日志錯誤及含義：
| 日志關(guān)鍵詞 | 含義 | 解決方法 |
|---|---|---|
401 Unauthorized | 飛書憑證錯誤 | 檢查 App ID/Secret 是否復(fù)制完整 |
Permission denied | 權(quán)限不足 | 回飛書開放平臺檢查權(quán)限是否全部開啟 |
Connection refused | Docker 容器沒跑起來 | 運行 docker ps 確認容器狀態(tài) |
Rate limit exceeded | API 調(diào)用頻率超限 | 等一分鐘再試，或升級 API 套餐 |
自動診斷：
ai-agent-cn doctor --fix這個命令不只是在首次配置時有用。任何時候遇到問題，都可以先跑一遍。它會檢查 20+ 項常見問題并嘗試自動修復(fù)。
常見問題 FAQ
Q：飛書消息發(fā)出去了，但機器人不回復(fù)？
A：先看日志。八成是權(quán)限沒開全，或者應(yīng)用沒發(fā)布。用 ai-agent-cn logs --follow 看有沒有收到消息的記錄。
Q：Docker 啟動失敗，報端口占用？
A：運行 netstat -ano | findstr :8080 看哪個進程占了端口，關(guān)掉它或者在 docker-compose.yml 里改端口映射。
Q：ai-agent-cn doctor 報 OPENAI_API_KEY 缺失？
A：龍蝦底層調(diào)用大模型需要 API Key。在 config.yaml 的 llm 段填入你的 OpenAI 或兼容 API 的密鑰。
下一步
部署成功只是開始。你可以繼續(xù)探索：
- 接入更多平臺：龍蝦 v0.8.2 已支持釘釘和企業(yè)微信，配置方式類似
- 自定義技能：通過 MCP 協(xié)議給龍蝦接入外部工具（搜索、數(shù)據(jù)庫查詢等）
- 本地模型替換：不想用 OpenAI？試試用 Ollama 跑本地模型，配置教程見 m.nhjb.com.cn - 本地模型接入指南
有疑問歡迎到龍蝦社區(qū)提 issue，或者在飛書里直接問你的龍蝦機器人——它可能比你想象的更聰明。