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