1. 什么是ClawdBot？——你的本地AI助手，不是云端玩具

ClawdBot 是一個(gè)真正屬于你自己的個(gè)人 AI 助手。它不依賴遠(yuǎn)程API、不上傳隱私數(shù)據(jù)、不按調(diào)用次數(shù)收費(fèi)——所有推理都在你自己的設(shè)備上完成。你可以把它理解成“裝在你電腦里的 Siri + Copilot + Notion AI 的混合體”，但更自由、更透明、更可控。

它的核心能力由 vLLM 提供支撐。vLLM 是當(dāng)前最高效的開源大模型推理引擎之一，以極高的吞吐量和極低的顯存占用著稱。ClawdBot 利用它來加載和運(yùn)行像 Qwen3-4B-Instruct 這樣的輕量級(jí)但能力扎實(shí)的模型，讓你在消費(fèi)級(jí)顯卡（甚至帶顯存的筆記本）上也能獲得接近專業(yè)服務(wù)的響應(yīng)速度和對(duì)話質(zhì)量。

和那些動(dòng)輒要填 API Key、綁定手機(jī)號(hào)、看廣告才能用的 Web 應(yīng)用不同，ClawdBot 的哲學(xué)是：“你裝，你用，你改，你擁有。”配置文件是純 JSON，日志清晰可讀，出問題時(shí)你能看到每一行報(bào)錯(cuò)，而不是一句模糊的“服務(wù)暫時(shí)不可用”。

這正是它和 MoltBot 這類工具形成鮮明對(duì)比的地方：MoltBot 是開箱即用的 Telegram 翻譯機(jī)器人，目標(biāo)是“5分鐘上線一個(gè)全能翻譯官”；而 ClawdBot 的目標(biāo)是“5分鐘搭建一個(gè)完全聽你指揮的本地AI大腦”。前者解決的是“我需要什么功能”，后者解決的是“我想怎么用AI”。

所以當(dāng)你遇到 Gateway not reachable 這個(gè)錯(cuò)誤時(shí)，別慌——這不是服務(wù)宕機(jī)，也不是網(wǎng)絡(luò)抽風(fēng)，而是你的本地AI大腦和控制界面之間，那條本該暢通無阻的“神經(jīng)通路”暫時(shí)斷開了。接下來，我們就一條一條地幫你把這條路重新接通。

簡(jiǎn)單來說，ClawdBot 是一個(gè)能替你“動(dòng)手做事”的 AI 智能體（AI Agent）。它就像一位能通過聊天軟件遠(yuǎn)程遙控的“數(shù)字管家”或現(xiàn)實(shí)版的“賈維斯”，只要通過日常的聊天軟件給它發(fā)消息，它就能在你自己的電腦上幫你執(zhí)行各種具體操作。

它是做什么的？

ClawdBot 的核心是“行動(dòng)”。與只能提供建議或生成文本的普通聊天機(jī)器人不同，它能夠直接將你的指令轉(zhuǎn)化為對(duì)電腦的操作，實(shí)現(xiàn)“所想即所得”。例如：

• 文件管理：根據(jù)指令自動(dòng)整理、歸類、重命名文件和文件夾-。
• 信息處理：從多個(gè)文檔中提取特定信息（如郵箱地址），或總結(jié)長(zhǎng)篇內(nèi)容-。
• 郵件與日程：自動(dòng)管理收件箱、發(fā)送郵件、安排日程等。
• 網(wǎng)絡(luò)瀏覽：自主訪問網(wǎng)頁、填寫表單、提取數(shù)據(jù)，甚至可以幫你預(yù)訂餐廳-。
• 軟件與系統(tǒng)控制：操作音樂軟件、編輯筆記、編寫腳本，甚至在 VS Code 里編寫代碼。

?? 它如何運(yùn)作？

ClawdBot 像一個(gè)“超級(jí)大腦”和“萬能手腳”的結(jié)合體：

• “大腦”（Agent & Memory）：它利用大模型（如 Claude、Gemini）進(jìn)行推理，并擁有持久記憶，能記住你過往的偏好，提供個(gè)性化服務(wù)。
• “耳朵與嘴巴”（Gateway）：它通過一個(gè)網(wǎng)關(guān)無縫連接到 WhatsApp、Telegram、Discord 等日常聊天軟件，讓你通過對(duì)話進(jìn)行操控。
• “手腳”（Skills）：這是它真正的執(zhí)行工具。通過社區(qū)貢獻(xiàn)的各種“技能”插件，它能像真人一樣去操作瀏覽器、運(yùn)行腳本或調(diào)用系統(tǒng) API。

2. Gateway not reachable 錯(cuò)誤的本質(zhì)：不是故障，是連接未就緒

在開始排查前，先破除一個(gè)常見誤解：Gateway not reachable: Error: gateway closed (1006 abnormal closure) 這個(gè)報(bào)錯(cuò)不是程序崩潰了，也不是模型掛了。它只是告訴你一件事：ClawdBot 的前端控制臺(tái)（Dashboard）嘗試通過 WebSocket 連接到后端網(wǎng)關(guān)（Gateway）時(shí)失敗了。

你可以把整個(gè)系統(tǒng)想象成一臺(tái)老式收音機(jī)：

• vLLM 推理服務(wù) 是電臺(tái)發(fā)射塔（在后臺(tái)默默運(yùn)行）
• ClawdBot Gateway 是收音機(jī)的調(diào)諧電路（負(fù)責(zé)接收信號(hào)、解碼指令）
• Dashboard 前端界面 是喇叭和旋鈕（你看到和操作的部分）

Gateway not reachable 意味著旋鈕已經(jīng)擰開，但調(diào)諧電路還沒收到發(fā)射塔的信號(hào)——可能是因?yàn)榘l(fā)射塔沒開機(jī)，也可能是中間的天線沒接好，還可能是你調(diào)錯(cuò)了頻率。

這個(gè)錯(cuò)誤通常出現(xiàn)在以下幾種典型場(chǎng)景中：

• 剛啟動(dòng) ClawdBot，vLLM 服務(wù)還在加載模型，網(wǎng)關(guān)尚未完全就緒
• 配置文件里指定了錯(cuò)誤的網(wǎng)關(guān)地址或端口
• vLLM 服務(wù)根本沒運(yùn)行，或者運(yùn)行失敗后自動(dòng)退出
• 網(wǎng)關(guān)進(jìn)程被意外終止，但 Dashboard 還在嘗試重連
• 代理或防火墻攔截了本地回環(huán)（localhost）的 WebSocket 連接

好消息是：所有這些原因，都不需要重裝、不需要?jiǎng)h庫、不需要查源碼。你只需要按順序執(zhí)行幾個(gè)命令，就能定位并修復(fù)。

3. 方法一：確認(rèn) vLLM 服務(wù)是否真正在運(yùn)行（最常被忽略的一步）

這是 70% 的 Gateway not reachable 問題的根源。很多人以為 clawdbot start 一執(zhí)行，所有服務(wù)就自動(dòng)拉起來了，其實(shí)不然。

ClawdBot 本身是一個(gè)控制框架，它不內(nèi)置模型推理能力。它依賴外部的 vLLM 服務(wù)提供“思考”能力。如果你只運(yùn)行了 ClawdBot，但沒啟動(dòng) vLLM，那么網(wǎng)關(guān)就像一個(gè)沒有發(fā)動(dòng)機(jī)的汽車——外觀完整，但無法啟動(dòng)。

如何驗(yàn)證？

打開終端，執(zhí)行：

ps aux | grep vllm

如果輸出中沒有任何包含 vllm_entrypoint.py 或 python -m vllm.entrypoints.api_server 的進(jìn)程，說明 vLLM 根本沒在跑。

如何啟動(dòng)？

根據(jù)你的部署方式選擇：

如果你用 Docker Compose（推薦）： 確保 docker-compose.yml 中已正確定義 vLLM 服務(wù)，然后運(yùn)行：

docker-compose up -d vllm

如果你手動(dòng)啟動(dòng) vLLM：

# 進(jìn)入你的 vLLM 項(xiàng)目目錄（例如 ~/vllm）
cd ~/vllm
# 啟動(dòng) API 服務(wù)，監(jiān)聽本地 8000 端口（必須和 clawdbot.json 中 baseUrl 一致）
python -m vllm.entrypoints.api_server \
  --model Qwen3-4B-Instruct-2507 \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.9

關(guān)鍵檢查點(diǎn)：

• --port 8000 必須和 clawdbot.json 中 "baseUrl": "http://localhost:8000/v1" 的端口號(hào)完全一致
• 啟動(dòng)后，訪問 http://localhost:8000/docs 應(yīng)該能看到 OpenAPI 文檔頁面
• 終端日志中出現(xiàn) INFO: Application startup complete. 即表示服務(wù)已就緒

等 vLLM 完全啟動(dòng)（首次加載模型可能需要 1–2 分鐘），再執(zhí)行 clawdbot dashboard，錯(cuò)誤通常會(huì)立即消失。

4. 方法二：校驗(yàn)配置文件中的網(wǎng)關(guān)地址與端口（小數(shù)點(diǎn)錯(cuò)一位，全盤皆輸）

ClawdBot 的網(wǎng)關(guān)（Gateway）和 vLLM 服務(wù)是兩個(gè)獨(dú)立進(jìn)程，它們之間的通信靠配置文件 clawdbot.json 中的 models.providers.vllm.baseUrl 字段指定。這個(gè)字段寫錯(cuò)一個(gè)字符，就會(huì)導(dǎo)致“雞同鴨講”。

常見錯(cuò)誤類型：

如何快速修正？

打開配置文件：

nano ~/.clawdbot/clawdbot.json
# 或者你映射到容器內(nèi)的路徑：/app/clawdbot.json

找到 models.providers.vllm.baseUrl 這一行，嚴(yán)格對(duì)照以下格式修改：

"baseUrl": "http://localhost:8000/v1"

保存后，必須重啟 ClawdBot 網(wǎng)關(guān)（不是只改配置就完事）：

# 先停止
clawdbot stop
# 再啟動(dòng)（會(huì)重新讀取配置）
clawdbot start

注意：ClawdBot 不支持熱重載配置。改完 JSON 文件后不重啟，等于沒改。

5. 方法三：檢查網(wǎng)關(guān)進(jìn)程狀態(tài)并強(qiáng)制重啟（當(dāng)“假死”發(fā)生時(shí)）

有時(shí)候，vLLM 服務(wù)明明在運(yùn)行，但 ClawdBot 的網(wǎng)關(guān)進(jìn)程自己卡住了，表現(xiàn)為：

• clawdbot dashboard 能打開頁面，但一直轉(zhuǎn)圈
• clawdbot models list 命令卡住或報(bào)超時(shí)
• 終端里看不到網(wǎng)關(guān)相關(guān)的日志輸出

這就是典型的“網(wǎng)關(guān)假死”——進(jìn)程還在，但內(nèi)部連接已中斷。

三步診斷法：

查看網(wǎng)關(guān)是否在運(yùn)行：

ps aux | grep clawdbot | grep gateway

如果有類似 clawdbot-gateway --config /app/clawdbot.json 的進(jìn)程，說明它在跑；如果沒有，則跳到第3步。

查看網(wǎng)關(guān)日志（關(guān)鍵！）：

# 查看最近10行錯(cuò)誤日志
journalctl -u clawdbot-gateway.service -n 10 --no-pager 2>/dev/null || echo "No systemd service; check container logs"
# 如果是 Docker 部署，進(jìn)入容器查看
docker exec -it clawdbot-container tail -n 20 /var/log/clawdbot/gateway.log

日志中如果出現(xiàn) Connection refused、timeout、failed to connect to vLLM，就坐實(shí)了是網(wǎng)關(guān)連不上后端。

暴力但有效：殺死并重啟網(wǎng)關(guān)

# 殺死所有 clawdbot 相關(guān)進(jìn)程
pkill -f clawdbot
# 清理殘留鎖文件（重要?。?
rm -f ~/.clawdbot/.gateway.lock
# 重新啟動(dòng)
clawdbot start

這個(gè)方法之所以有效，是因?yàn)?ClawdBot 的網(wǎng)關(guān)在啟動(dòng)時(shí)會(huì)創(chuàng)建一個(gè) .gateway.lock 文件防止重復(fù)啟動(dòng)。如果上次異常退出，鎖文件可能沒被清除，導(dǎo)致新進(jìn)程拒絕啟動(dòng)。手動(dòng)刪除后，就能干凈重啟。

6. 方法四：繞過網(wǎng)關(guān)直連 Dashboard（臨時(shí)應(yīng)急，驗(yàn)證前端是否正常）

當(dāng)你反復(fù)嘗試前三步仍失敗時(shí)，可以跳過網(wǎng)關(guān)，直接讓 Dashboard 連接 vLLM。這能幫你快速判斷：?jiǎn)栴}是出在網(wǎng)關(guān)本身，還是網(wǎng)關(guān)與 vLLM 的連接上。

操作步驟：

臨時(shí)修改配置，讓 Dashboard 直連 vLLM： 編輯 ~/.clawdbot/clawdbot.json，將 models.providers 部分改為：

"models": {
  "mode": "direct",
  "providers": {
    "vllm": {
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": "sk-local",
      "api": "openai-responses"
    }
  }
}

關(guān)鍵變化："mode": "direct" 替代了原來的 "merge"，并移除了 models 數(shù)組（因?yàn)橹边B模式下不需預(yù)注冊(cè)模型ID）

重啟 ClawdBot：

clawdbot stop && clawdbot start

再次訪問 Dashboard：

clawdbot dashboard

如果這次能正常打開，并且 Models → List 能顯示模型列表，那就100%確認(rèn)：問題出在 ClawdBot 自帶的網(wǎng)關(guān)模塊，而非你的環(huán)境或 vLLM 服務(wù)。

此時(shí)你可以：

• 繼續(xù)用直連模式工作（適合開發(fā)調(diào)試）
• 或回到 GitHub 查看 clawdbot-gateway 的 issue，確認(rèn)是否為已知 bug
• 或降級(jí)到上一個(gè)穩(wěn)定版本的 ClawdBot

7. 方法五：檢查本地回環(huán)（localhost）網(wǎng)絡(luò)策略（國內(nèi)用戶高頻雷區(qū)）

在國內(nèi)網(wǎng)絡(luò)環(huán)境下，某些安全軟件、企業(yè)防火墻、甚至 Windows 的 Hyper-V 虛擬交換機(jī)，會(huì)劫持或限制 localhost 的 WebSocket 連接。這會(huì)導(dǎo)致 ws://127.0.0.1:18780 這個(gè)網(wǎng)關(guān)地址無法建立連接，即使所有服務(wù)都正常。

如何驗(yàn)證是否是網(wǎng)絡(luò)策略問題？

執(zhí)行這個(gè)命令，測(cè)試本地 WebSocket 是否可達(dá)：

# 安裝 wscat（輕量級(jí) WebSocket 客戶端）
npm install -g wscat
# 嘗試連接 ClawdBot 網(wǎng)關(guān)（默認(rèn)端口 18780）
wscat -c ws://127.0.0.1:18780

• 如果返回 connected，說明網(wǎng)絡(luò)通暢，問題不在這一層
• 如果卡住幾秒后報(bào) Error: connect ECONNREFUSED 127.0.0.1:18780，說明網(wǎng)關(guān)進(jìn)程沒起來（回到方法一）
• 如果報(bào) Error: read ECONNRESET 或 Error: socket hang up，大概率是網(wǎng)絡(luò)策略攔截

解決方案（三選一）：

• 換用 127.0.0.1 替代 localhost（最簡(jiǎn)單）：
  • 在 clawdbot.json 中，把所有 localhost 改成 127.0.0.1，包括 baseUrl 和網(wǎng)關(guān)綁定地址。
• 關(guān)閉可能干擾的軟件：
  • 臨時(shí)退出騰訊電腦管家、360安全衛(wèi)士、Windows Defender 實(shí)時(shí)防護(hù)，再試。
• 強(qiáng)制指定網(wǎng)關(guān)監(jiān)聽地址（終極方案）：
  • 啟動(dòng) ClawdBot 時(shí)，顯式指定網(wǎng)關(guān)綁定到 127.0.0.1：

clawdbot start --gateway-host 127.0.0.1 --gateway-port 18780

小技巧：國內(nèi)用戶建議在 ~/.bashrc 中添加別名，避免每次輸入長(zhǎng)命令：

echo "alias cbstart='clawdbot start --gateway-host 127.0.0.1 --gateway-port 18780'" >> ~/.bashrc
source ~/.bashrc

8. 總結(jié)：一張表看清5種方法的適用場(chǎng)景與執(zhí)行順序

當(dāng)你再次看到 Gateway not reachable 時(shí)，不要再從頭百度。按下面這張表，30秒內(nèi)定位問題根源：

記住一個(gè)原則：ClawdBot 的設(shè)計(jì)哲學(xué)是“可見、可查、可修”。每一個(gè)錯(cuò)誤背后，都有對(duì)應(yīng)的日志、進(jìn)程和配置項(xiàng)。你不需要成為系統(tǒng)專家，只需要學(xué)會(huì)用 ps、grep、cat 這三個(gè)命令，就能掌控全局。

最后提醒一句：ClawdBot 的價(jià)值，不在于它多酷炫，而在于它把 AI 的控制權(quán)，穩(wěn)穩(wěn)交還到你手中。那個(gè) Gateway not reachable 的報(bào)錯(cuò)，不是障礙，而是系統(tǒng)在對(duì)你說：“嘿，我們之間的連接需要你親手確認(rèn)一下。”

到此這篇關(guān)于ClawdBot解決Gateway not reachable錯(cuò)誤的5種方法(保姆級(jí)教學(xué))的文章就介紹到這了,更多相關(guān)ClawdBot解決Gateway not reachable錯(cuò)誤內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論