大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



 <p><img alt="" height="444" src="https://i-blog.csdnimg.cn/direct/276a66deac814cdebd65b0ed43473e2c.png" width="831" /></p> 

GPT plus 代充 只需 145

本教程基于官方最新文档、社区博客实战指南优化编写，覆盖从架构理解、环境准备、安装配置、渠道接入到日常使用、安全加固、故障排查的全流程，重点补充国内用户适配方案、新手避坑指南、全场景问题排查，新手跟着步骤走，20 分钟即可跑通最小可用闭环。

如果你只想最快跑通核心流程，直接按以下 4 步操作，无需提前阅读全文，后续可回头补全细节：

1. 一键安装：macOS/Linux/WSL2 终端执行 ；Windows 管理员 PowerShell 执行
2. 初始化配置：执行 ，跟着向导选「本地模式」、配置 AI 模型 API Key、选择 Telegram 渠道、安装后台守护进程
3. 安全配对：给 Telegram 机器人发第一条消息，终端执行 查看配对码，执行 完成授权
4. 测试验证：给机器人发送「你是谁，用 3 句话介绍自己」，收到回复即跑通闭环，可开始正常使用。

1.1 核心定位

OpenClaw 是一款开源自托管的 AI 个人智能体，区别于只能给建议的对话式 AI，它的核心能力是「发一句话，就帮你在本机 / 服务器上真实执行任务」。

• 入口：微信、Telegram、WhatsApp、Discord 等你常用的聊天软件
• 大脑：支持 Claude、GPT、Kimi、智谱 GLM 等云端 API，也支持 Ollama 本地大模型
• 双手：可执行终端命令、读写文件、控制浏览器、管理邮件日历、运行脚本等操作
• 记忆：跨会话保存上下文与配置，越用越贴合你的使用习惯

1.2 核心架构全景（新手必看，少走 90% 弯路）

一次完整的指令执行，会经过以下核心组件，理解每个组件的作用，出问题可快速定位故障点：

plaintext

讯享网

关键名词解释

1.3 新手使用的正确心态

1. 先跑通「发指令→真执行→回结果」的最小闭环，不要一上来就追求全自动化人生
2. 把它当成「会犯错的实习生」，先给最小权限，验证稳定后再逐步开放
3. 先只接入一个你明天就会用的能力（比如清邮件、整理日程），跑稳了再扩展其他功能

2.1 系统与硬性要求

2.2 必备依赖安装（分平台手把手）

核心必装：Node.js（必须≥22.0 版本，否则必报错）

推荐使用 nvm 安装，可灵活切换版本，避免权限问题：

bash

运行

Windows 原生系统：直接前往Node.js 官网下载 22.x LTS 版本，按向导安装后，在 PowerShell 执行验证。

可选依赖

• Git：源码安装时必备，macOS/Linux 执行（macOS）/（Linux）即可安装
• pnpm：源码构建推荐使用，执行即可安装
• Chrome/Chromium：浏览器自动化工具必备，后续使用时安装即可

WSL2 完整安装教程（Windows 用户必看）

1. 以管理员身份打开 PowerShell，执行以下命令开启 WSL2 功能

   powershell

   讯享网

2. 重启电脑，再次以管理员身份打开 PowerShell，设置 WSL2 为默认版本

   powershell

3. 打开 Microsoft Store，搜索「Ubuntu 22.04 LTS」，点击安装，安装完成后启动 Ubuntu，设置用户名和密码
4. 开启 systemd（后台服务必备），在 Ubuntu 终端执行

   bash

   运行

   讯享网

5. 关闭 PowerShell，执行，重新打开 Ubuntu 终端，执行验证 systemd 正常运行
6. 按上文 Node.js 安装步骤，在 Ubuntu 终端内安装 Node.js 22 + 版本

2.3 AI 模型 API Key 准备

OpenClaw 本身不提供大模型能力，需提前准备好模型 API Key，二选一即可：

1. 海外模型：Anthropic Claude（推荐）、OpenAI GPT 系列，需前往对应官网控制台创建按量付费 API Key（禁止使用 Claude Pro/Max 订阅密钥，违反服务条款）
2. 国内模型：Moonshot Kimi、MiniMax、智谱 GLM，国内网络可直连，无需代理，下文有完整接入教程
3. 本地模型：提前安装 Ollama 并下载对应大模型，实现零云端依赖，完全隐私可控

2.4 国内用户网络环境准备

如果使用海外模型，需提前配置系统代理，否则无法调用 API、启动网关：

bash

运行

2.5 30 秒环境自检

安装完依赖后，执行以下命令，全部通过再继续后续步骤：

bash

运行

讯享网

3.1 方式 1：一键脚本安装（新手首选，99% 兼容）

自动安装 Node.js、Python、OpenClaw CLI 及所有依赖，无需手动配置，全程无需干预。

macOS / Linux / WSL2

打开终端，执行以下命令：

bash

运行

Windows 原生系统（不推荐，优先用 WSL2）

以管理员身份打开 PowerShell，执行以下命令：

powershell

讯享网

安装完成后，终端会提示，即安装成功。

3.2 方式 2：NPM/PNPM 手动安装（可控性强）

适合已有 Node.js 环境，想自主控制安装过程的用户：

bash

运行

3.3 方式 3：源码安装（开发者专用，适合二次开发）

适合想调试代码、贡献社区、自定义修改的用户：

bash

运行

讯享网

3.4 安装后必做的验证 & 问题解决

1. 验证安装成功

执行以下命令，能正常输出版本号，即安装成功：

bash

运行

2. 高频问题：安装后提示

这是 npm 全局安装目录不在系统 PATH 中导致的，按以下方案解决：

bash

运行

讯享网

3.5 新手安装避坑指南

1. ❌ 禁止使用 Bun 运行 WhatsApp/Telegram 渠道，官方明确说明 Bun 在这些渠道有已知兼容性问题，必须使用 Node.js
2. ❌ 不要使用低于 22.0 的 Node.js 版本，会出现大量依赖报错、功能异常
3. ❌ Windows 用户不要强行使用原生系统，优先使用 WSL2，可避免 90% 的兼容性问题
4. ❌ 不要在代理未配置好的情况下安装 / 启动，会出现依赖拉取失败、API 调用超时

是官方推荐的配置方式，全程交互式引导，新手跟着选即可，不会出错。

4.1 启动配置向导

打开终端，执行以下命令，启动向导并自动安装后台守护进程（开机自启）：

bash

运行

4.2 每一步配置详解 & 选择建议

以下是向导全步骤的命令行视图与新手选择建议，实际输出可能因版本略有差异，以官方提示为准。

步骤 1：选择配置模式

plaintext

讯享网

• 新手必选（QuickStart），使用官方推荐的默认值，只需要填写核心配置，避免踩坑
• 有自定义需求的用户可选（Advanced），完全自主控制所有配置项

步骤 2：处理现有配置

如果之前安装过 OpenClaw，向导会检测到现有配置，提示：

plaintext

• 首次安装无此步骤
• 想保留之前的配置选，想修改部分配置选，想完全清空重来选

步骤 3：选择 Gateway 运行模式

plaintext

讯享网

• 新手必选（Local），在本机运行网关，所有数据都在本地
• （Remote）仅用于连接远程服务器上已部署的网关，首次安装不要选

步骤 4：选择 AI 模型认证方式（最核心步骤）

向导会先检测环境变量中已有的 API Key，然后列出所有支持的认证方式：

plaintext

• 选择你准备好的模型对应的选项，比如用 Kimi 就选，用 Claude 就选
• 选好后，向导会提示你输入对应的 API Key，粘贴后回车即可，密钥会自动加密保存到文件中
• 输入完成后，向导会让你选择默认模型，新手按推荐选择即可（Claude 选 sonnet，Kimi 选 kimi-k2.5，平衡性能与成本）

步骤 5：Workspace 工作目录配置

plaintext

讯享网

• 新手必选，使用默认工作目录，后续可随时修改
• 自定义路径需确保当前用户有读写权限

步骤 6：Gateway 网关配置

plaintext

• 新手必选，使用默认配置，端口 18789，仅本地可访问，自动生成认证 Token，安全有保障
• 想修改端口、绑定地址的用户可选，禁止新手直接绑定 0.0.0.0，会有严重安全风险

步骤 7：聊天渠道配置

plaintext

讯享网

• 新手优先选（Telegram），配置最简单，稳定性最高，后续可添加其他渠道
• 选择后，向导会提示你输入对应渠道的凭证，比如 Telegram 需要输入 Bot Token，下文有详细的 Bot 创建教程
• 也可以选跳过，后续通过命令补充配置

步骤 8：后台守护进程安装

plaintext

• 必选，安装后台服务，实现开机自启，关闭终端也能正常运行
• 选择后，向导会让你选择运行时，必须选 1（Node），Bun 有兼容性问题，不要选

步骤 9：技能插件安装（可选）

plaintext

讯享网

• 新手选跳过，先跑通基础闭环，再按需安装技能插件
• 有明确需求的用户可选，安装推荐技能，后续需单独配置 OAuth 授权

步骤 10：健康检查 & 配置完成

向导会自动执行健康检查，验证网关、模型 API、渠道是否正常：

• 健康检查通过：会显示配置保存路径、Web 仪表板地址、后续操作步骤，配置完成
• 健康检查失败：向导会提示错误原因和解决方案，比如 API Key 无效、网络不通，按提示修复后重试即可

4.3 非交互模式自动化配置（适合服务器部署）

如果你需要用脚本自动化部署，可使用非交互模式，无需手动选择，示例如下：

bash

运行

注意：非交互模式的参数可能因版本变化，执行查看最新可用参数。

4.4 后续配置修改

如果后续想修改配置，无需重新跑向导，执行以下命令即可进入交互式配置界面，只修改你需要的部分：

bash

运行

讯享网

5.1 Kimi（Moonshot）从零到接入全流程

Kimi 是国内用户首选，网络可直连，无需代理，长上下文能力强，OpenClaw 原生支持。

步骤 1：获取 Kimi API Key

1. 访问Moonshot 开放平台，注册并登录账号
2. 进入控制台 → API Keys，点击「创建 API Key」，设置名称后，复制完整的 Key（格式为）
3. 重要提醒：Moonshot API Key 和 Kimi Coding Key 不通用，不要混用

步骤 2：通过 onboard 向导配置（推荐）

在的认证方式步骤，选择，粘贴你复制的 API Key，向导会自动配置好模型参数，无需手动修改。

步骤 3：手动配置（已完成初始化的用户）

方式 A：通过交互式命令配置

bash

运行

方式 B：直接编辑配置文件编辑文件，添加以下配置：

json

讯享网

保存后，执行重启网关生效。

步骤 4：验证配置是否生效

bash

运行

能正常收到回复，即 Kimi 接入成功。

可用 Kimi 模型列表

模型切换方法

• 临时切换（单次对话）：在聊天中发送
• 永久切换（修改默认模型）：执行，然后重启网关

5.2 其他国内模型配置

MiniMax、智谱 GLM 等国内模型，配置逻辑与 Kimi 一致，在向导中选择对应选项，输入 API Key 即可自动配置，也可参考官方文档手动编辑配置文件。

5.3 本地 Ollama 模型接入教程

实现零云端依赖，完全隐私可控，所有数据均在本地处理：

1. 提前安装 Ollama，执行（比如），确保本地模型正常运行
2. 编辑配置文件，添加以下内容：

   json

   讯享网

3. 保存配置，执行重启网关，执行验证模型连通性。

Gateway 是 OpenClaw 的核心，所有消息、渠道、会话都由它统一管理，必须确保网关正常运行。

6.1 网关的运行方式

6.2 网关启动后的必做验证

执行以下 3 条命令，确认网关完全正常：

bash

运行

6.3 Web 控制界面使用

网关启动后，即可通过浏览器访问可视化控制界面，无需敲命令即可完成所有配置、聊天、管理操作。

1. 本地默认访问地址：http://127.0.0.1:18789/
2. 快速打开命令：终端执行，会自动打开浏览器并跳转到仪表板
3. 核心功能模块：
   • 聊天面板：直接在浏览器中与智能体对话，测试所有能力
   • 渠道管理：可视化添加、配置、管理所有聊天渠道，无需敲命令
   • 会话管理：查看、隔离、重置不同用户的会话上下文
   • 配置管理：可视化修改所有配置项，自动校验格式，避免手动编辑 JSON 出错
   • 技能市场：一键安装、卸载、配置技能插件
   • 节点管理：配对 iOS/Android 移动节点，扩展移动端能力
   • 日志面板：实时查看网关运行日志，快速定位问题

6.4 网关常见配置修改

1. 修改端口

bash

运行

讯享网

2. 修改绑定地址

警告：新手禁止绑定 0.0.0.0，会将网关暴露到公网，有严重安全风险，远程访问请使用 Tailscale 或 SSH 隧道

bash

运行

7.1 渠道接入前置说明

1. 所有渠道接入后，默认开启配对安全策略：陌生用户发消息不会被处理，必须你手动批准配对后才能正常响应，防止机器人被滥用
2. 新手优先接入 Telegram，配置最简单，稳定性最高，跑通后再接入其他渠道
3. 所有渠道的状态，都可以通过命令查看

7.2 Telegram Bot 从零接入全流程

Telegram 是 OpenClaw 适配最完善的渠道，新手首选。

步骤 1：创建 Telegram Bot，获取 Token

1. 打开 Telegram，搜索（带官方蓝标认证），点击进入
2. 发送命令，跟着提示设置机器人名称、用户名（用户名必须以结尾）
3. 创建完成后，BotFather 会给你一条消息，里面包含，后面的一串字符就是 Bot Token（格式类似），复制保存好

步骤 2：接入 OpenClaw

方式 A：onboard 向导配置在初始化向导的渠道步骤，选择，粘贴你复制的 Bot Token，向导会自动完成配置。

方式 B：手动命令配置

bash

运行

讯享网

方式 C：Web 界面配置打开 Web 仪表板 → 渠道管理 → 选择 Telegram → 粘贴 Bot Token → 点击保存，自动完成配置。

步骤 3：安全配对（最关键，否则发消息没反应）

1. 打开 Telegram，搜索你创建的机器人用户名，点击进入，发送第一条消息（比如「你好」）
2. 机器人会自动回复一个 8 位配对码，不会响应其他内容
3. 回到终端，执行以下命令，查看待处理的配对请求：

   bash

   运行

4. 执行以下命令，批准配对（替换为你的配对码）：

   bash

   运行

   讯享网

5. 终端提示，即配对完成，回到 Telegram，重新发送消息，机器人就会正常响应了。

步骤 4：白名单免配对配置（可选）

如果你想让指定用户无需配对，直接使用，可配置白名单：

1. 编辑配置文件
2. 添加以下配置，替换为你的 Telegram 用户 ID（可通过 @userinfobot 获取）：

   json

3. 保存配置，重启网关生效，白名单内的用户无需配对，直接发送消息即可响应。

步骤 5：群聊配置

1. 把机器人邀请到你的 Telegram 群组中，给机器人管理员权限（至少需要发送消息、读取消息权限）
2. 编辑配置文件，添加群聊配置：

   json

   讯享网

3. 保存配置，重启网关生效，群聊中必须 @机器人，才会响应，避免误触发。

7.3 WhatsApp 接入步骤

1. 终端执行以下命令，启动登录流程：

   bash

   运行

2. 终端会生成一个二维码，打开手机 WhatsApp → 设置 → 已关联设备 → 扫描二维码
3. 扫码完成后，终端提示登录成功，重启网关即可生效
4. 首次发送消息，同样需要执行查看配对码，执行批准后，才能正常响应
5. 白名单配置与 Telegram 逻辑一致，在配置文件的中添加允许的手机号（格式为）

7.4 Discord 接入步骤

1. 访问Discord 开发者平台，登录账号，创建新应用
2. 进入应用 → Bot，点击「Add Bot」，然后点击「Reset Token」，复制 Bot Token 保存好
3. 在 Bot 设置页面，开启「Privileged Gateway Intents」下的所有权限（Presence Intent、Server Members Intent、Message Content Intent）
4. 进入 OAuth2 → URL Generator，勾选和，然后在 Bot 权限中勾选发送消息、读取消息、管理消息等基础权限，复制生成的 URL，在浏览器中打开，邀请机器人到你的服务器
5. 回到 OpenClaw，执行，粘贴 Bot Token，重启网关生效
6. 首次私信机器人，同样需要完成配对批准，才能正常响应。

7.5 iMessage 接入（仅 macOS）

1. 先安装 imsg CLI 工具，终端执行：

   bash

   运行

   讯享网

2. 执行，完成配置
3. 给你的 iMessage 账号发送消息，完成配对批准后，即可正常使用。

很多新手一上来就配置大量功能，结果出问题找不到原因，正确的做法是先跑通「发指令→真执行→回结果」的最小闭环，验证全链路通畅。

8.1 第一步：确认链路通畅（基础对话测试）

给你的机器人发送以下消息，能稳定收到回复，说明聊天链路、模型调用完全正常：

1. 「你是谁？用 3 句话介绍你自己」
2. 「你当前有哪些核心能力？用 5 条列出来」

如果没收到回复，直接跳转到第十三章故障排查，按步骤排查问题，不要继续往下走。

8.2 第二步：低风险执行任务测试

选择无风险、不会造成系统损坏的任务，验证智能体的执行能力，推荐以下测试指令，按顺序执行：

1. 「告诉我现在的系统时间」
2. 「列出你当前的工作目录里有哪些文件」
3. 「在工作目录里创建一个 test.txt 文件，写入 “OpenClaw 测试成功”」
4. 「读取 test.txt 文件的内容，返回给我」

能完整执行以上步骤，返回正确结果，说明最小闭环完全跑通，你已经可以正常使用 OpenClaw 的所有能力了。

8.3 官方自检三连（必跑）

每次修改配置、出现异常时，先执行以下 3 条命令，可定位 90% 的问题：

bash

运行

8.4 新手**实践

1. 先只接一个你明天就会用的能力，比如「清邮件」「整理日程」，跑稳了再扩展其他功能，不要一上来就全量配置
2. 指令编写要具体，明确目标、范围、禁止项，避免歧义导致误操作，比如：
   • ❌ 错误指令：「帮我整理文件」
   • ✅ 正确指令：「帮我整理 Downloads 文件夹里的文件，只处理超过 30 天的文件，移动到 Archive 文件夹，不要删除任何文件，移动前先告诉我文件列表，等我确认后再执行」
3. 高风险操作，要求它先复述执行计划，等你确认后再执行，比如在指令末尾加上「在开始之前，先告诉我你的执行计划，等我确认后再执行」
4. 先给最小权限，验证稳定后，再逐步开放更多工具权限。

9.1 基础触发规则

• 私聊场景：直接发送你的需求，无需 @，机器人会直接响应，默认按发送者隔离会话，上下文互不干扰
• 群聊场景：必须按配置 @对应的触发词（比如 @你的机器人名称）+ 需求，才会响应，避免群聊消息误触发

9.2 媒体文件使用

直接在聊天窗口发送图片、音频、文档、压缩包等文件，再补充对应的需求指令即可，支持几乎所有常见格式，示例：

• 发送一张代码截图 + 指令：「帮我识别这张截图里的代码，修复其中的语法错误，解释错误原因，并给出优化后的完整代码」
• 发送一个 PDF 合同 + 指令：「帮我读取这份 PDF 合同，提取核心的付款条款、违约责任、合作期限，整理成清晰的表格」
• 发送一个 Excel 表格 + 指令：「帮我分析这个表格里的销售数据，按月份统计销售额，找出 Top3 的产品，生成数据分析报告」

9.3 高频场景指令示例

9.4 内置工具使用

OpenClaw 内置了 3 个核心工具，无需额外安装即可使用：

1. exec 终端命令工具：可执行系统终端命令，运行脚本，管理进程，是最核心的执行工具
2. browser 浏览器工具：可控制 Chrome/Chromium 浏览器，访问网页、填写表单、抓取数据、截图、自动化操作
3. file 文件管理工具：可读写、创建、删除、移动本地文件，支持几乎所有文件格式的读取与写入

9.5 技能插件安装 & 使用

技能是扩展 OpenClaw 能力的插件，目前有 100 + 预置技能，支持 50 + 第三方服务对接，比如 Gmail、日历、智能家居、音乐平台等。

安装方法

1. Web 界面安装（推荐）：打开仪表板 → 技能市场 → 找到你需要的技能 → 点击「安装」，自动完成安装和基础配置
2. 命令行安装：

   bash

   运行

   讯享网

新手推荐技能

---

10.1 多智能体路由与会话隔离

OpenClaw 支持配置多个独立的 Agent，每个 Agent 使用不同的模型、技能、权限、工作目录，按发送者、渠道自动路由，实现场景隔离。

示例配置：编辑，添加以下内容

json

保存配置，重启网关生效，即可实现：指定用户使用代码专属 Agent，Telegram 渠道使用本地模型 Agent，其他用户使用默认 Agent，上下文、权限、能力完全隔离。

10.2 定时任务自动化配置

OpenClaw 支持配置 Cron 定时任务，实现无人值守自动化执行，比如每天 9 点清邮件、每周五生成数据报告、每天凌晨备份文件等。

配置方法：

1. 编辑配置文件，添加配置项
2. 示例：每天 9 点执行清邮件任务，每周五 18 点生成周报

   json

   讯享网

3. 保存配置，重启网关生效，定时任务会自动按计划执行。

10.3 远程访问安全配置

如果你需要在其他设备访问 OpenClaw，禁止直接暴露公网端口，推荐以下两种安全方案：

方案 1：Tailscale（官方推荐，最简单安全）

1. 在网关设备和访问设备上安装 Tailscale，完成组网
2. 终端执行以下命令，配置网关绑定 Tailscale 网络：

   bash

   运行

3. 组网内的所有设备，都可以通过 Tailscale 分配的 IP+18789 端口，安全访问 Web 仪表板和网关服务。

方案 2：SSH 隧道（无需额外软件）

1. 在本地访问设备上，执行以下命令，建立 SSH 隧道：

   bash

   运行

   讯享网

2. 隧道建立后，本地浏览器访问http://127.0.0.1:18789/，即可安全访问远程服务器上的 OpenClaw 仪表板。

10.4 移动节点配对

OpenClaw 支持配对 iOS 和 Android 移动节点，扩展 Canvas、移动端相机、文件访问等能力，步骤如下：

1. 打开 Web 仪表板，进入「节点管理」菜单
2. 点击「添加移动节点」，生成配对二维码
3. 手机端安装 OpenClaw 移动端应用，打开扫码功能，扫描二维码完成配对
4. 配对完成后，即可在移动端直接管理网关、与智能体对话，调用移动端的相机、文件、Canvas 等能力。

10.5 自定义技能开发入门

你可以自己编写技能插件，扩展 OpenClaw 的能力，甚至让 OpenClaw 帮你生成技能代码：

1. 官方技能开发文档：https://docs.openclaw.ai/tools/skills
2. 基础技能结构：每个技能包含一个入口文件、依赖配置、说明文档
3. 开发完成后，可通过安装，也可发布到社区，供其他用户使用。

---

OpenClaw 拥有你设备的系统权限，一旦配置不当，可能导致数据泄露、系统损坏、API 额度被盗刷，必须做好安全加固。

11.1 最小权限原则 & 沙箱配置详解

OpenClaw 通过三层权限控制：Sandbox 沙箱、Tool Policy 工具策略、Elevated 权限，新手必须先配置沙箱，限制 Agent 的权限范围。

第一步：查看当前生效的权限配置

bash

运行

可查看当前 Agent 的沙箱模式、工作目录权限、工具允许列表、提权状态。

第二步：沙箱模式配置

编辑，添加以下配置，推荐新手使用模式：

json

讯享网

• ：主会话在主机运行，其他会话全部在沙箱中运行，平衡便利性与安全性，新手首选
• ：所有会话全部在沙箱中运行，最高安全性
• ：关闭沙箱，Agent 可直接访问主机系统，仅完全信任时使用
• ：只读权限，：读写权限，新手先设为，验证稳定后再开放
• ：挂载指定目录到沙箱，可设置只读 / 读写权限，避免 Agent 访问无关目录

第三步：工具策略配置（限制可使用的工具）

json

• ：允许使用的工具，新手先只开放，逐步添加
• ：禁止使用的工具，必须禁止、等高风险操作
• 权限逐步开放策略：
  1. 第一阶段：只允许文本处理，仅开放工具，禁用
  2. 第二阶段：允许读取和执行，开放、，禁用、
  3. 第三阶段：允许写入指定目录，通过限制范围
  4. 最后阶段：根据信任度，逐步开放更多权限

11.2 网络安全加固

1. 禁止绑定公网地址：必须确保网关只绑定或，禁止绑定

   bash

   运行

   讯享网

2. 防火墙配置：只允许本地访问网关端口，禁止公网入站访问

   bash

   运行

3. 启用网关 Token 认证：即使是本地访问，也必须启用 Token 认证，防止本地其他进程误连

   bash

   运行

   讯享网

11.3 敏感信息管理规范

1. ❌ 禁止在聊天对话中直接发送 API Key、密码、Token 等敏感信息
2. ❌ 禁止把 API Key、凭证直接写在配置文件的明文里，必须使用环境变量，存放在文件中
3. ❌ 禁止截图时暴露 Token、API Key、配对码
4. ✅ 正确做法：所有敏感信息都通过环境变量配置，文件权限设为 600，仅当前用户可读写

   bash

   运行

5. ✅ 定期轮换 API Key，每月检查一次使用情况，发现异常立即轮换，在模型控制台设置使用额度上限
6. ✅ 配置文件、凭证定期备份，加密存储，不要上传到 GitHub、云盘等公开平台

11.4 高风险动作二次审批配置

可配置高风险命令执行前必须经过你的手动批准，避免 Agent 误执行危险操作，比如、、格式化磁盘等命令。

配置方法

bash

运行

讯享网

配置完成后，Agent 执行这些命令时，会先向你发送审批请求，你点击确认后，才会执行，避免误操作。

也可以通过 JSON 文件批量导入审批规则：

1. 创建文件：

   json

2. 导入配置：

   bash

   运行

   讯享网

11.5 定期安全审计

执行以下命令，定期对 OpenClaw 做深度安全审计，及时发现安全隐患：

bash

运行

审计完成后，会列出所有安全隐患和修复建议，按提示及时修复即可。

---

12.1 日常状态检查清单

12.2 日志管理 & 错误排查

bash

运行

讯享网

12.3 配置备份 & 恢复方案

手动备份

bash

运行

自动备份（定时任务）

1. 创建备份脚本：

   bash

   运行

   讯享网

2. 给脚本添加执行权限：
3. 添加定时任务，每天凌晨 2 点自动备份：

   bash

   运行

恢复方案

bash

运行

讯享网

12.4 版本更新流程（无痛升级）

OpenClaw 更新频繁，建议每月更新一次，获取最新功能和 bug 修复，更新前务必备份配置。

标准更新流程

bash

运行

大版本升级注意事项

1. 大版本更新前，先查看官方更新日志，确认是否有破坏性变更
2. 先在测试环境验证，再更新生产环境
3. 升级后，必须执行修复配置兼容性问题
4. 若升级后出现异常，可通过备份的配置文件回滚到之前的版本。

12.5 监控告警配置（可选）

适合服务器 7×24 小时部署的用户，配置监控脚本，网关异常时自动重启并告警。

1. 创建监控脚本：

   bash

   运行

   讯享网

2. 给脚本添加执行权限：
3. 添加定时任务，每小时执行一次：

   bash

   运行

12.6 垃圾清理 & 空间优化

bash

运行

讯享网

---

遇到问题时，先执行，可自动修复 80% 的常见问题，若无法解决，再按以下场景排查。

场景 1：安装后提示

核心原因：npm 全局安装目录不在系统 PATH 环境变量中排查 & 解决步骤：

1. 先查找 openclaw 的安装位置

   bash

   运行

2. 若能找到安装路径，将路径添加到系统 PATH 中

   bash

   运行

   讯享网

3. 若找不到安装路径，重新执行安装命令，查看安装过程中是否有报错，大概率是 Node.js 版本过低，升级到 22 + 版本后重新安装。

场景 2：Gateway 网关启动失败

排查 & 解决步骤：

1. 前台启动网关，查看详细报错信息

   bash

   运行

2. 常见报错 1：（端口被占用）

   bash

   运行

   讯享网

3. 常见报错 2：配置文件 JSON 格式错误

   bash

   运行

4. 常见报错 3：Node.js 版本过低执行，确认版本≥22.0.0，低于该版本请升级 Node.js
5. 常见报错 4：网络代理问题海外模型用户需确认代理配置正确，执行验证网络连通性
6. 常见报错 5：后台服务启动失败
   • macOS：查看 LaunchAgent 状态，查看系统日志，重新安装守护进程，选择重新安装 daemon
   • Linux/WSL2：查看 systemd 服务状态，确认已启用 systemd，启用 lingering，避免用户登出后服务停止。

场景 3：发消息给 Bot 完全没反应

排查 & 解决步骤（按顺序执行）：

1. 第一步：确认网关正常运行

   bash

   运行

   讯享网

2. 第二步：确认渠道已正常连接

   bash

   运行

3. 第三步：确认配对已批准（90% 新手的问题）

   bash

   运行

   讯享网

4. 第四步：确认用户在白名单内检查配置文件中的，确认你的手机号 / 用户 ID 已添加到白名单，或配置的免配对规则正确。
5. 第五步：检查网络连通性
   • Telegram/WhatsApp 需确认网络可正常访问对应平台 API，国内用户需配置代理
   • 查看实时日志，确认消息是否到达网关

     bash

     运行

6. 第六步：确认模型 API 正常执行，确认模型 API 可正常调用，若 API 报错，检查 API Key 是否有效、是否有额度、网络是否正常。

场景 4：能回复，但一执行就报错

排查 & 解决步骤：

1. 第一步：确认工具权限已开放检查配置文件中的，确认对应的工具已在允许列表中，比如执行终端命令需要开放工具。
2. 第二步：确认沙箱权限配置正确

   bash

   运行

   讯享网

3. 第三步：常见报错：（权限不足）
   • 确认 Agent 有对应目录的读写权限，通过挂载需要访问的目录
   • 确认系统用户对文件 / 目录有操作权限，不要操作 root 权限的系统目录
4. 第四步：常见报错：浏览器启动失败 bash
   • 确认已安装 Chrome/Chromium 浏览器

   运行

5. 第五步：查看详细报错日志

   bash

   运行

   讯享网

   根据日志中的具体报错，修复对应问题。

场景 5：模型 API 调用失败

排查 & 解决步骤：

1. 执行健康检查，查看具体报错信息

   bash

   运行

2. 常见报错 1：（未授权）
   • 确认 API Key 已正确配置，没有多余的空格、换行
   • 确认 API Key 未过期、未被吊销，在模型控制台验证 Key 有效性
   • 确认使用了正确的 API Key，不要混用 Kimi 和 Kimi Coding 的 Key
3. 常见报错 2：（禁止访问）
   • 确认 API Key 有对应模型的访问权限
   • 确认没有使用 Claude Pro/Max 订阅密钥，必须使用按量付费的 API Key
   • 确认账户没有欠费、被封禁
4. 常见报错 3：请求超时 / 网络不可达
   • 海外模型用户确认代理配置正确，网络可正常访问 API 端点
   • 国内 Kimi 用户确认 baseUrl 配置为，不要用海外地址
   • 执行 curl 命令，直接测试 API 连通性

     bash

     运行

     讯享网

5. 常见报错 4：额度不足 / 速率限制
   • 确认账户有足够的 API 额度，在模型控制台查看使用情况
   • 降低调用频率，避免触发速率限制，在模型控制台设置额度上限。

场景 6：国内网络相关问题

排查 & 解决步骤：

1. 优先使用国内模型（Kimi/MiniMax/ 智谱 GLM），无需代理，网络更稳定
2. 若使用海外模型，必须配置系统代理，且终端代理生效

   bash

   运行

3. 若终端代理生效，但 OpenClaw 还是无法访问，直接在配置文件中设置代理

   bash

   运行

   讯享网

4. WSL2 用户需注意：WSL2 的代理地址要填写 Windows 主机的 IP，不能用 127.0.0.1，同时 Windows 防火墙要放行对应端口。

场景 7：macOS/Linux 后台服务启动失败

macOS 排查步骤：

1. 查看 LaunchAgent 状态

   bash

   运行

2. 查看系统日志，定位报错原因

   bash

   运行

   讯享网

3. 常见问题 & 解决：
   • 权限不足：在「系统设置 > 隐私与安全性」中给终端 / OpenClaw 授权完全磁盘访问权限
   • 环境变量未加载：确认文件存在，API Key 已正确写入
   • 重新安装守护进程：，选择重新安装 daemon

Linux/WSL2 排查步骤：

1. 查看 systemd 服务状态

   bash

   运行

2. 常见问题 & 解决：
   • 找不到 openclaw 命令：systemd 服务未加载用户 PATH，编辑服务文件，添加正确的 PATH 环境变量
   • 用户登出后服务停止：启用 lingering
   • 重新安装守护进程：，选择重新安装 daemon

场景 8：紧急恢复方案

若出现配置混乱、无法启动、未知错误，可按以下步骤紧急恢复：

1. 停止网关服务

   bash

   运行

   讯享网

2. 备份当前配置（必做，避免丢失凭证）

   bash

   运行

3. 重置配置，保留工作区和凭证

   bash

   运行

   讯享网

4. 重新执行初始化配置

   bash

   运行

5. 若仍有问题，恢复备份的配置文件，重启网关

   bash

   运行

   讯享网

---

基础管理命令

Gateway 网关命令

配置管理命令

模型管理命令

渠道管理命令

配对管理命令

会话 / 代理管理命令

技能管理命令

诊断 / 日志命令

---

1. 官方网站：https://openclaw.ai/
2. 官方中文文档：https://docs.openclaw.ai/zh-CN
3. 官方 GitHub 仓库：https://github.com/openclaw/openclaw
4. 官方 Discord 社区：discord.com/invite/clawd
5. 中文社区文档：https://www.moltcn.com/
6. 平台特定文档：
   • Windows/WSL2：https://docs.openclaw.ai/platforms/windows
   • macOS：https://docs.openclaw.ai/platforms/macos
   • Linux：https://docs.openclaw.ai/platforms/linux