前置說明

什么是 OpenClaw？

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

安裝環(huán)境

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

第一步：安裝 Xcode  Command Line Tools

為什么需要這一步？

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

操作步驟

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

xcode-select --install

運(yùn)行項(xiàng)目并下載源碼

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

驗(yàn)證安裝

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

git --version

運(yùn)行項(xiàng)目并下載源碼

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

可能遇到的問題

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

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

問題 2：下載速度很慢

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

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

檢查 Node.js 版本

在終端輸入：

node --version

運(yùn)行項(xiàng)目并下載源碼

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

檢查 npm 版本

在終端輸入：

npm --version

運(yùn)行項(xiàng)目并下載源碼

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

如果沒有 Node.js

如果上述命令報(bào)錯(cuò)"command not found"，說明你的 Mac 還沒裝 Node.js。請(qǐng)?jiān)L問 nodejs.org 下載 LTS 版本并安裝。

第三步：安裝 OpenClaw

全局安裝 OpenClaw

在終端輸入以下命令：

sudo npm install -g openclaw@latest

運(yùn)行項(xiàng)目并下載源碼

重要說明：

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

安裝過程

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

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

...

added 655 packages in 2m

運(yùn)行項(xiàng)目并下載源碼

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

驗(yàn)證安裝

在終端輸入：

openclaw --version

運(yùn)行項(xiàng)目并下載源碼

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

常見錯(cuò)誤處理

錯(cuò)誤 1：EACCES: permission denied

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

解決：在命令前加 sudo：

sudo npm install -g openclaw@latest

運(yùn)行項(xiàng)目并下載源碼

錯(cuò)誤 2：xcode-select: note: No developer tools were found

原因：Xcode Command Line Tools 沒裝好。

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

錯(cuò)誤 3：git command not found

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

解決：

xcode-select --install

運(yùn)行項(xiàng)目并下載源碼

第四步：配置 OpenClaw

啟動(dòng)配置向?qū)?/h3>

在終端輸入：

openclaw onboard

運(yùn)行項(xiàng)目并下載源碼

這會(huì)啟動(dòng)一個(gè)交互式配置向?qū)?，按照提示一步步操作即可?/p>

配置流程詳解

1. 安全提示

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

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

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

2. 選擇配置模式

會(huì)提示選擇配置模式：

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

操作：選擇 QuickStart。

3. 配置 AI 模型

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

選項(xiàng)說明：

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

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

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

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

4. 選擇聊天渠道

OpenClaw 支持多種聊天平臺(tái)：

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

本次配置示例（飛書）：

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

5. 配置飛書憑證

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

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

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

配置完成后：

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

6. 選擇飛書域名

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

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

7. 配置群聊策略

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

操作：

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

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

8. 技能配置

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

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

9. Hooks 配置

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

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

10. 安裝 Gateway 服務(wù)

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

系統(tǒng)會(huì)自動(dòng)安裝并啟動(dò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.

運(yùn)行項(xiàng)目并下載源碼

11. 查看狀態(tài)

配置完成后會(huì)顯示：

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

運(yùn)行項(xiàng)目并下載源碼

12. 啟動(dòng) TUI（終端界面）

最后會(huì)提示是否啟動(dòng) TUI（Terminal User Interface）：

操作：選擇 Hatch in TUI (recommended)

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

示例對(duì)話：

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

運(yùn)行項(xiàng)目并下載源碼

按 Ctrl+C 可以退出 TUI。

第五步：配置飛書機(jī)器人

飛書開放平臺(tái)配置

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

參考官方飛書集成教程進(jìn)行配置

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

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

添加機(jī)器人

開通權(quán)限

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

在“導(dǎo)入”頁(yè)簽中，將如下權(quán)限替換原有示例，單擊“下一步，確認(rè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"
    ]
  }
}

點(diǎn)擊申請(qǐng)開通

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

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

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

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

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

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

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

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

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

發(fā)布機(jī)器人

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

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

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

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

配對(duì)機(jī)制說明

OpenClaw 默認(rèn)使用"配對(duì)碼"機(jī)制保護(hù)隱私：

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

批準(zhǔn)配對(duì)

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

openclaw pairing approve feishu <配對(duì)碼>

運(yùn)行項(xiàng)目并下載源碼

示例：

openclaw pairing approve feishu XXXXXXX

運(yùn)行項(xiàng)目并下載源碼

成功后會(huì)顯示：

Approved feishu sender ou_xxxxx.

運(yùn)行項(xiàng)目并下載源碼

測(cè)試對(duì)話

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

你好

運(yùn)行項(xiàng)目并下載源碼

如果機(jī)器人正?；貜?fù)，說明一切配置成功！

常見問題排查

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

可能原因：

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

排查步驟：

檢查 Gateway 狀態(tài)：

openclaw status

運(yùn)行項(xiàng)目并下載源碼

查看日志：

openclaw logs

運(yùn)行項(xiàng)目并下載源碼

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

openclaw config get channels.feishu.groupPolicy

運(yùn)行項(xiàng)目并下載源碼

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

openclaw config set channels.feishu.groupPolicy "open"

運(yùn)行項(xiàng)目并下載源碼

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

如果看到：

plugin feishu: duplicate plugin id detected

運(yùn)行項(xiàng)目并下載源碼

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

openclaw config get plugins.entries

運(yùn)行項(xiàng)目并下載源碼

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

問題 3：Gateway 啟動(dòng)失敗

可能原因：端口被占用

解決方法：

openclaw gateway --force

運(yùn)行項(xiàng)目并下載源碼

這會(huì)強(qiáng)制殺掉占用端口的進(jìn)程并重啟 Gateway。

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

可能原因：

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

排查步驟：

檢查配置：

openclaw config get models

運(yùn)行項(xiàng)目并下載源碼

重新配置模型：

openclaw configure

運(yùn)行項(xiàng)目并下載源碼

問題 5：如何重啟 Gateway

# 停止
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 啟動(dòng)
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

運(yùn)行項(xiàng)目并下載源碼

或者直接：

openclaw gateway --force

運(yùn)行項(xiàng)目并下載源碼

總結(jié)

完整流程回顧

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

關(guān)鍵命令速查

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

進(jìn)階使用

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

相關(guān)資源

• 官方文檔：https://docs.openclaw.ai/
• GitHub 倉(cāng)庫(kù)：https://github.com/openclaw/openclaw
• 飛書開放平臺(tái)：https://open.feishu.cn/

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

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

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

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

最新評(píng)論