OpenClaw 安装与配置实战指南(含常用命令 + 故障排查)

2026-03-06 09:31:38 sunz_dragon

OpenClaw 安装与配置实战（含常用命令与故障排查）

这篇笔记整理了我本地安装和使用 OpenClaw 的流程，重点覆盖首次上手最容易踩坑的环节：通道配置、模型接入、网关排障。

0. 最短可用路径（先跑通再优化）

# 1) 安装
curl -fsSL https://openclaw.ai/install.sh | bash
# 2) 启动网关
openclaw gateway start
# 3) 打开本地控制台
# http://127.0.0.1:18789/
# 4) 引导配置模型（按提示输入 API Key）
openclaw onboard
# 5) 检查状态
openclaw status --all

如果第 5 步显示异常，直接跳到文末“故障排查”章节按顺序执行。

1. 安装 OpenClaw

官方一键安装：

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

官方文档：
OpenClaw 安装说明

1.1onboard向导建议（来自实测经验）

首次安装建议直接走 QuickStart，重点留意下面几点：

Model Provider 选你已经开通并拿到 API Key 的平台（如 Kimi Code / Moonshot / OpenAI）。
渠道（Channel）可以先跳过，后续用 openclaw configure 补配。
Hooks 建议优先启用常用项：
- 会话起始注入项目说明（如 README/Markdown）
- 操作日志记录
- 新会话前自动生成上下文摘要
如果提示已有网关在运行，建议选重启，避免旧配置残留。

2. 通道配置（Chat Channels）

国内环境优先建议配置飞书（Lark/Feishu）。

先查看命令入口：

openclaw channels --help

2.1 飞书应用权限（示例）

以你实际业务需要为准，以下为我能跑通的一组权限参考。

{
  "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 飞书事件订阅（建议最少集）

在事件配置里添加：

im.message.receive_v1（必需）
im.message.message_read_v1
im.chat.member.bot.added_v1
im.chat.member.bot.deleted_v1

2.3 通过插件接入飞书（推荐）

如果当前 OpenClaw 环境没有内置飞书通道，可走插件方案：

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

飞书开放平台入口：
开发者后台 - 飞书开放平台

说明：

事件订阅与回调配置建议使用“长连接”模式（按插件文档说明）。
修改 appId/appSecret 后务必重启网关，否则新配置可能不生效。

3. 模型配置（重点避坑）

建议先看当前模型状态：

openclaw models status
openclaw models list

3.1 OpenAI

常见问题：

网络环境受限时，需要在 OpenClaw 内正确配置代理，否则请求容易失败。
OpenAI API 与 ChatGPT Plus 是两套独立计费体系，额度不互通。

3.2 Ollama（本地模型）

本地拉模型后接入，例如先执行：

ollama pull <model>

优点是本地可控，缺点通常是速度和效果受本机算力影响较大。

3.3 Kimi / Moonshot（我当前更推荐）

可通过引导命令配置：

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

注意：Moonshot 和 Kimi Coding 是不同提供商，密钥不互通，端点和模型前缀也不同。

Moonshot 模型前缀通常是 moonshot/...
Kimi Coding 模型前缀通常是 kimi-coding/...（或平台文档中给出的别名）

4. 高频命令速查

本地控制台地址：
http://127.0.0.1:18789/

# 网关控制
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
# 模型相关
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 中开新会话可用：

/new

5. 故障排查（按顺序执行）

先跑基础诊断：

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

若网关可达但仍有问题，再做深度探测：

openclaw status --deep

5.1 常见认知误区（很重要）

Gateway 和 TUI/Web 不是一回事：

Gateway 是后台守护进程，负责接收并处理 IM 消息，应保持运行。
TUI / Web 只是交互入口，关闭界面不等于服务停止。
只要 Gateway 正常，飞书/Slack 等通道依然能工作。

快速自检：

openclaw status
openclaw logs --follow

如果状态页显示类似 Gateway service: running 且对应通道 OK，说明主链路正常。

6. 建议排障思路

先确认网关是否已启动（gateway start + status）。
再确认通道与模型是否健康（status --all + models status）。
观察实时日志定位具体报错（logs --follow）。
最后跑 doctor，用自动化检查补漏。

7. 版本与命名说明（避免踩文档坑）

你在社区文章里可能会看到 Clawdbot、Moltbot 等旧名称。当前统一按 OpenClaw 理解即可。
命令也优先使用 openclaw ... 形式；如果旧文写的是 clawdbot ...，通常是一一对应的历史命令写法。

8. Windows 安装飞书插件报错spawn EINVAL（实测可用修复）

适用场景：

Windows 11 环境
执行 openclaw plugins install @openclaw/feishu 报错 Error: spawn EINVAL

典型报错片段（关键字）：

[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 修复步骤

根据报错栈定位到 runCommandWithTimeout 所在文件（例如 openclaw/dist/exec-*.js），将该函数中的 spawn 调用改为：

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

修改后重新执行：

openclaw plugins install @openclaw/feishu

8.2 注意事项（建议写在文中）

这是“临时热修”方案，openclaw 升级后可能会覆盖该改动。
每次升级后若问题复现，需要重新检查该文件是否被重置。
建议同时关注官方后续版本修复，优先使用官方正式修复版本。

9. 参考来源

8. 参考来源

到此这篇关于OpenClaw 安装与配置实战指南(含常用命令 + 故障排查)的文章就介绍到这了,更多相关OpenClaw 安装与配置内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！