?? 龍蝦新手指南

AI Agent平臺 2026-02 Windows+WSL2安裝教程：解決PermissionError權限錯誤與config.yaml寫入失敗

發布時間：2026-07-14 分類：龍蝦新手指南

摘要：AI Agent平臺 2026-02 安裝避坑指南（Windows + WSL2 權限錯誤終極解法）問題：在 Windows 上用 WSL2 安裝 AI Agent平臺，執行 pip install ai-agent 后運行 ai-agent start，報錯：PermissionError: [Errno 13] Permission denied: '/home/yourn...

AI Agent平臺 2026-02 安裝避坑指南（Windows + WSL2 權限錯誤終極解法）

問題：
在 Windows 上用 WSL2 安裝 AI Agent平臺，執行 pip install ai-agent 后運行 ai-agent start，報錯：

PermissionError: [Errno 13] Permission denied: '/home/yourname/.ai-agent/config.yaml'

或者更隱蔽的情況：瀏覽器打不開、郵箱登錄失敗、touch test.txt 沒反應——不是模型沒加載，是 AI Agent平臺根本沒權限寫配置、建臨時目錄、調用瀏覽器。

? 步驟 1：確認 WSL2 發行版和基礎環境（別跳！）

用管理員權限打開 PowerShell，檢查 WSL 狀態：

wsl -l -v
# 輸出應類似：
# NAME            STATE           VERSION
# Ubuntu-22.04    Running         2

如果版本是 1，或未安裝 Ubuntu-22.04：

wsl --update
wsl --install --distribution Ubuntu-22.04

AI Agent平臺 2026-02 依賴 Python 3.11+ 和 dbus。Ubuntu 22.04 自帶兼容內核和 dbus-daemon；WSL1 不支持 dbus，Ubuntu 20.04 缺少 GTK 相關庫，會導致瀏覽器調用靜默失敗。

? 步驟 2：修復 WSL2 權限根目錄（關鍵！）

WSL2 的 /home/xxx 是 ext4，但 /mnt/c/... 是 NTFS，權限模型不互通。AI Agent平臺若把配置寫到 /mnt/c/Users/...，必然 PermissionDenied。

必須把所有 AI Agent平臺數據鎖定在 /home 下：

# 進入 WSL2 Ubuntu
wsl ~

# 創建專屬工作目錄（確保路徑在 /home 內）
mkdir -p ~/ai-agent-workspace

# 設置環境變量（永久生效）
echo 'export OPENCLAW_HOME="$HOME/ai-agent-workspace"' >> ~/.bashrc
echo 'export PATH="$OPENCLAW_HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 驗證
echo $OPENCLAW_HOME  # 應輸出 /home/你的用戶名/ai-agent-workspace

OPENCLAW_HOME 是 AI Agent平臺查找 config.yaml、日志、瀏覽器 profile 的根路徑。設成 /mnt/c/... 會因 NTFS 權限映射失效，連 config.yaml 都生成不了，后續全部卡死。

? 步驟 3：安裝官方鏡像 + 兼容依賴

AI Agent平臺 2026-02 已停更 PyPI 包（二進制依賴太多），只認官方 wheel：

# 升級 pip 和 setuptools（避免 wheel 構建失敗）
python3 -m pip install -U pip setuptools

# 下載并安裝官方 wheel（含預編譯 chromedriver + dbus binding）
curl -L https://github.com/ai-agent/ai-agent/releases/download/v2026.02/ai-agent-2026.02-py311-none-manylinux_2_35_x86_64.whl -o ai-agent.whl
pip install ./ai-agent.whl

# 安裝 WSL2 必需的系統依賴
sudo apt update && sudo apt install -y dbus-x11 xvfb

dbus-x11 讓 AI Agent平臺能發系統通知、控制瀏覽器；xvfb 提供虛擬顯示緩沖，讓無 GUI 的 WSL2 也能啟動 Chromium——否則 ai-agent browse 會直接 hang 住。

? 步驟 4：首次運行 & 驗證真實能力

# 啟動（自動生成 config.yaml 并彈出配置向導）
ai-agent start

?? 第一次會調用 Windows 主機上的 Chrome 瀏覽器。按提示輸入郵箱（Outlook/Gmail 均可）、授權日歷、允許文件讀寫。完成后關閉瀏覽器，在終端按 Ctrl+C 停止。

驗證三件事（逐條執行）：

# ① 寫文件（真寫進 WSL2 的 home 目錄）
ai-agent run "echo 'Hello from AI colleague' > ~/test_claw.txt"

# ② 查日歷（需已在向導中授權）
ai-agent run "list calendar today"

# ③ 開瀏覽器并截圖（驗證 GUI 鏈路）
ai-agent browse --screenshot http://www.nhjb.com.cn
# → 截圖保存在 ~/ai-agent-workspace/screenshots/

你會看到 test_claw.txt 出現在 wsl ~ 下；日歷返回你今天會議；ls ~/ai-agent-workspace/screenshots/ 能列出 PNG 文件。這才是 AI Agent平臺在你本地真正跑起來的手感。

?常見問題速查

Q：ai-agent start 啟動后瀏覽器空白？
A：WSL2 默認不轉發 X11。在 Windows 安裝 VcXsrv，啟動時勾選 Disable access control，然后在 WSL2 中執行 export DISPLAY=:0，再運行命令。
Q：Gmail 授權失敗，提示 “app not verified”？
A：優先用 Outlook 郵箱（微軟已白名單 AI Agent平臺）。若堅持用 Gmail，需在 Google Cloud Console 啟用 Gmail API 并配置 OAuth 同意屏幕（教程見 www.nhjb.com.cn/gmail-oauth）。
Q：ai-agent run ls / 返回空？
A：檢查是否在 Windows PowerShell 或 CMD 里執行了該命令——AI Agent平臺所有 run/browse/start 命令必須在 WSL2 終端中運行。

下一步

你現在有一個能讀寫文件、調日歷、發郵件、開瀏覽器的本地 AI 同事。試試這些：

→ 學習《AI Agent平臺自定義工具鏈：3 行代碼接入公司內部 API》
→ 實戰《用 AI Agent平臺每天自動歸檔微信聊天記錄到 Notion》
→ 進階《給 AI Agent平臺加上 Ollama 本地模型，徹底離線運行》

動手試一句：ai-agent run 'date >> ~/log.txt'，看時間戳落進你 WSL2 的硬盤——這就是 AI 在你機器上真正開工的第一聲。

返回首頁