AI Agent平臺 全平臺安裝實測：Windows/macOS/Linux/Docker 哪條路最順？

搞 AI 開發，本地跑一個 AI Agent平臺 是很多人的第一步。但網上教程要么只講一個系統，要么踩坑經驗零散。我花了兩天，在四臺機器上把主流安裝路徑全跑了一遍，把每條路的坑和解法整理出來，幫你少走彎路。

先搞清楚：AI Agent平臺 是什么？

AI Agent平臺 是一個開源的 AI Agent 開發框架，你可以把它理解成一個"AI 大腦的骨架"——它幫你處理消息調度、工具調用、記憶管理這些臟活累活，你只需要專注寫業務邏輯。類似 Dify 或 Coze，但更輕量，適合想深入理解 Agent 工作原理的開發者。

環境要求一覽

不管你用什么系統，先確認這幾樣東西：

路徑一：Windows + WSL2（推薦指數：?????）

為什么選 WSL2？ AI Agent平臺 依賴的很多 npm 包在原生 Windows 上有路徑和權限問題，WSL2 提供了一個完整的 Linux 環境，踩坑最少。

步驟 1：開啟 WSL2

打開 PowerShell（管理員），執行：

wsl --install -d Ubuntu-22.04

重啟電腦后，Ubuntu 會自動彈出，設置用戶名和密碼。

為什么要指定 Ubuntu 22.04？ 它的包管理最穩定，社區遇到的問題和解法最多，搜什么都搜得到。

步驟 2：安裝 Node.js

進入 WSL 終端：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

驗證：

node -v   # 應該輸出 v20.x.x
npm -v    # 應該輸出 10.x.x

步驟 3：一鍵安裝 AI Agent平臺

npx ai-agent@latest init my-agent
cd my-agent
npm install

npx ai-agent@latest init 會自動下載最新版腳手架，生成項目目錄。npm install 安裝所有依賴。

步驟 4：啟動并驗證

npm run dev

看到 AI Agent平臺 server running on http://localhost:3000 就成功了。瀏覽器打開這個地址，能看到管理界面。

實測耗時： 約 3 分鐘（不含 WSL 首次安裝）。

常見問題

• EACCES 權限錯誤： 不要用 sudo npm install，改用 nvm 管理 Node 版本，或者執行 sudo chown -R $(whoami) ~/.npm
• WSL 訪問 localhost 失敗： Windows 防火墻可能攔截了，執行 netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=localhost

路徑二：Docker 一鍵部署（推薦指數：?????）

為什么選 Docker？ 環境完全隔離，不污染本機，換機器直接遷移鏡像，團隊協作最省心。

步驟 1：確保 Docker 已安裝

docker --version

沒裝的話，去 docker.com 下載 Docker Desktop。

步驟 2：拉取并運行

docker run -d \
  --name ai-agent \
  -p 3000:3000 \
  -v ai-agent-data:/app/data \
  ai-agent/ai-agent:latest

為什么加 -v ai-agent-data:/app/data？ 這是把數據持久化到 Docker 卷里，容器刪了數據還在。不加這行，你配置的 Agent 和對話記錄全沒了。

步驟 3：驗證

docker logs -f ai-agent

看到 Server ready 字樣，瀏覽器打開 http://localhost:3000。

實測耗時： 約 1 分鐘（前提是 Docker 已裝好）。

常見問題

• 鏡像拉不下來： 配置 Docker 鏡像加速器，編輯 /etc/docker/daemon.json，加入 "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]，然后 sudo systemctl restart docker
• 端口沖突： 改 -p 3001:3000 用其他端口

路徑三：macOS（推薦指數：????）

步驟 1：安裝 Node.js

用 Homebrew 最省事：

brew install node@20

步驟 2：安裝并啟動

npx ai-agent@latest init my-agent
cd my-agent && npm install
npm run dev

關于 Rosetta 2： 如果你用的是 M1/M2/M3 芯片，Node.js 20 已經原生支持 ARM，不需要 Rosetta。只有極少數舊版 npm 包可能需要，遇到報錯時執行 softwareupdate --install-rosetta 即可。

實測耗時： 約 2 分鐘。

常見問題

• xcrun: error: invalid active developer path： 執行 xcode-select --install 安裝命令行工具
• M 芯片兼容問題： 如果某個依賴編譯失敗，試試 arch -x86_64 npx ai-agent@latest init my-agent 強制走 Rosetta

路徑四：Linux + systemd（推薦指數：???）

適合誰？ 想把 AI Agent平臺 當服務長期跑在服務器上的開發者。

步驟 1：安裝 Node.js

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

步驟 2：安裝 AI Agent平臺

sudo mkdir -p /opt/ai-agent
cd /opt/ai-agent
sudo npx ai-agent@latest init .
sudo npm install --production

為什么加 --production？ 只裝運行時依賴，不裝開發工具，鏡像體積小一半，啟動更快。

步驟 3：創建 systemd 服務

sudo tee /etc/systemd/system/ai-agent.service << 'EOF'
[Unit]
Description=AI Agent平臺 Agent Server
After=network.target

[Service]
Type=simple
User=ai-agent
WorkingDirectory=/opt/ai-agent
ExecStart=/usr/bin/node server.js
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

啟動服務：

sudo useradd -r -s /bin/false ai-agent
sudo chown -R ai-agent:ai-agent /opt/ai-agent
sudo systemctl daemon-reload
sudo systemctl enable --now ai-agent

步驟 4：驗證

sudo systemctl status ai-agent
curl http://localhost:3000/health

返回 {"status":"ok"} 就正常了。

實測耗時： 約 5 分鐘（多了 systemd 配置步驟）。

常見問題

• 服務啟動失敗： sudo journalctl -u ai-agent -f 查看實時日志，通常是端口被占或權限問題
• 想更新版本： cd /opt/ai-agent && sudo npm update && sudo systemctl restart ai-agent

四種方案對比

下一步學什么？

裝好 AI Agent平臺 只是開始。建議按這個順序推進：

1. 跑通第一個 Agent： 官方文檔的 Quick Start 帶你寫一個能回答天氣的簡單 Agent
2. 接入工具調用： 學會用 MCP 協議給 Agent 加上搜索、數據庫查詢等能力
3. 部署到生產環境： 配合 Nginx 反向代理 + HTTPS，把你的 Agent 發布到公網

遇到問題，去 AI Agent平臺 GitHub Issues 搜一下，80% 的坑前人都踩過了。