前置說明

什么是 OpenClaw？

OpenClaw（前身為 Clawdbot/Moltbot）是一款開源、本地優(yōu)先、可執(zhí)行任務(wù)的 AI 自動化代理引擎，遵循 MIT 協(xié)議。它以自然語言指令為驅(qū)動，在本地或私有云環(huán)境中完成文件操作、流程編排、瀏覽器自動化、多 IM 平臺交互等任務(wù)，實現(xiàn)從 “對話式建議” 到 “自動化執(zhí)行” 的跨越，是面向個人與企業(yè)的自托管式 AI 數(shù)字員工。

安裝環(huán)境

• 操作系統(tǒng)：macOS（本文基于 macOS 11+）
• 前置條件：已安裝 Node.js 和 npm（如果沒有，需要先從 nodejs.org 下載安裝）
• 網(wǎng)絡(luò)要求：需要穩(wěn)定的網(wǎng)絡(luò)連接
• 時間預(yù)估：首次安裝約 15-30 分鐘

第一步：安裝 Xcode  Command Line Tools

為什么需要這一步？

Mac 上的很多開發(fā)工具（包括 git）都依賴 Xcode Command Line Tools。OpenClaw 在安裝過程中需要使用 git 拉取依賴，所以必須先裝好這個工具包。

操作步驟

• 打開"終端"應(yīng)用（在"應(yīng)用程序" → "實用工具"里，或用 Spotlight 搜索"終端"）
• 在終端中輸入以下命令并回車：

xcode-select --install

運行項目并下載源碼

• 系統(tǒng)會彈出一個對話框，點擊"安裝"按鈕
• 等待下載和安裝完成（可能需要 5-15 分鐘，取決于網(wǎng)速）

驗證安裝

安裝完成后，在終端輸入：

git --version

運行項目并下載源碼

如果看到類 似 git version 2.x.x 的輸出，說明安裝成功。

可能遇到的問題

問題 1：提示"Command line tools are already installed"

這說明你的 Mac 已經(jīng)裝過了，可以直接跳到下一步。

問題 2：下載速度很慢

這是正?，F(xiàn)象，耐心等待即可。如果實在太慢，可以嘗試切換網(wǎng)絡(luò)或稍后再試。

第二步：驗證 Node.js  環(huán)境

檢查 Node.js 版本

在終端輸入：

node --version

運行項目并下載源碼

應(yīng)該看到類似 v24.14.0 的輸出（版本號可能不同，但應(yīng)該是 v18 或更高）。

檢查 npm 版本

在終端輸入：

npm --version

運行項目并下載源碼

應(yīng)該看到類似 11.9.0 的輸出。

如果沒有 Node.js

如果上述命令報錯"command not found"，說明你的 Mac 還沒裝 Node.js。請訪問 nodejs.org 下載 LTS 版本并安裝。

第三步：安裝 OpenClaw

全局安裝 OpenClaw

在終端輸入以下命令：

sudo npm install -g openclaw@latest

運行項目并下載源碼

重要說明：

• sudo 會要求你輸入 Mac 的登錄密碼
• 輸入密碼時屏幕不會顯示任何字符（這是正常的安全機制）
• 輸完密碼直接按回車即可

安裝過程

安裝過程可能需要 2-5 分鐘，你會看到：

npm warn deprecated ...（一些過時依賴的警告，可以忽略）

...

added 655 packages in 2m

運行項目并下載源碼

看到 added XXX packages 就說明安裝成功了。

驗證安裝

在終端輸入：

openclaw --version

運行項目并下載源碼

應(yīng)該看到類似 ?? OpenClaw 2026.3.1 (2a8ac97) 的輸出。

常見錯誤處理

錯誤 1：EACCES: permission denied

原因：沒有使用 sudo 導(dǎo)致權(quán)限不足。

解決：在命令前加 sudo：

sudo npm install -g openclaw@latest

運行項目并下載源碼

錯誤 2：xcode-select: note: No developer tools were found

原因：Xcode Command Line Tools 沒裝好。

解決：回到第一步重新安裝。

錯誤 3：git command not found

原因：Xcode Command Line Tools 安裝不完整。

解決：

xcode-select --install

運行項目并下載源碼

第四步：配置 OpenClaw

啟動配置向?qū)?/h3>

在終端輸入：

openclaw onboard

運行項目并下載源碼

這會啟動一個交互式配置向?qū)?，按照提示一步步操作即可?/p>

配置流程詳解

1. 安全提示

首先會看到一段安全警告，大意是：

• OpenClaw 默認是個人使用的工具
• 如果多人共用或開放給陌生人，需要做安全加固
• 建議定期運行 openclaw security audit

操作：選擇 Yes 繼續(xù)。

2. 選擇配置模式

會提示選擇配置模式：

• QuickStart（快速開始）：推薦新手使用
• Custom（自定義）：適合有經(jīng)驗的用戶

操作：選擇 QuickStart。

3. 配置 AI 模型

這一步需要配置 OpenClaw 使用的 AI 后端。

選項說明：

• OpenAI：使用 OpenAI 官方 API（需要 OpenAI API key）
• Anthropic：使用 Claude API（需要 Anthropic API key）
• Custom Provider：使用自定義 API 端點（比如代理服務(wù)）

本次配置示例（使用 MiraclePlus 代理）：

• 選擇 Custom Provider
• 輸入 API Base URL：https://openai-proxy.miracleplus.com
• 選擇如何提供 API Key：Paste API key now
• 輸入你的 API Key（輸入時不會顯示，這是正常的）
• 選擇兼容性：Anthropic-compatible
• 輸入模型 ID：claude-opus-4-6
• 系統(tǒng)會驗證配置，成功后顯示 Verification successful.

提示：如果你使用 OpenAI 官方 API，選擇 OpenAI 并輸入你的 API key 即可。

4. 選擇聊天渠道

OpenClaw 支持多種聊天平臺：

• Telegram：最簡單，只需一個 Bot Token
• WhatsApp：需要獨立手機號
• Discord：需要 Bot Token
• 飛書/Lark：需要企業(yè)應(yīng)用配置
• Slack、Signal、iMessage 等

本次配置示例（飛書）：

• 選擇 Feishu/Lark (飛書)
• 系統(tǒng)會提示安裝飛書插件，選擇 Download from npm (@openclaw/feishu)
• 等待插件下載和安裝完成

5. 配置飛書憑證

系統(tǒng)會提示你需要：

• 訪問飛書開放平臺（open.feishu.cn）
• 創(chuàng)建自建應(yīng)用
• 獲取 App ID 和 App Secret
• 啟用必要權(quán)限
• 發(fā)布應(yīng)用或添加到測試群

詳細步驟見下一章節(jié)。

配置完成后：

• 輸入 Feishu App ID
• 輸入 Feishu App Secret
• 系統(tǒng)會測試連接，成功后顯示 Connected as ou_xxxxx

6. 選擇飛書域名

• Feishu (feishu.cn) - China：國內(nèi)版飛書
• Lark (larksuite.com) - International：國際版 Lark

操作：根據(jù)你的飛書版本選擇（國內(nèi)用戶選第一個）。

7. 配置群聊策略

• Open：所有群都能使用機器人
• Allowlist：只在指定群里響應(yīng)

操作：

• 如果選 Allowlist，需要輸入群 chat_id（可以先留空，后續(xù)再配置）
• 如果選 Open，所有群都能用

建議：個人使用選 Open；公司環(huán)境選 Allowlist 更安全。

8. 技能配置

系統(tǒng)會顯示可用的技能（Skills）數(shù)量。

操作：選擇 No（跳過，后續(xù)可以按需配置）。

9. Hooks 配置

Hooks 可以在特定事件發(fā)生時自動執(zhí)行操作。

操作：選擇 Skip for now（跳過）。

10. 安裝 Gateway 服務(wù)

Gateway 是 OpenClaw 的核心服務(wù)，負責(zé)消息路由和 AI 處理。

系統(tǒng)會自動安裝并啟動 Gateway 服務(wù)：

Installing Gateway service...
Installed LaunchAgent: /Users/xxx/Library/LaunchAgents/ai.openclaw.gateway.plist
Logs: /Users/xxx/.openclaw/logs/gateway.log
Gateway service installed.

運行項目并下載源碼

11. 查看狀態(tài)

配置完成后會顯示：

Feishu: ok
Agents: main (default)
Gateway WS: ws://127.0.0.1:18789
Web UI: http://127.0.0.1:18789/

運行項目并下載源碼

12. 啟動 TUI（終端界面）

最后會提示是否啟動 TUI（Terminal User Interface）：

操作：選擇 Hatch in TUI (recommended)

這會打開一個終端聊天界面，你可以直接和 AI 對話，完成機器人的"初始化"（設(shè)置名字、風(fēng)格等）。

示例對話：

Wake up, my friend!
> 你好
你好！我剛剛啟動?？雌饋磉@是一個全新的工作空間...

運行項目并下載源碼

按 Ctrl+C 可以退出 TUI。

第五步：配置飛書機器人

飛書開放平臺配置

參考資料： https://www.volcengine.com/docs/6396/2189942?lang=zh

參考官方飛書集成教程進行配置

創(chuàng)建飛書機器人

在飛書開發(fā)者平臺創(chuàng)建企業(yè)自建應(yīng)用。

添加機器人

開通權(quán)限

在左側(cè)目錄樹選擇“開發(fā)配置 > 權(quán)限管理”，單擊“批量導(dǎo)入/導(dǎo)出權(quán)限”按鈕。

在“導(dǎo)入”頁簽中，將如下權(quán)限替換原有示例，單擊“下一步，確認新增權(quán)限”按鈕。

{
  "scopes": {
    "tenant": [
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource"
    ],
    "user": [
      "contact:user.employee_id:readonly"
    ]
  }
}

點擊申請開通

可以看到已獲取相應(yīng)權(quán)限

配置事件與回調(diào)

進入創(chuàng)建的飛書應(yīng)用詳情頁，并在左側(cè)目錄樹選擇“開發(fā)配置 > 事件與回調(diào)”。選擇“事件配置”頁簽，單擊“訂閱方式”旁的編輯按鈕。

選擇“使用 長連接 接收事件”，并單擊“保存”按鈕。

在“已添加事件”區(qū)域，單擊“添加事件”按鈕。

在添加事件對話框中，選擇“應(yīng)用身份訂閱”頁簽，并勾選“接收消息”及其它需要訂閱的事件，單擊“確認添加”按鈕。

可以看到當(dāng)前具備了接收消息權(quán)限。

選擇“回調(diào)配置”頁簽，單擊“訂閱方式”旁的編輯按鈕。

選擇“使用 長連接 接收回調(diào)”，并單擊“保存”按鈕。

發(fā)布機器人

復(fù)制這里的APP  ID和App Secret，用于填寫到OpenClaw的飛書集成配置中。

單擊頂部的“創(chuàng)建版本”按鈕，填寫信息，發(fā)布應(yīng)用。

成功發(fā)布修改。將該飛書機器人的APP ID和App Secret，填寫到OpenClaw的飛書集成配置中。

第六步：批準(zhǔn)配對并測試

配對機制說明

OpenClaw 默認使用"配對碼"機制保護隱私：

• 當(dāng)有人第一次給機器人發(fā)消息時，機器人會生成一個配對碼
• 你需要在終端手動批準(zhǔn)這個配對碼
• 批準(zhǔn)后，該用戶才能正常使用機器人

批準(zhǔn)配對

當(dāng)有人（包括你自己）第一次給飛書機器人發(fā)消息時，在終端輸入：

openclaw pairing approve feishu <配對碼>

運行項目并下載源碼

示例：

openclaw pairing approve feishu XXXXXXX

運行項目并下載源碼

成功后會顯示：

Approved feishu sender ou_xxxxx.

運行項目并下載源碼

測試對話

在飛書里給機器人發(fā)送消息，比如：

你好

運行項目并下載源碼

如果機器人正常回復(fù)，說明一切配置成功！

常見問題排查

問題 1：機器人不回復(fù)消息

可能原因：

• Gateway 服務(wù)沒有運行
• 配對沒有批準(zhǔn)
• 群聊策略配置錯誤

排查步驟：

檢查 Gateway 狀態(tài)：

openclaw status

運行項目并下載源碼

查看日志：

openclaw logs

運行項目并下載源碼

如果是群聊不回復(fù)，檢查群聊策略：

openclaw config get channels.feishu.groupPolicy

運行項目并下載源碼

如果是 allowlist 但白名單為空，改為 open：

openclaw config set channels.feishu.groupPolicy "open"

運行項目并下載源碼

問題 2：插件重復(fù)警告

如果看到：

plugin feishu: duplicate plugin id detected

運行項目并下載源碼

這是配置文件中飛書插件被注冊了兩次。雖然不影響使用，但可以清理：

openclaw config get plugins.entries

運行項目并下載源碼

查看配置，手動編輯 ~/.openclaw/openclaw.json 刪除重復(fù)項。

問題 3：Gateway 啟動失敗

可能原因：端口被占用

解決方法：

openclaw gateway --force

運行項目并下載源碼

這會強制殺掉占用端口的進程并重啟 Gateway。

問題 4：API 調(diào)用失敗

可能原因：

• API Key 錯誤
• 網(wǎng)絡(luò)問題
• 模型 ID 錯誤

排查步驟：

檢查配置：

openclaw config get models

運行項目并下載源碼

重新配置模型：

openclaw configure

運行項目并下載源碼

問題 5：如何重啟 Gateway

# 停止
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 啟動
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

運行項目并下載源碼

或者直接：

openclaw gateway --force

運行項目并下載源碼

總結(jié)

完整流程回顧

• ? 安裝 Xcode Command Line Tools
• ? 驗證 Node.js 環(huán)境
• ? 全局安裝 OpenClaw
• ? 運行 openclaw onboard 配置
• ? 配置飛書開放平臺
• ? 批準(zhǔn)配對碼
• ? 測試對話

關(guān)鍵命令速查

# 安裝
sudo npm install -g openclaw@latest
# 配置
openclaw onboard
# 查看狀態(tài)
openclaw status
# 批準(zhǔn)配對
openclaw pairing approve feishu <配對碼>
# 查看日志
openclaw logs
# 重啟 Gateway
openclaw gateway --force
# 配置管理
openclaw config get <key>
openclaw config set <key> <value>

進階使用

• Web 控制面板：訪問 http://127.0.0.1:18789/
• 技能管理：openclaw skills
• 安全審計：openclaw security audit --deep
• 更新 OpenClaw：sudo npm install -g openclaw@latest

相關(guān)資源

• 官方文檔：https://docs.openclaw.ai/
• GitHub 倉庫：https://github.com/openclaw/openclaw
• 飛書開放平臺：https://open.feishu.cn/

附錄：目錄結(jié)構(gòu)

OpenClaw 的配置和數(shù)據(jù)存儲在：

~/.openclaw/
├── openclaw.json          # 主配置文件
├── workspace/             # 工作區(qū)（AI 可訪問的文件）
├── agents/
│   └── main/
│       └── sessions/      # 會話記錄
├── logs/
│   └── gateway.log        # Gateway 日志
└── extensions/
    └── feishu/            # 飛書插件

到此這篇關(guān)于OpenClaw 在 Mac 上的完整安裝指南的文章就介紹到這了,更多相關(guān)OpenClaw安裝完整指南內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論