OpenClaw 完整安装与使用教程：（零基础安装配置 + 渠道接入 + 排错）

OpenClaw 完整使用指南：从 0 到稳定常驻（安装配置 + 渠道接入 + 排错）

• 阅读建议：先跑通“安装 -> 首次接入 -> 第一条任务验证”，再做进阶配置。

目录

• 01｜OpenClaw 是什么：它和普通 AI 聊天工具的区别
• 02｜安装前准备：系统、账号、模型来源
• 03｜20 分钟跑通最小闭环：安装 -> 启动 -> 首次可用
• 04｜渠道接入：飞书 + Telegram 两条可用路线
• 05｜模型配置：先跑通一个 provider，再优化
• 06｜下一步：给 AI 助手一个灵魂（SOUL / USER / AGENTS）
• 07｜Skills 进阶：从会用到会管理
• 08｜常见坑与排错（安装、接入、模型、Skills）

01｜OpenClaw 是什么：它和普通 AI 聊天工具的区别

一句话总结：OpenClaw 是本地优先（local-first）的个人 AI 助手框架。
它不是一个单纯的聊天网页，而是一套可以长期运行的自托管 AI 中枢。

核心形态是：

• 你在自己的设备上运行一个 Gateway，
  把聊天渠道、设备能力和模型统一接入，
  形成可扩展、可持续使用的个人 AI 工作台。

适合这类场景：

• 想把 AI 接入 Telegram / WhatsApp / 飞书等渠道
• 想让 AI 处理一部分重复流程，而不只是问答
• 想把数据和执行环境放在自己可控的设备上

02｜安装前准备：系统、账号、模型来源

先确认基础环境：

• Node.js >= 22
• macOS / Linux / Windows（建议用 WSL2）
• pnpm（仅在从源码构建时需要）

模型来源准备：

OpenClaw 支持多个 provider。先选你当前最稳定可用的一个，后续再扩展。

• OpenAI（API + Codex）[1]
• Anthropic（API + Claude Code CLI）[2]
• Qwen（OAuth）[3]
• OpenRouter[4]
• Vercel AI Gateway[5]
• Moonshot AI（Kimi + Kimi Coding）[6]
• OpenCode Zen[7]
• Amazon Bedrock[8]
• Z.AI[9]
• Xiaomi[10]
• GLM 模型[11]
• MiniMax[12]
• Venice（Venice AI）[13]
• Ollama（本地模型）[14]

渠道准备建议：

• 新手先接一个消息渠道，不要一开始全接
• 本文示例使用飞书（Feishu），流程跑通后再扩展到 Telegram/WhatsApp/Discord

03｜20 分钟跑通最小闭环：安装 -> 启动 -> 首次可用

推荐默认部署方案（大多数用户）：

• 小型 Linux VPS：适合 Gateway 常驻，成本低

参考 VPS 托管[15]

• 专用硬件（Mac mini / Linux 机器）：适合需要本地能力或长期稳定运行
• 混合方案：Gateway 放 VPS，需要本地 UI/浏览器自动化时再连本地节点

参考 节点[16] 和 Gateway 远程[17]

macOS/Linux 安装：

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

Windows 建议先安装 WSL2，详细步骤见 微软 WSL 安装文档[18]。

安装过程的一些截图：

这一步是安全提醒。建议先看一遍官方安全文档，再继续安装流程：
https://docs.openclaw.ai/zh-CN/gateway/security[19]

如果你是新手，建议先选QuickStart ，先把最小闭环跑通。

这一步是选择模型供应商。本文演示使用 OpenAI Codex (ChatGPT OAuth)，后文也会补充自定义baseURL和apiKey的配置方式。

完成 OAuth 认证后选择模型。这里我直接使用Keep current。

这一步是选择消息渠道。本文先演示飞书，所以这里先选 skip for now，等下面渠道章节再完整配置。

这一步会问你用哪个 Node 包管理器安装 Skills。默认npm就可以。其余步骤我先选了Skip/No，后续有需要再在配置文件里补上。

访问127.0.0.1:18789时如果出现报错，可按下面步骤处理：

1. 执行 cat ~/.openclaw/openclaw.json
2. 复制 gateway.auth.token
3. 在/overview > Gateway Access > Gateway Token中粘贴
4. 点击 Connect

完成后页面就能正常连接。

安装常用状态与运维命令：

openclaw status          # 查看整体状态
openclaw gateway status  # 查看 Gateway 运行状态
openclaw health          # 健康检查
openclaw configure       # 重新配置（修改模型、渠道等）
openclaw daemon restart  # 重启后台服务
openclaw daemon logs     # 查看运行日志

验证方法（满足这 3 条即可）：

• openclaw status和openclaw health无关键错误
• Gateway 状态为运行中
• 在目标消息渠道里能收到机器人回复

04｜渠道接入：飞书 + Telegram 两条可用路线

新手路线建议：先接一个渠道。
这里先给飞书流程，再补一条 Telegram 流程。你可以先跑通其中一条，再扩展其他渠道。

1. 打开飞书开放平台

访问 飞书开放平台[20] 并登录。
如果你用的是 Lark（国际版），使用 open.larksuite.com/app[21]。

2. 创建应用

1. 点击“创建企业自建应用”
2. 填写应用名称和描述
3. 选择应用图标

3. 获取应用凭证

在“凭证与基础信息”页面复制：

• App ID（格式类似 cli_xxx）
• App Secret

请妥善保管App Secret，不要外泄。

4. 配置应用权限

在“权限管理”页面，使用“批量导入”导入所需权限：

{
“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: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”
]
}
}

5. 启用机器人能力

在“应用能力 > 机器人”中：

1. 开启机器人能力
2. 配置机器人名称

6. 配置事件订阅

在配置前先确认：

1. 已执行openclaw channels add添加 Feishu 渠道
2. Gateway 已启动（ openclaw gateway status可检查）

然后在“事件订阅”页面：

1. 选择“使用长连接接收事件（WebSocket）”
2. 添加事件 im.message.receive_v1

7. 发布应用（飞书侧）

1. 在“版本管理与发布”里创建版本
2. 提交审核并发布
3. 等待管理员审批

飞书接入后：在 OpenClaw 中配置渠道

通过向导配置（推荐）：

openclaw channels add

选择 Feishu，粘贴App ID和App Secret。

通过配置文件配置（示例）：

{
“channels”:{
“feishu”:{
“enabled”:true,
“dmPolicy”:”pairing”,
“accounts”:{
“main”:{
“appId”:”cli_xxx”,
“appSecret”:”xxx”,
“botName”:”我的AI助手”
}
}
}
}
}

通过环境变量配置（示例）：

export FEISHU_APP_ID=”cli_xxx”
export FEISHU_APP_SECRET=”xxx”

Lark（国际版）域名配置：

{
“channels”:{
“feishu”:{
“domain”:”lark”,
“accounts”:{
“main”:{
“appId”:”cli_xxx”,
“appSecret”:”xxx”
}
}
}
}
}

飞书接入后：启动并测试

启动 Gateway：

openclaw gateway

在飞书里给机器人发一条消息。首次通常会返回配对码，执行：

openclaw pairing approve feishu <配对码>

通过后即可正常对话。

Telegram 渠道接入（飞书流程异常时可先用这条）

1. 通过 @BotFather（直达链接[22]）创建机器人，确认账号无误后复制 Token。
2. 配置 Token：

• 环境变量：TELEGRAM_BOT_TOKEN=…
• 或配置文件：channels.telegram.botToken: “…”
• 如果两者都设置，配置文件优先。

1. 启动 Gateway 网关。
2. 首次私聊机器人会返回配对码，按提示执行配对授权。

最小配置示例：

{
“channels”:{
“telegram”:{
“enabled”:true,
“botToken”:”123:abc”,
“dmPolicy”:”pairing”
}
}
}

然后在 Telegram 里给机器人发消息，拿到配对码后执行：

openclaw pairing approve telegram ABC123

授权成功后，你就可以开始和机器人正常互动。

如果继续对话都能正常返回，说明 Telegram 渠道已经接入成功。

05｜模型配置：先跑通一个 provider，再优化

前面的演示使用的是ChatGPT – OpenAI Codex。

这篇先给最小可用配置。

先看一张模型接入路线图，再按你当前阶段选一条先跑通：

如果你使用中转服务，可参考下面的最小可用配置：

{
“models”:{
“providers”:{
“my-api”:{
“baseUrl”:”https://你的中转地址/v1″,
“apiKey”:”你的-api-key”,
“api”:”openai-completions”,
“models”:[
{
“id”:”模型id”,
“name”:”显示名称”,
“reasoning”:false,
“input”:[“text”],
“contextWindow”:200000,
“maxTokens”:8192
}
]
}
}
},
“agents”:{
“defaults”:{
“model”:{
“primary”:”my-api/模型id”
}
}
},
“gateway”:{
“port”:18789,
“bind”:”loopback”,
“auth”:{
“mode”:”token”,
“token”:”你的-Gateway-Token”
}
}
}

重点只改这几个字段：

• baseUrl：中转服务地址（通常是https://xxx.com/v1）
• apiKey：中转服务分配给你的密钥
• models[].id：中转服务支持的模型 ID
• agents.defaults.model.primary：格式 provider名/模型id
• gateway.auth.token：可用 openclaw configure –section gateway生成

补充两点：

•  providers下的名字（如 my-api）可以自定义，但要和model.primary前缀一致
• 先跑通一个模型再加第二个，排错效率更高

06｜下一步：给 AI 助手一个灵魂（SOUL / USER / AGENTS）

到这里你已经完成了第一阶段：安装、渠道接入、模型配置、首条问答验证。
下一步就是从“能对话”升级到“懂你、会干活、风格一致”。

先看这张三件套关系图，能更直观理解三份文件怎么协同：

这一步的核心是灵魂三件套：

文件	作用	类比
SOUL.md	定义助手性格、语气、行为边界	基因 + 教养
USER.md	定义你是谁、在做什么、偏好什么	简历 + 日记
AGENTS.md	定义执行规范、协作方式、安全规则	员工手册

写好这三个文件后，助手才会从“通用 AI”变成“你的 AI”。
再往后，它就能更稳定地协助你处理邮件、管理日程、总结文件、看代码，逐步进化成桌面端 Jarvis。

6.1 先写 SOUL.md：把性格和边界说清楚

建议按这四块写：

• 性格：直接、务实、主动还是温和、陪伴型
• 说话风格：简洁/详细、是否使用 emoji、术语习惯
• 行为准则：哪些事可以直接做，哪些事必须确认
• 绝对不做：隐私泄露、破坏性操作、越权外发

关键原则：

• 性格要具体，不要写“友好、有帮助”这种空话
• “不做什么”比“做什么”更重要
• 规则不要互相冲突，避免“既要主动又不能打扰”这种矛盾

6.2 再写 USER.md：让助手真正认识你

USER.md最少包含：

• 基本信息：名字、职业、时区
• 当前项目：正在推进的 1-3 个项目
• 工具栈：常用 IDE、文档、设计和协作工具
• 沟通偏好：要简洁还是详细，中英比例，提醒方式
• 当前重点：最近研究内容、近期目标、关键背景

你写得越具体，助手越少反问，越能直接进入执行状态。

6.3 最后调 AGENTS.md：把工作规则固定下来

重点看这三类配置：

• 记忆管理：每次启动读取什么、会话结束记录什么
• 安全边界：读写文件、执行命令、外发消息的确认规则
• 交互规则：群聊发言策略、安静时段、心跳任务触发条件

默认AGENTS.md一般已经可用，先小改，不要一上来大改。

6.4 改完后重启并验证

openclaw daemon restart

然后用同一个问题做 A/B 对比（例如“帮我写一封项目更新邮件”），你会明显看到语气、结构和执行策略变得更贴近你的习惯。

6.5 持续训练，才会越来越像你

灵魂三件套不是一次写完就结束，而是边用边调。
每次你出现“它应该这样做，但它没做到”的瞬间，就是更新SOUL.md/USER.md / AGENTS.md的时机。

你可以把这套方法当成长期工程：先跑通，再稳定，再个性化，最后沉淀成你自己的工作流资产。
如果你也在做这条路线，欢迎关注我，一起交流实战经验。

07｜Skills 进阶：从会用到会管理

如果说 SOUL.md / USER.md /
AGENTS.md  决定了助手“像谁”，那 Skills 决定了助手“会什么”。
OpenClaw 的 Skills 体系兼容 AgentSkills，核心文件是每个技能目录下的SKILL.md 。

官方文档建议先看总索引再按需深入：
https://docs.openclaw.ai/llms.txt[23]

7.1 Skills 从哪里加载，谁优先

OpenClaw 默认从三个位置加载 Skills：

1. 内置 Skills（随安装包发布）
2. ~/.openclaw/skills（本地/托管 Skills）
3. <workspace>/skills（当前工作区 Skills）

同名冲突时优先级是：/skills

<workspace>/skills >~/.openclaw/skills >内置 Skills

另外还能在~/.openclaw/openclaw.json用skills.load.extraDirs加额外目录（最低优先级）。

这张图可以快速记住加载优先级和作用域：

7.2 单智能体和共享 Skills 的区别

多智能体场景下可以这样理解：

• 单智能体专用：放在该智能体工作区的<workspace>/skills
• 全局共享：放在 ~/.openclaw/skills，同机智能体都能用
• 团队共享目录：通过skills.load.extraDirs挂载公共路径

如果你想“不同智能体用不同技能集”，优先用工作区目录；如果想“所有智能体复用一套”，优先用~/.openclaw/skills 。

7.3 安装、更新、同步（ClawHub）

OpenClaw 官方推荐用 ClawHub 管理 Skills：

clawhub install
clawhub update –all
clawhub sync –all

默认会安装到当前目录的./skills（或回退到配置的工作区），下次新会话会自动识别为 <workspace>/skills 。

7.4 find-skills：先装这个“技能搜索器”

find-skills 的定位是帮你发现和安装技能。
README 原话：

This skill helps you discover and install skills from the open agent skills ecosystem.

链接：

• https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md[24]
• https://skills.sh/[25]

常用命令：

npx skills find [query]
npx skills add
npx skills check
npx skills update

无交互安装：

npx skills add <owner/repo@skill> -g -y

7.5 一个合格的 SKILL.md 应该长什么样

最小格式（必须带 YAML frontmatter）：

—
name: your-skill-name
description: What this skill does
—

编写时要注意两点：

• frontmatter 键值尽量保持单行
• metadata 建议写成单行 JSON 对象，避免解析歧义

7.6 门控机制：为什么有的 Skills 看不见

OpenClaw 会基于metadata.openclaw做加载时过滤，常见条件包括：

• requires.bins：依赖的二进制必须在PATH 里
• requires.env：必须有环境变量或配置值
• requires.config：openclaw.json指定路径必须为真值
• os：仅在指定系统加载

这也是很多人“明明装了却没生效”的核心原因。

如果你想从“能看到”走到“能安全用”，先过一遍这张门控与安全流程图：

7.7 配置覆盖与密钥注入

你可以在~/.openclaw/openclaw.json里做 Skills 级配置：

• skills.entries.<name>.enabled：开关技能
• apiKey：给声明了 primaryEnv的技能注入密钥
• env：注入环境变量（仅当进程中不存在时）
• config：该技能的自定义配置

这类注入是“智能体运行期注入”，不是写进你全局 shell。

7.8 安全边界：把第三方 Skills 当不受信任代码

重点建议：

• 先读SKILL.md再启用
• 高风险工具优先放到沙箱里跑
• 不要把密钥写进提示词和日志
• 对外发消息、文件删除、系统命令执行保留确认门槛

7.9 插件也可以发布 Skills

如果你在用插件体系，插件可通过openclaw.plugin.json 声明skills目录来发布技能。
这些插件 Skills 会参与同一套优先级和门控规则，也可以通过 metadata.openclaw.requires.config 做条件启用。

7.10 会话快照与热刷新（为什么改完不立刻生效）

OpenClaw 通常会在会话开始时对可用 Skills 做快照，后续轮次复用该列表。
所以改了 Skills 或配置后，最稳妥的做法是开一个新会话再测。

如果开启了 Skills 监视器（skills.load.watch），SKILL.md 变更会触发刷新，下一轮调用会拿到新列表。

08｜常见坑与排错（安装、接入、模型、Skills）

先看这张排错决策树，按分支一路排查会更快：

1) Node 版本不够

现象：安装或启动时报版本不兼容。
原因：OpenClaw 要求 Node 22+。
修法：升级 Node 后重新执行安装。

2) Dashboard 连不上或提示 token 错误

现象：页面报 token 缺失、请求失败。
原因：访问地址没带 token，或配置里未生成 token。
修法：

cat ~/.openclaw/openclaw.json | grep token
openclaw configure –section gateway

3) 模型配置报错

常见原因：

• API Key 格式不正确
• 模型 ID 写错或缺少 provider 前缀
• 改了环境变量后未重启 Gateway

修法：

openclaw gateway restart

4) 渠道接入后机器人不回消息（以飞书为例）

优先检查：

• Feishu 渠道是否已添加
• Gateway 是否在运行
• 事件订阅是否添加了 im.message.receive_v1
• 是否完成配对授权

最后建议：先保证“单渠道 + 单模型 + 单账号”跑通，再逐步扩展，这样定位问题最快。

5) Skills 安装后看不到或不能调用

优先检查：

• 是否安装到了当前会话对应的工作区目录
• 同名 Skills 是否被更高优先级目录覆盖
•  metadata.openclaw.requires.*条件是否满足（bins/env/config/os）
• 是否在旧会话里测试（Skills 列表通常在会话开始时快照）

排查路径建议：

1. 先确认安装目录<workspace>/skills（ 或~/.openclaw/skills ）
2. 再确认openclaw.json的 skills.entries 开关与配置
3. 最后重开新会话再验证