📖 什么是 OpenClaw？

OpenClaw（原 Clawdbot） 是一款开源、自托管的个人 AI 助手，可以在本地计算机上运行，兼容 MacOS、Windows 及 Linux 等多种系统。它支持接入常用聊天工具，除了内置多种 Agent 常用工具外，还可以通过插件和 Skill 扩展更多能力。

提示： 方舟 Coding Plan 支持在 OpenClaw 中使用。需要先访问 方舟 Coding Plan 活动（邀请码：CBDDJGDG），按需订阅套餐后再配置使用编程工具。

⚙️ 核心配置

接入工具的核心参数如下：

模型配置

支持以下两种方式配置模型：

在工具配置文件中指定 Model Name，可实时切换模型。支持配置的 Model Name：

doubao-seed-2.0-code

豆包种子模型 - 代码优化版

doubao-seed-2.0-pro

豆包种子模型 - 专业版

doubao-seed-2.0-lite

豆包种子模型 - 轻量版

doubao-seed-code

豆包种子模型 - 代码版

minimax-m2.5

MiniMax M2.5 模型

glm-4.7

智谱 GLM-4.7 模型

deepseek-v3.2

DeepSeek V3.2 模型

kimi-k2.5

月之暗面 Kimi K2.5 模型

Model Name 不支持配置为 Auto，如需使用，请通过控制台切换该模式。
  1. 在配置文件中指定模型为 ark-code-latest。
  2. 通过开通管理页面选择或切换目标模型，切换模型后 3-5 分钟即可生效。
支持 Auto 模式，通过「效果 + 速度」双维度智能算法自动选择模型。

Base URL

不同的工具配置的 Base URL 根据兼容的协议会有不同：

  • 兼容 Anthropic 接口协议工具：https://ark.cn-beijing.volces.com/api/coding
  • 兼容 OpenAI 接口协议工具：https://ark.cn-beijing.volces.com/api/coding/v3
请勿使用 https://ark.cn-beijing.volces.com/api/v3：该 Base URL 不会消耗您的 Coding Plan 额度，而是会产生额外费用。

API Key

点击获取 API Key

🚀 安装步骤

0 前提条件：安装 Node.js 22 或更新版本。
0.5 配置 npm 国内镜像（推荐）

为了加速下载速度，建议先配置 npm 使用国内镜像源：

方式一：使用淘宝镜像（永久生效）

# 设置淘宝镜像源 npm config set registry https://registry.npmmirror.com # 验证配置 npm config get registry
淘宝镜像（npmmirror）是目前最稳定的国内镜像源，由阿里巴巴维护。

方式二：使用 npmmirror（永久生效）

# 设置 npmmirror 源 npm config set registry https://registry.npmmirror.com # 验证配置 npm config get registry
npmmirror 前身是 cnpm，提供完整的 npm 包同步服务。

查看当前配置的镜像源

npm config get registry

如果显示 https://registry.npmmirror.com，说明已配置成功。

临时使用镜像（单次安装）：

npm install -g openclaw --registry=https://registry.npmmirror.com

1. 安装 OpenClaw

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

Windows PowerShell 环境下安装命令如下：

iwr -useb https://openclaw.ai/install.ps1 | iex

2. 配置 OpenClaw

根据提示信息完成 OpenClaw 配置：

基本配置

提示信息 配置
I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue? 选择 "Yes"
Onboarding mode 选择 "QuickStart"

模型配置

提示信息 配置
Model/auth provider 选择 "Volcano Engine"
How do you want to provide this API key? 选择 "Paste API key now"
Enter Volcano Engine API key 设置 API Key
Default model 选择 Coding Plan 支持的模型（volcengine-plan），本文设置为 "volcengine-plan/ark-code-latest"

功能配置

提示信息 配置
Select channel (QuickStart) 选择 "Skip for now"，后续可以配置
Configure skills now? (recommended) 选择 "No"，后续可以配置
Enable hooks? 按空格键选中选项，按回车键进入下一步
How do you want to hatch your bot? 选择 "Hatch in TUI"

🔧 配置工具

根据操作系统选择合适的方式完成工具配置后，配置文件中会包含 Coding Plan 支持的完整的模型列表，便于快速切换目标模型。

方式一：自动化助手（推荐）

Ark Helper 是一个编码工具助手，支持快速配置选择的工具接入 Coding Plan。安装并运行该助手，根据界面提示操作可自动完成工具配置，降低手动配置的时间成本和出错风险。

  • Ark Helper 仅支持 MacOS、Linux 系统，暂不支持 Windows 系统。
  • 以下配置步骤及截图为 Ark Helper 首次使用指引；非首次使用请按界面提示完成套餐配置和工具配置。
1 安装 Ark Helper
curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/ylwslo-yrh/ljhwZthlaukjlkulzlp/install.sh | sh

安装完成后，执行以下命令查看安装的版本号：

ark-helper --version
2 启动 Ark Helper

在命令行界面输入 ark-helper 命令，启动 Ark Helper。

3 完成套餐配置
  • 选择要配置的套餐：[Volcano] Volcano Engine（国内）
  • 配置 API Key：获取 API Key
  • 选择默认模型
4 完成 OpenClaw 工具配置
  • 选择要配置的编码工具：OpenClaw
  • 选择设置 Volcano 配置到 OpenClaw，配置完成后，选择退出。如果需要重新配置工具，可先选择卸载 OpenClaw 配置，再重新执行配置流程。

方式二：手动配置 - Web UI 方式

1 打开 Web UI
openclaw dashboard
2 修改配置信息

在左侧菜单栏选择配置 - All Settings - Raw，查看并修改配置信息。

  • 如果已经配置过 OpenClaw，请勿直接覆盖原有配置，建议根据提供的配置更新models、agents 和 gateway 节点信息。
  • 需要将 <ARK_API_KEY> 替换为您自己的 API Key。
3 保存并更新配置

配置完成后，先单击右上角 Save 保存，保存完成后单击 Update 更新配置。

方式三：手动配置 - 终端方式

1 打开配置文件
nano ~/.openclaw/openclaw.json
2 修改配置信息

将 <ARK_API_KEY> 替换为您自己的 API Key。

如果已经配置过 OpenClaw，请勿直接覆盖原有配置，建议根据提供的配置更新models、agents 和 gateway 节点信息。
3 重启服务

配置完成后保存文件，并在终端执行以下命令重启服务使更改生效：

openclaw gateway restart

📚 指令手册

安装完成后，继续看 OpenClaw 指令详解

如果你已经完成安装与模型配置，下一步建议阅读完整的指令手册。新页面按 CLI 命令、TUI 斜杠指令、典型使用流程 和 排错方法 做了系统整理，适合作为后续操作的速查页。

4 个 新手必记核心命令
2 层 CLI 与会话斜杠命令体系
6 类 典型流程与排错路径
指令页内容按照当前机器上已安装的 OpenClaw 帮助输出和本地文档整理，适合接在本安装页之后阅读。
打开指令详解页面 直接查看新手四个命令

▶️ 开始使用

Web UI 交互

打开 Web UI，在 Chat 页面进行交互。

openclaw dashboard

TUI 交互

打开 TUI，并查看 Gateway 状态。

openclaw tui /status

🔄 切换模型

请根据模型配置方式，选择对应的模型切换方案。

模型配置：Model Name

前提条件：根据配置工具步骤完成文件配置，其中 agents.defaults.models 包含支持的模型列表。

方式一：全局配置（永久有效）

在配置文件中直接修改 agents.defaults.model.primary 为目标模型，修改完成后需要重新启动服务。

{ "agents": { "defaults": { "model": { "primary": "volcengine-plan/doubao-seed-code" } } } }

方式二：在当前会话切换模型（临时有效）

在终端执行 openclaw tui 后，通过 /models 切换模型，当界面返回 "model set to <Model_Name>" 时，表示配置生效。

模型配置：volcengine-plan/ark-code-latest

配置文件中 agents.defaults.model.primary 为 volcengine-plan/ark-code-latest。

模型切换操作：在开通管理页面选择要使用的模型，切换后 3-5 分钟即可生效。

🤖 接入飞书机器人

前置准备：安装并配置 OpenClaw，参见安装步骤、配置工具、开始使用。
飞书插件处于快速迭代阶段，本文使用的插件版本为 2026.3.10，如果实际使用与以下步骤存在差异，可参见 OpenClaw 飞书官网插件。

安装飞书插件

1 执行安装命令
npx -y @larksuite/openclaw-lark-tools install

如果执行命令时报错，可在命令行前增加 sudo 重新执行。

2 新建机器人

根据界面提示信息，选择新建机器人。

3 创建飞书机器人

通过飞书客户端扫描二维码，选择一键创建飞书机器人。

4 验证安装

在飞书中向机器人发送 /feishu start，若返回版本号信息，代表安装成功。

5 开始对话

在飞书中向机器人发送消息，开始对话。

💬 接入 QQ 机器人

前置准备：安装并配置 OpenClaw，参见安装步骤、配置工具、开始使用。

注册 QQ 机器人

访问 QQ 机器人开放平台完成注册：

https://q.qq.com/qqbot/openclaw/login.html

获取凭证

注册成功后，获取以下凭证信息：

凭证名称 说明
AppID 机器人的唯一标识符
AppSecret 机器人密钥，用于身份验证
请妥善保管 AppID 和 AppSecret，不要泄露给他人。

安装 QQ 机器人插件

1 执行安装命令
openclaw plugins install @sliverp/qqbot@latest

等待安装完成。

2 验证安装

执行以下命令查看已安装的插件列表：

openclaw plugins list
如果列表中显示 @sliverp/qqbot，说明插件安装成功。
3 配置 QQ 频道

使用获取的 AppID 和 AppSecret 配置 QQ 机器人：

openclaw channels add --channel qqbot --token "AppID:AppSecret"
请将 AppID 和 AppSecret 替换为您在 QQ 机器人平台获取的实际凭证信息。
4 重启服务

配置完成后，需要重启 OpenClaw 服务使配置生效：

openclaw gateway restart

开始使用

重启服务后，QQ 机器人即可正常工作。您可以在 QQ 频道中与机器人进行对话交互。

提示：如果遇到问题，可以检查 OpenClaw 日志文件查看详细错误信息。

❓ 常见问题

OpenClaw 配置问题

OpenClaw 如何开启深度思考模式？

深度思考模式可以通过修改配置文件中的相关参数来开启。具体配置方法请参考官方文档。

使用 OpenClaw 时，出现不支持 developer role 的报错，如何解决？

这个问题通常是由于模型配置不兼容导致的。请检查您使用的模型是否支持 developer role，或者尝试切换到兼容的模型。

在 OpenClaw 中无法识别图片，如何处理？

请检查配置文件中模型的 input 参数是否包含 "image" 类型。如果未包含，需要更新模型配置。

安装 OpenClaw 时报错 "gateway connect failed: Error: pairing required"，如何处理？

这个错误表示需要进行配对操作。请尝试重新运行 openclaw onboard 命令，按照提示完成配对流程。

配置 OpenClaw 时报错 "run error: 404 The model or endpoint xxx does not exist or you do not have access to it"，如何处理？

请检查：

  • API Key 是否正确且有效
  • 模型名称是否拼写正确
  • 是否有该模型的访问权限
  • Base URL 配置是否正确

QQ 机器人使用问题

如何更新 QQ 机器人插件？

重新执行安装命令即可更新到最新版本：openclaw plugins install @sliverp/qqbot@latest

QQ 机器人无法回复消息怎么办？

请检查：

  • AppID 和 AppSecret 是否正确配置
  • OpenClaw 服务是否正常运行
  • QQ 机器人插件是否已成功安装（执行 openclaw plugins list 查看）
  • 是否已重启服务使配置生效

配置 QQ 频道时提示 token 格式错误？

请确保 token 格式为 AppID:AppSecret，使用冒号连接，中间不要有空格。

飞书插件使用问题

如何更新飞书插件？

重新执行安装命令即可更新到最新版本：npx -y @larksuite/openclaw-lark-tools install

在使用飞书插件时遇到问题，如何操作？

可以查看官方文档或联系 OpenClaw 社区寻求帮助。同时也可以尝试卸载后重新安装插件。

Ark Helper 使用问题

如何升级 Ark Helper？

重新执行安装脚本即可升级：curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/ylwslo-yrh/ljhwZthlaukjlkulzlp/install.sh | sh

如何卸载 Ark Helper？

可以通过删除安装目录或使用包管理器的卸载命令来移除 Ark Helper。