OpenClaw 安裝與配置實(shí)戰(zhàn)（含常用命令與故障排查）

這篇筆記整理了我本地安裝和使用 OpenClaw 的流程，重點(diǎn)覆蓋首次上手最容易踩坑的環(huán)節(jié)：通道配置、模型接入、網(wǎng)關(guān)排障。

0. 最短可用路徑（先跑通再優(yōu)化）

# 1) 安裝
curl -fsSL https://openclaw.ai/install.sh | bash
# 2) 啟動(dòng)網(wǎng)關(guān)
openclaw gateway start
# 3) 打開本地控制臺(tái)
# http://127.0.0.1:18789/
# 4) 引導(dǎo)配置模型（按提示輸入 API Key）
openclaw onboard
# 5) 檢查狀態(tài)
openclaw status --all

如果第 5 步顯示異常，直接跳到文末“故障排查”章節(jié)按順序執(zhí)行。

1. 安裝 OpenClaw

官方一鍵安裝：

curl -fsSL https://openclaw.ai/install.sh | bash

官方文檔：
OpenClaw 安裝說明

1.1onboard向?qū)Ыㄗh（來自實(shí)測(cè)經(jīng)驗(yàn)）

首次安裝建議直接走 QuickStart，重點(diǎn)留意下面幾點(diǎn)：

1. Model Provider 選你已經(jīng)開通并拿到 API Key 的平臺(tái)（如 Kimi Code / Moonshot / OpenAI）。
2. 渠道（Channel）可以先跳過，后續(xù)用 openclaw configure 補(bǔ)配。
3. Hooks 建議優(yōu)先啟用常用項(xiàng)：
   • 會(huì)話起始注入項(xiàng)目說明（如 README/Markdown）
   • 操作日志記錄
   • 新會(huì)話前自動(dòng)生成上下文摘要
4. 如果提示已有網(wǎng)關(guān)在運(yùn)行，建議選重啟，避免舊配置殘留。

2. 通道配置（Chat Channels）

國內(nèi)環(huán)境優(yōu)先建議配置飛書（Lark/Feishu）。

先查看命令入口：

openclaw channels --help

2.1 飛書應(yīng)用權(quán)限（示例）

以你實(shí)際業(yè)務(wù)需要為準(zhǔn)，以下為我能跑通的一組權(quán)限參考。

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

2.2 飛書事件訂閱（建議最少集）

在事件配置里添加：

1. im.message.receive_v1（必需）
2. im.message.message_read_v1
3. im.chat.member.bot.added_v1
4. im.chat.member.bot.deleted_v1

2.3 通過插件接入飛書（推薦）

如果當(dāng)前 OpenClaw 環(huán)境沒有內(nèi)置飛書通道，可走插件方案：

openclaw plugins install @m1heng-clawd/feishu
openclaw config set channels.feishu.appId "<你的 App ID>"
openclaw config set channels.feishu.appSecret "<你的 App Secret>"
openclaw config set channels.feishu.enabled true
openclaw gateway restart

飛書開放平臺(tái)入口：
開發(fā)者后臺(tái) - 飛書開放平臺(tái)

說明：

1. 事件訂閱與回調(diào)配置建議使用“長連接”模式（按插件文檔說明）。
2. 修改 appId/appSecret 后務(wù)必重啟網(wǎng)關(guān)，否則新配置可能不生效。

3. 模型配置（重點(diǎn)避坑）

建議先看當(dāng)前模型狀態(tài)：

openclaw models status
openclaw models list

3.1 OpenAI

常見問題：

1. 網(wǎng)絡(luò)環(huán)境受限時(shí)，需要在 OpenClaw 內(nèi)正確配置代理，否則請(qǐng)求容易失敗。
2. OpenAI API 與 ChatGPT Plus 是兩套獨(dú)立計(jì)費(fèi)體系，額度不互通。

3.2 Ollama（本地模型）

本地拉模型后接入，例如先執(zhí)行：

ollama pull <model>

優(yōu)點(diǎn)是本地可控，缺點(diǎn)通常是速度和效果受本機(jī)算力影響較大。

3.3 Kimi / Moonshot（我當(dāng)前更推薦）

可通過引導(dǎo)命令配置：

openclaw onboard --auth-choice moonshot-api-key
openclaw onboard --auth-choice kimi-code-api-key

注意：Moonshot 和 Kimi Coding 是不同提供商，密鑰不互通，端點(diǎn)和模型前綴也不同。

1. Moonshot 模型前綴通常是 moonshot/...
2. Kimi Coding 模型前綴通常是 kimi-coding/...（或平臺(tái)文檔中給出的別名）

4. 高頻命令速查

本地控制臺(tái)地址：
http://127.0.0.1:18789/

# 網(wǎng)關(guān)控制
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
# 模型相關(guān)
openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models fallbacks add <provider/model>
# 終端 UI
openclaw tui
openclaw dashboard
# 配置與更新
openclaw configure
openclaw update
# daemon / hooks（按需）
openclaw daemon install
openclaw daemon uninstall
openclaw hooks list
openclaw hooks enable <name>
openclaw hooks disable <name>

示例：

openclaw models set openai/gpt-4o-mini
openclaw models fallbacks add openai-codex/gpt-5.2-codex

在 TUI 中開新會(huì)話可用：

/new

5. 故障排查（按順序執(zhí)行）

先跑基礎(chǔ)診斷：

openclaw status
openclaw status --all
openclaw gateway probe
openclaw logs --follow
openclaw doctor

若網(wǎng)關(guān)可達(dá)但仍有問題，再做深度探測(cè)：

openclaw status --deep

5.1 常見認(rèn)知誤區(qū)（很重要）

Gateway 和 TUI/Web 不是一回事：

1. Gateway 是后臺(tái)守護(hù)進(jìn)程，負(fù)責(zé)接收并處理 IM 消息，應(yīng)保持運(yùn)行。
2. TUI / Web 只是交互入口，關(guān)閉界面不等于服務(wù)停止。
3. 只要 Gateway 正常，飛書/Slack 等通道依然能工作。

快速自檢：

openclaw status
openclaw logs --follow

如果狀態(tài)頁顯示類似 Gateway service: running 且對(duì)應(yīng)通道 OK，說明主鏈路正常。

6. 建議排障思路

1. 先確認(rèn)網(wǎng)關(guān)是否已啟動(dòng)（gateway start + status）。
2. 再確認(rèn)通道與模型是否健康（status --all + models status）。
3. 觀察實(shí)時(shí)日志定位具體報(bào)錯(cuò)（logs --follow）。
4. 最后跑 doctor，用自動(dòng)化檢查補(bǔ)漏。

7. 版本與命名說明（避免踩文檔坑）

你在社區(qū)文章里可能會(huì)看到 Clawdbot、Moltbot 等舊名稱。當(dāng)前統(tǒng)一按 OpenClaw 理解即可。
命令也優(yōu)先使用 openclaw ... 形式；如果舊文寫的是 clawdbot ...，通常是一一對(duì)應(yīng)的歷史命令寫法。

8. Windows 安裝飛書插件報(bào)錯(cuò)spawn EINVAL（實(shí)測(cè)可用修復(fù)）

適用場(chǎng)景：

1. Windows 11 環(huán)境
2. 執(zhí)行 openclaw plugins install @openclaw/feishu 報(bào)錯(cuò) Error: spawn EINVAL

典型報(bào)錯(cuò)片段（關(guān)鍵字）：

[openclaw] Failed to start CLI: Error: spawn EINVAL
...
at runCommandWithTimeout (.../node_modules/openclaw/dist/exec-*.js:***)
at packNpmSpecToArchive (.../node_modules/openclaw/dist/npm-registry-spec-*.js:***)

8.1 修復(fù)步驟

根據(jù)報(bào)錯(cuò)棧定位到 runCommandWithTimeout 所在文件（例如 openclaw/dist/exec-*.js），將該函數(shù)中的 spawn 調(diào)用改為：

const isWindows = process.platform === "win32";
const child = spawn(resolvedCommand, argv.slice(1), {
  stdio,
  cwd,
  env: resolvedEnv,
  shell: isWindows,
  windowsVerbatimArguments: isWindows ? false : windowsVerbatimArguments,
});

修改后重新執(zhí)行：

openclaw plugins install @openclaw/feishu

8.2 注意事項(xiàng)（建議寫在文中）

1. 這是“臨時(shí)熱修”方案，openclaw 升級(jí)后可能會(huì)覆蓋該改動(dòng)。
2. 每次升級(jí)后若問題復(fù)現(xiàn)，需要重新檢查該文件是否被重置。
3. 建議同時(shí)關(guān)注官方后續(xù)版本修復(fù)，優(yōu)先使用官方正式修復(fù)版本。

9. 參考來源

1. OpenClaw 安裝說明
2. 飛書開放平臺(tái)
3. Windows 環(huán)境插件報(bào)錯(cuò)案例（華為開發(fā)者）

8. 參考來源

1. OpenClaw 安裝使用與通道配置（知乎）
2. OpenClaw 上手與運(yùn)維命令（知乎）
3. 飛書官方內(nèi)容文章（飛書）

到此這篇關(guān)于OpenClaw 安裝與配置實(shí)戰(zhàn)指南(含常用命令 + 故障排查)的文章就介紹到這了,更多相關(guān)OpenClaw 安裝與配置內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論