通過(guò) Docker 部署 OpenClaw：從零到“懂你”的 AI 助理

引言

OpenClaw 是一個(gè)開源、本地優(yōu)先、可深度定制的 AI 代理。與普通的云端 AI（如 ChatGPT）不同，OpenClaw 擁有持久的本地記憶、對(duì)系統(tǒng)的實(shí)際執(zhí)行權(quán)限，并且可以通過(guò)“技能”無(wú)限擴(kuò)展能力。它真正有可能成為你的“數(shù)字分身”——一個(gè)既懂你、又能幫你操作電腦的智能助理。

我使用的是 MacBook Air M4 芯片，希望通過(guò) Docker 方式部署 OpenClaw，既保證環(huán)境隔離，又便于管理。本文將詳細(xì)記錄我在 M4 Mac 上部署 OpenClaw 的全過(guò)程，包括環(huán)境準(zhǔn)備、安裝步驟、配置技巧、常見(jiàn)的“令牌不匹配”問(wèn)題，以及如何優(yōu)化 CLI 命令避免每次輸入 token。

一、環(huán)境準(zhǔn)備

• 硬件：MacBook Air (M4 芯片，16GB 內(nèi)存，512GB 存儲(chǔ))
• 操作系統(tǒng)：macOS Sequoia 15.3.1
• 軟件：
  • Docker Desktop for Mac（最新版，支持 Apple Silicon）
  • Git（通常 macOS 自帶，可執(zhí)行 git --version 確認(rèn)）
  • （可選）Homebrew，用于安裝一些輔助工具
• 網(wǎng)絡(luò)：由于 Docker 鏡像拉取可能較慢，建議提前配置國(guó)內(nèi)鏡像加速器（見(jiàn)下文）。
• API 密鑰：如果你計(jì)劃使用通義千問(wèn)（Qwen）等模型，需要提前在阿里云百煉平臺(tái)申請(qǐng) API Key，并領(lǐng)取免費(fèi)額度。后續(xù)在配置向?qū)е袝?huì)用到。

二、Docker 環(huán)境配置

2.1 安裝 Docker Desktop

1. 訪問(wèn) Docker 官網(wǎng)，下載 Mac with Apple Chip 版本。
2. 雙擊安裝，將 Docker 拖入 Applications 文件夾。
3. 從 Launchpad 啟動(dòng) Docker，等待頂部菜單欄的鯨魚圖標(biāo)變綠，表示 Docker 引擎已運(yùn)行。

2.2 配置鏡像加速器（推薦）

國(guó)內(nèi)訪問(wèn) Docker Hub 速度較慢，配置鏡像加速可以大幅提升拉取速度。

編輯（或新建）~/.docker/daemon.json，添加以下內(nèi)容：

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

保存后，重啟 Docker：點(diǎn)擊菜單欄 Docker 圖標(biāo) → Restart。

2.3 驗(yàn)證 Docker 與 Docker Compose

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

docker --version
docker compose version

確保兩條命令都能正常輸出版本信息（注意新版 Docker 使用 docker compose 空格，而非舊版的 docker-compose）。

2.4 處理 Rosetta 問(wèn)題（M1/M2/M4 用戶）

安裝過(guò)程中可能會(huì)遇到 Failed to install Rosetta 的報(bào)錯(cuò)，這通常不影響使用。如果擔(dān)心，可以手動(dòng)安裝 Rosetta：

softwareupdate --install-rosetta --agree-to-license

或者在 Docker Desktop 的設(shè)置中勾選 “Use Rosetta for x86/amd64 emulation on Apple Silicon”。

三、克隆 OpenClaw 倉(cāng)庫(kù)

為了保持目錄清晰，我在 ~/Developer 下存放所有開發(fā)項(xiàng)目：

mkdir -p ~/Developer
cd ~/Developer
git clone https://github.com/openclaw/openclaw.git

如果遇到網(wǎng)絡(luò)問(wèn)題（如 RPC failed），可以嘗試：

• 設(shè)置 Git 代理（如果你有代理客戶端）
• 強(qiáng)制 Git 使用 HTTP/1.1：git config --global http.version HTTP/1.1
• 使用鏡像加速克?。?code>git clone https://githubproxy.cc/openclaw/openclaw.git

克隆完成后，進(jìn)入項(xiàng)目目錄：

cd openclaw

四、運(yùn)行安裝腳本

執(zhí)行以下命令啟動(dòng)安裝流程：

sh docker-setup.sh

腳本會(huì)做兩件事：

1. 構(gòu)建 OpenClaw 的 Docker 鏡像（可能需要幾分鐘，取決于網(wǎng)絡(luò)）。
2. 進(jìn)入交互式配置向?qū)В╓izard）。

可能遇到的問(wèn)題：鏡像拉取超時(shí)

如果看到類似 i/o timeout 的錯(cuò)誤，說(shuō)明鏡像拉取失敗。請(qǐng)檢查：

• Docker 鏡像加速器是否配置正確。
• 網(wǎng)絡(luò)是否穩(wěn)定。可以嘗試手動(dòng)拉取基礎(chǔ)鏡像：docker pull node:22-bookworm。

五、配置向?qū)г斀?/h3>

向?qū)?huì)依次詢問(wèn)多個(gè)配置項(xiàng)，以下是關(guān)鍵選擇：

5.1 模型選擇

選擇你希望使用的 AI 模型。我選擇的是 “千問(wèn)”（通義千問(wèn)），因?yàn)樗谥形娜蝿?wù)上表現(xiàn)優(yōu)秀，并且阿里云百煉提供免費(fèi)額度。

接下來(lái)會(huì)要求填寫 API 密鑰。將你在阿里云百煉創(chuàng)建的 API Key 粘貼進(jìn)去。

?? 重要坑點(diǎn)：之后需要手動(dòng)修改配置文件，將模型的 reasoning 參數(shù)設(shè)為 false，否則網(wǎng)關(guān)啟動(dòng)會(huì)失敗。我們會(huì)在第七章詳細(xì)說(shuō)明。

5.2 聊天通道

向?qū)?huì)列出 Telegram、WhatsApp、iMessage 等多種接入方式。由于我們打算通過(guò) Web 界面直接使用，這里選擇 Skip for now。

5.3 技能依賴

同樣選擇 Skip for now。核心聊天功能已經(jīng)可用，技能可以后續(xù)按需安裝。

5.4 Hooks（鉤子）

這里務(wù)必選擇 session-memory！這是開啟長(zhǎng)期記憶的關(guān)鍵，讓 AI 能跨會(huì)話記住你的信息。其他鉤子可根據(jù)需要勾選，我暫時(shí)只選了 session-memory。

5.5 其他可選配置

如 Google Places API 等，可根據(jù)需求填寫或跳過(guò)。

配置完成后，腳本會(huì)啟動(dòng) OpenClaw 網(wǎng)關(guān)服務(wù)，并顯示一些信息，包括訪問(wèn)令牌（Token）、配置目錄等。請(qǐng)務(wù)必保存好這個(gè)令牌，例如：

Token: your_gateway_token

六、網(wǎng)關(guān)啟動(dòng)與配置文件調(diào)整

首次啟動(dòng)后，網(wǎng)關(guān)可能無(wú)法正常運(yùn)行，需要根據(jù)日志調(diào)整配置文件。

6.1 查看網(wǎng)關(guān)狀態(tài)

cd ~/Developer/openclaw
docker compose ps

如果 openclaw-gateway-1 的狀態(tài)是 Restarting，說(shuō)明啟動(dòng)失敗，需要查看日志：

docker compose logs openclaw-gateway

6.2 常見(jiàn)錯(cuò)誤及解決

錯(cuò)誤 1：Control UI 安全限制

日志中出現(xiàn)：

Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins...

原因：網(wǎng)關(guān)檢測(cè)到可能暴露給外部網(wǎng)絡(luò)，要求明確指定允許的來(lái)源。

解決：編輯配置文件 ~/.openclaw/openclaw.json，在 gateway 段添加：

"controlUi": {
  "allowedOrigins": ["http://localhost:18789", "http://127.0.0.1:18789"]
}

錯(cuò)誤 2：綁定地址導(dǎo)致其他容器無(wú)法連接

日志可能沒(méi)有直接報(bào)錯(cuò)，但 CLI 工具（如 devices list）無(wú)法連接網(wǎng)關(guān)，出現(xiàn) gateway closed (1006)。原因是配置中的 "bind": "loopback" 讓網(wǎng)關(guān)只監(jiān)聽(tīng)容器內(nèi)的 127.0.0.1，導(dǎo)致其他容器無(wú)法通過(guò)服務(wù)名訪問(wèn)。

解決：將 bind 改為 local（或直接刪除該行，默認(rèn)即為 local）：

"bind": "local"

錯(cuò)誤 3：令牌不匹配（token mismatch）

這是最常見(jiàn)的認(rèn)證問(wèn)題，表現(xiàn)為：

• Web 界面連接時(shí)提示 unauthorized: gateway token mismatch
• CLI 命令報(bào) gateway token mismatch (set gateway.remote.token to match gateway.auth.token)

根本原因：OpenClaw 需要同時(shí)設(shè)置服務(wù)端令牌（auth.token）和客戶端令牌（remote.token），且兩者必須一致。默認(rèn)配置中可能缺少 remote.token。

解決步驟：

1. 打開 ~/.openclaw/openclaw.json。
2. 找到 gateway 部分，確保存在以下兩個(gè)字段，值相同：

   "auth": {
     "mode": "token",
     "token": "your_gateway_token"
   },
   "remote": {
     "token": "your_gateway_token"
   }

3. 保存文件，重啟網(wǎng)關(guān)：

   docker compose restart openclaw-gateway

為什么需要 remote.token？
OpenClaw 的設(shè)計(jì)將服務(wù)端和客戶端令牌分離，為將來(lái)實(shí)現(xiàn)多客戶端、不同權(quán)限的管理做準(zhǔn)備。當(dāng)前版本只需將兩者設(shè)為相同即可。

6.3 驗(yàn)證千問(wèn)模型的reasoning參數(shù)

在 ~/.openclaw/openclaw.json 中找到 models 部分，確保你添加的千問(wèn)模型配置中 reasoning 為 false：

{
  "id": "qwen3-max-2026-01-23",
  "name": "qwen3-max-2026-01-23",
  "reasoning": false,
  ...
}

如果不設(shè)置，網(wǎng)關(guān)可能無(wú)法正常響應(yīng)。

6.4 重啟網(wǎng)關(guān)并驗(yàn)證

完成上述修改后，重啟網(wǎng)關(guān)：

docker compose down
docker compose up -d

再次查看狀態(tài)，應(yīng)為 Up。

七、CLI 命令的優(yōu)化之路：從oclaw到oclaw-gw

安裝完成后，我們不可避免地需要通過(guò)命令行管理 OpenClaw，例如查看設(shè)備配對(duì)、安裝技能等。OpenClaw 提供了 CLI 工具，但使用起來(lái)有一些“坑”。

7.1 初次嘗試：創(chuàng)建oclaw別名

官方推薦通過(guò) docker compose run --rm openclaw-cli 來(lái)執(zhí)行 CLI 命令。為了方便，我首先在 ~/.zshrc 中創(chuàng)建了別名：

alias oclaw='cd ~/Developer/openclaw && docker compose run --rm openclaw-cli'

然后執(zhí)行 oclaw devices list。但結(jié)果令人沮喪：

[openclaw] CLI failed: Error: gateway closed (1006 abnormal closure (no close frame)): no close reason
Gateway target: ws://127.0.0.1:18789
...

7.2 問(wèn)題分析：網(wǎng)絡(luò)隔離

錯(cuò)誤信息顯示 CLI 容器嘗試連接 ws://127.0.0.1:18789。但在容器內(nèi)部，127.0.0.1 指向的是 CLI 容器自身，而不是運(yùn)行著網(wǎng)關(guān)的另一個(gè)容器。因此網(wǎng)絡(luò)不通，導(dǎo)致連接失敗。

7.3 發(fā)現(xiàn)可靠的替代方案：直接在網(wǎng)關(guān)容器內(nèi)執(zhí)行命令

通過(guò)查看 Docker 容器狀態(tài)，我發(fā)現(xiàn)網(wǎng)關(guān)容器 openclaw-gateway-1 一直正常運(yùn)行。既然 CLI 工具本身也是 Node.js 腳本，為何不直接在網(wǎng)關(guān)容器內(nèi)調(diào)用呢？

測(cè)試命令（成功！）：

docker compose -f ~/Developer/openclaw/docker-compose.yml exec openclaw-gateway node dist/index.js devices list --token "your_gateway_token"

終于看到了正確的輸出（設(shè)備列表為空）。于是我又創(chuàng)建了第二個(gè)別名：

alias oclaw-gw='docker compose -f ~/Developer/openclaw/docker-compose.yml exec openclaw-gateway node dist/index.js'

現(xiàn)在可以用 oclaw-gw devices list --token <token> 來(lái)管理了。

7.4 進(jìn)一步優(yōu)化：告別每次輸入 token

每次都要手動(dòng)輸入 --token 依然繁瑣。我決定將 token 存入文件，并讓 oclaw-gw 自動(dòng)讀取。

步驟：

1. 創(chuàng)建 token 文件并設(shè)置權(quán)限：

   echo "your_gateway_token" > ~/.openclaw/token
   chmod 600 ~/.openclaw/token

2. 將別名改為函數(shù)，從文件讀取 token：

   oclaw-gw() {
     local token_file="$HOME/.openclaw/token"
     if [[ ! -f "$token_file" ]]; then
       echo "Error: Token file not found at $token_file" >&2
       return 1
     fi
     local token=$(cat "$token_file" | tr -d '\n')
     docker compose -f "$HOME/Developer/openclaw/docker-compose.yml" exec openclaw-gateway node dist/index.js "$@" --token "$token"
   }

3. 由于之前已經(jīng)定義了別名 oclaw-gw，需要先刪除別名才能定義同名函數(shù)：

   unalias oclaw-gw   # 移除別名

   然后將上述函數(shù)添加到 ~/.zshrc，替換原來(lái)的別名行。

4. 重新加載配置：

   source ~/.zshrc

現(xiàn)在，一切變得無(wú)比絲滑：

oclaw-gw devices list
oclaw-gw skills list
oclaw-gw health

不再需要手動(dòng)輸入 token，而且命令簡(jiǎn)潔優(yōu)雅。

7.5 為什么不用環(huán)境變量？

我最初嘗試通過(guò)環(huán)境變量 OPENCLAW_GATEWAY 指定網(wǎng)關(guān)地址，但發(fā)現(xiàn) CLI 工具并不讀取該變量（或配置文件優(yōu)先級(jí)更高）。exec 方式直接繞過(guò)了網(wǎng)絡(luò)隔離，是最可靠的。

7.6 給其他用戶的建議

• 如果你的 oclaw 別名（基于 run）能夠正常工作，恭喜你！但多數(shù)用戶會(huì)遇到網(wǎng)絡(luò)問(wèn)題，此時(shí) oclaw-gw 是最佳選擇。
• 將 token 存入文件并創(chuàng)建自動(dòng)附加參數(shù)的函數(shù)，能極大提升使用體驗(yàn)。
• 記得在修改 .zshrc 后執(zhí)行 source ~/.zshrc，并確保沒(méi)有別名與函數(shù)沖突（可用 unalias 解決）。

八、Web 界面連接與最終成功

8.1 訪問(wèn) Web 界面

瀏覽器打開 http://127.0.0.1:18789，你會(huì)看到 OpenClaw 的儀表板概覽頁(yè)。

8.2 首次連接：配對(duì)流程

點(diǎn)擊頁(yè)面上的 “連接” 按鈕，可能會(huì)提示 pairing required，而不是直接要求輸入令牌。這是 OpenClaw 的安全配對(duì)機(jī)制。

此時(shí)需要批準(zhǔn)配對(duì)請(qǐng)求：

在終端查看待處理請(qǐng)求（使用我們剛剛優(yōu)化好的命令）：

oclaw-gw devices list

輸出中會(huì)有一個(gè)請(qǐng)求 ID，例如 0f7ee8dd-a397-4b0c-b4c4-1a88b0e211a0。

批準(zhǔn)該請(qǐng)求：

oclaw-gw devices approve 0f7ee8dd-a397-4b0c-b4c4-1a88b0e211a0

返回瀏覽器，頁(yè)面應(yīng)自動(dòng)連接成功，右上角顯示“已連接”。如果沒(méi)有自動(dòng)刷新，可以手動(dòng)刷新頁(yè)面。

8.3 初次對(duì)話

連接成功后，點(diǎn)擊左側(cè)的 “聊天”，你會(huì)看到一個(gè)對(duì)話界面。AI 會(huì)主動(dòng)打招呼，并詢問(wèn)你的稱呼、希望它扮演的角色等。這正是它開始建立長(zhǎng)期記憶的第一步。

你可以這樣回復(fù)：

• “我叫小明，希望你叫我小助手。”
• “你的風(fēng)格可以幽默一些，表情符號(hào)就用 ?? 吧。”

AI 會(huì)將這些信息存入記憶，后續(xù)對(duì)話中會(huì)記得。

九、體驗(yàn)與進(jìn)階配置

9.1 技能安裝

技能是 OpenClaw 擴(kuò)展功能的“插件”。你可以通過(guò) Web 界面的 “技能” 頁(yè)面瀏覽和安裝，也可以使用 CLI：

oclaw-gw skills install github

9.2 記憶管理

所有記憶都存儲(chǔ)在 ~/.openclaw/memory/ 目錄下，以純文本 Markdown 文件形式存在。你可以直接查看、編輯甚至刪除，完全透明可控。

9.3 多通道接入

如果你希望在其他平臺(tái)（如 Telegram）使用 OpenClaw，可以在 Web 界面的 “頻道” 中配置。需要?jiǎng)?chuàng)建 Bot 并獲取 Token。

十、常見(jiàn)問(wèn)題排錯(cuò)指南

十一、總結(jié)與展望

在 MacBook Air M4 上通過(guò) Docker 部署 OpenClaw 雖然有些曲折，但最終成功后的體驗(yàn)是值得的。OpenClaw 不僅僅是一個(gè)聊天機(jī)器人，它擁有長(zhǎng)期記憶、可執(zhí)行系統(tǒng)操作、可無(wú)限擴(kuò)展技能，真正有望成為你的“數(shù)字助理”。

部署心得

• 耐心是關(guān)鍵：配置文件需要手動(dòng)調(diào)整幾個(gè)關(guān)鍵點(diǎn)，尤其是 remote.token 和 reasoning。
• 善用日志：遇到問(wèn)題先看 docker compose logs，大部分錯(cuò)誤都能在日志中找到線索。
• 安全第一：OpenClaw 擁有較高權(quán)限，建議在備用機(jī)或隔離環(huán)境中使用，避免安裝來(lái)路不明的技能。
• CLI 優(yōu)化：通過(guò) oclaw-gw 函數(shù)和 token 文件，日常管理變得輕松愉快。

未來(lái)可玩性

• 你可以教會(huì) OpenClaw 處理日常事務(wù)，如整理文件、管理項(xiàng)目、發(fā)送郵件。
• 社區(qū)不斷涌現(xiàn)新技能，從控制智能家居到自動(dòng)生成周報(bào)，想象力無(wú)限。
• 結(jié)合 Hooks，你可以定制自己的自動(dòng)化工作流。

致謝

感謝 OpenClaw 開發(fā)團(tuán)隊(duì)的辛勤工作，以及社區(qū)的分享。本文所有步驟均基于 OpenClaw 2026.2.23 版本，未來(lái)版本可能會(huì)有變化，請(qǐng)以官方文檔為準(zhǔn)。

附錄

常用命令速查（基于oclaw-gw）

# 查看設(shè)備配對(duì)請(qǐng)求
oclaw-gw devices list
# 批準(zhǔn)配對(duì)請(qǐng)求
oclaw-gw devices approve <requestId>
# 列出所有技能
oclaw-gw skills list
# 安裝技能
oclaw-gw skills install <skill-name>
# 查看網(wǎng)關(guān)健康狀態(tài)
oclaw-gw health
# 列出所有會(huì)話
oclaw-gw sessions list

配置文件示例（脫敏）

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "local",
    "auth": {
      "mode": "token",
      "token": "your_gateway_token"
    },
    "remote": {
      "token": "your_gateway_token"
    },
    "controlUi": {
      "allowedOrigins": ["http://localhost:18789", "http://127.0.0.1:18789"]
    },
    "tailscale": {
      "mode": "off"
    }
  },
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "your_api_key",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-max-2026-01-23",
            "name": "qwen3-max-2026-01-23",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 262144,
            "maxTokens": 65536
          }
        ]
      }
    }
  }
}

參考鏈接

• OpenClaw 官網(wǎng)：openclaw.ai
• GitHub 倉(cāng)庫(kù)：github.com/openclaw/op…
• 阿里云百煉：bailian.console.aliyun.com
• Docker 鏡像加速器配置：docs.docker.com/registry/re…

希望這篇博客能幫助你在 MacBook Air M4 上順利部署 OpenClaw，并避開我在 CLI 優(yōu)化上踩過(guò)的坑。如果在安裝過(guò)程中還有任何疑問(wèn)，歡迎在評(píng)論區(qū)留言討論。

到此這篇關(guān)于Docker 部署 OpenClaw：從零到“懂你”的 AI 助理的文章就介紹到這了,更多相關(guān)Docker 部署 OpenClaw內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論