OpenClaw 安装与配置教程

作者：CSDN博客

适合对象：Windows 初学者 / 需要快速跑通 OpenClaw 的开发者
阅读方式：按章节顺序执行；遇到报错先看每章「排错」再继续。

https://github.com/openclaw/openclaw

先看这个

先装好 Node.js 22+（可选 Git）。用 PowerShell 执行安装脚本。重点处理 PATH（不要用 setx PATH）。跑 openclaw onboard 完成模型与频道配置。用 openclaw gateway start/status 验证服务。

本教程风格说明

以「能跑通」为第一目标。命令默认可直接复制执行。关键坑位会明确标注，避免走回头路。

整体流程

1.准备工作（Node.js、PowerShell 设置）
2.安装 OpenClaw
3.路径设置（关键 - 必须是 GUI 或 PowerShell）
4. PATH 丢失恢复（在 setx 事故的情况下）
5.运行入门向导
6.Ollama 集成（本地/云模型）
7. ChatGPT 订阅集成（Codex CLI 身份验证，推荐）
8. Messenger 渠道集成 - Telegram
9. Messenger 渠道集成 - Discord
10.启动并验证网关
11.工作空间定制
OpenClaw（前身为 Clawbot / Moldbot）是一个运行在本地机器上的开源 AI 代理。通过 Telegram、WhatsApp、Discord 等消息工具发送指令，它可以代为执行文件操作、发送邮件、运行代码、管理日程等任务。
开始前说明
大多数路径在安装时会自动写入，以推荐默认路径为准。路径中的 <UserName> 替换为实际的 Windows 用户名。
1. 提前准备

步骤 1：安装 WSL2 和 Ubuntu 24.04

使用管理员权限运行 PowerShell 并输入以下命令。

1. wsl --update
2. wsl --install -d Ubuntu-24.04

复制代码

安装完成后请务必重新启动。重新启动后，当 Ubuntu 终端打开时，设置您的用户名和密码。
如果没有自动打开：

1. wsl -d Ubuntu-24.04

复制代码

故障排除：WSL_E_DISTRO_NOT_FOUND 错误

首次激活 WSL 功能时可能会发生这种情况。

1. wsl --update
2. wsl --list --online
3. wsl --install -d Ubuntu-24.04

复制代码

步骤2：激活systemd

在 Ubuntu 终端中运行它。

1. sudo tee /etc/wsl.conf >/dev/null <<'EOF'
2. [boot]
3. systemd=true
4. EOF

复制代码

在 PowerShell 中终止 WSL 并重新启动它。

1. wsl --shutdown

复制代码

1.1 安装 Node.js 22 或更高版本

OpenClaw 需要 Node.js 22 或更高版本。
如果您还没有，请从官方网站获取 LTS 版本。

下载：https://nodejs.org选择“推荐给大多数用户”版本使用安装向导中的默认设置继续

验证安装：

1. node --version
2. # 如果 v22.x.x 或更高版本则正常

复制代码

OpenClaw 安装脚本会自动检测 Node.js，如果不存在则尝试安装它，但提前安装可以减少错误。

1.2 安装Git（推荐）

从 GitHub 下载源代码时，某些 npm 包需要 Git。

下载：https://git-scm.com使用安装向导中的默认设置继续

1.3 CMD 与 PowerShell 的区别

当您在 Windows 中打开终端时，CMD（命令提示符） 和 PowerShell 是不同的环境。 OpenClaw 安装脚本是特定于 PowerShell 的，因此您必须从 PowerShell 运行它。
如何区分：

CMD 提示符：C:\Users\<用户名>>PowerShell 提示：PS C:\Users\<用户名>>

要从 CMD 切换到 PowerShell，请输入“powershell”。
1.4 检查PowerShell执行策略

Windows 的默认执行策略可能会阻止脚本执行。在管理员模式下打开PowerShell并更改执行策略：

1. Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

复制代码

当出现确认消息时，输入“Y”。
2.安装OpenClaw

在管理员模式下打开PowerShell并运行安装脚本：

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

复制代码

该脚本的作用：

检查Node.js版本



使用 npm 全局安装 OpenClaw CLI



创建初始配置目录(~/.openclaw/)



运行入门向导

3. PATH 设置（核心）

即使安装了 OpenClaw，大多数情况下也无法识别“openclaw”命令。这是因为npm全局二进制路径没有在用户PATH中注册。
3.1 检查问题

1. C:\Users\<UserName>>openclaw --version
2. “openclaw”是指内部或外部命令、可执行程序或
3. 它不是批处理文件。

复制代码

3.2 验证二进制文件是否存在

首先，检查安装本身是否成功：

1. npm prefix -g
2. # 示例输出：C:\Users\<用户名>\AppData\Roaming\npm
4. dir "C:\Users\<UserName>\AppData\Roaming\npm\openclaw*"
5. # 如果openclaw、openclaw.cmd、openclaw.ps1文件存在，则安装完成。

复制代码

通过直接路由验证操作：

1. "C:\Users\<UserName>\AppData\Roaming\npm\openclaw.cmd" --version
2. # 如果输出版本，则二进制文件正常。

复制代码

3.3 如何添加PATH（2种方式）

方法 A：GUI (sysdm.cpl) - 最安全

按“Win + R”，输入“sysdm.cpl”，然后按 Enter。单击高级选项卡单击环境变量按钮在顶部的用户变量部分中，选择“路径”和编辑单击“新建”输入 C:\Users\<用户名>\AppData\Roaming\npm

7.确定->确定->确定

要反映这一点，您必须完全关闭 CMD/PowerShell 窗口并重新打开它

方法 B：PowerShell - 安全附加到现有值

1. $current = [Environment]::GetEnvironmentVariable("PATH", "User")
2. [Environment]::SetEnvironmentVariable("PATH", "$current;C:\Users\<UserName>\AppData\Roaming\npm", "User")

复制代码

警告：切勿在 CMD 中使用 setx PATH。**
setx PATH "%PATH%;new path" 命令将用户 PATH + 系统 PATH 组合起来，覆盖用户 PATH，但由于 1024 个字符限制，内容被截断。这种情况下，之前注册的Ollama、Go、Python等路径将会丢失。
真实例子：

1. C:\Windows\System32>setx PATH "%PATH%;C:\Users\<UserName>\AppData\Roaming\npm"
2. 警告：保存的数据被截断为 1024 个字符。
3. 成功：指定值已保存。

复制代码

之后会出现无法识别 ollama 命令的情况。详细恢复方法请参见第4节。

3.4 好

在新终端中：

1. openclaw --version
2. ollama --version

复制代码

如果两者都正常，则PATH设置完成。
4. PATH丢失恢复（setx意外情况下）

这是意外执行setx PATH导致现有路径丢失时的恢复方法。
4.1 setx 破坏 PATH 的机制

Windows环境变量PATH有两种类型：

1. 最终路径=系统路径+用户路径

复制代码

如果您在 CMD 中引用 %PATH%，您将得到这个组合值。当您运行 setx PATH "%PATH%;new path" 时：
1.尝试将整个组合的PATH（数千个字符）放入用户PATH中

系统PATH 内容与用户PATH 重复。由于1024个字符的限制，最后一部分被截断。

4.Ollama、Rancher Desktop等后面的路径丢失。
4.2 现状诊断

在PowerShell中分别检查用户PATH和系统PATH：

1. Write-Host "=== USER PATH ==="
2. [Environment]::GetEnvironmentVariable("PATH", "User")
3. Write-Host ""
4. Write-Host "=== SYSTEM PATH ==="
5. [Environment]::GetEnvironmentVariable("PATH", "Machine")

复制代码

setx 仅覆盖用户路径。 系统PATH很有可能是安全的。 整个系统PATH会被复制并复制到用户PATH中，后面的部分（Ollama等）会因为截断1024个字符而丢失。
4.3 寻找丢失的路径

查找无法识别的程序（例如 Ollama）的实际位置：

1. where /R "C:\Users\<UserName>" ollama.exe
2. # 示例输出：C:\Users\<用户名>\AppData\Local\Programs\Ollama\ollama.exe

复制代码

4.4 重置用户路径

由于系统PATH已经包含Git、Python、Go、Node和Windows默认路径，因此您只需将您安装的程序的路径保留在用户PATH中即可。
在 PowerShell 中：

1. [Environment]::SetEnvironmentVariable("PATH", "C:\Users\<UserName>\AppData\Local\Programs\Ollama;C:\Users\<UserName>\AppData\Roaming\npm", "User")

复制代码

如有必要，添加其他用户程序路径，以分号分隔。
4.5 好

完全关闭CMD/PowerShell并打开一个新的：

1. ollama --version
2. openclaw --version

复制代码

一旦两者都被识别，恢复就完成了。
4.6 经验教训

方法	安全	备注
setx PATH (CMD)	危险	截断为 1024 个字符，混合系统+用户 PATH
sysdm.cpl (GUI)	安全	单独编辑用户/系统路径
`[Environment]::SetEnvironmentVariable() (PowerShell)	安全	只能准确操作用户PATH

添加 PATH 始终通过 GUI 或 PowerShell 完成。未使用“setx PATH”。
5. 入门向导

安装脚本自动开始载入。如果跳过则手动运行：

1. openclaw onboard --install-daemon

复制代码

向导中设置的项目：

订单	项目	描述
1	模型提供商	选择Ollama、Anthropic、OpenAI、Google等
2	API 密钥或身份验证	输入适合所选提供商的身份验证信息
3	Messenger 频道	选择要链接的频道，例如 Telegram、WhatsApp、Discord 等
4	技能	是否安装捆绑技能（可稍后添加，可跳过）
5	Hook / Webhook	不需要则跳过

单击“是”继续。

之后会出现型号名称，但根据使用的 AI 不同，型号名称也会有所不同。
就API而言，成本超出预期，所以我个人的建议是与Open AI的订阅系统链接或与本地LLM链接。

什么是Ollama？
Ollama 是一个开源平台，可让您在本地计算机上轻松运行和使用大型语言模型 (LLM)。
它允许您使用简单的命令运行 DeepSeek 或 LLaMA 等模型，无需任何复杂的设置，并像 API 一样使用它们。
6.Ollama 集成

Ollama 在 0.17 版本之后可以与 OpenClaw 链接，但这里假设 Ollmama 已经安装在 Windows 上。
6.1 ollama 启动命令

现在 OpenClaw 已经安装并设置了 PATH，它应该可以正常工作：

1. ollama launch openclaw

复制代码

这里，你选择一个模型，我选择gpt-oss 20b模型。
正常执行期间的输出示例：

1. This will modify your OpenClaw configuration:
2.   C:\Users\<Username>\.openclaw\openclaw.json
3. Backups will be saved to C:\Users\<Username>\AppData\Local\Temp\ollama-backups/
4. Added gpt-oss:20b to OpenClaw
5. Launching OpenClaw with gpt-oss:20b...

复制代码

奥拉马手柄：

备份现有设置显示型号选择屏幕将所选模型自动注册到 OpenClaw 设置启动网关运行 TUI（文本用户界面）控制台6.2 选型标准

OpenClaw 建议至少包含 64K 令牌的上下文窗口。
Ollama 云模型（推荐，提供免费套餐）：

型号	特点
gpt-oss:20b	通用，默认选择
Kimi-K2.5	性价比

本地型号（根据VRAM选择）：

型号	显存	用途
qwen3:8b	8GB	轻量问答
qwen2.5-coder:32b	24GB	编码专业化，工具调用支持
deepseek-r1:32b	24GB	专业推理
glm-4.7-flash	25GB	推理 + 代码生成

6.3 仅更改设置而不启动网关

1. ollama launch openclaw --config

复制代码

6.4 手动更改模型

要在网关已运行时更改模型：

1. openclaw models set ollama/qwen2.5-coder:32b

复制代码

或者直接编辑配置文件：

1. notepad %USERPROFILE%\.openclaw\openclaw.json

复制代码

配置示例（“openclaw.json”中的模型部分）：

1. {
2.   "models": {
3.     "providers": {
4.       "ollama": {
5.         "baseUrl": "http://localhost:11434/v1",
6.         "apiKey": "ollama-local",
7.         "api": "openai-completions",
8.         "models": [
9.           {
10.             "id": "gpt-oss:20b",
11.             "name": "gpt-oss:20b",
12.             "reasoning": false,
13.             "input": ["text"],
14.             "cost": {
15.               "input": 0,
16.               "output": 0,
17.               "cacheRead": 0,
18.               "cacheWrite": 0
19.             },
20.             "contextWindow": 131072,
21.             "maxTokens": 8192
22.           }
23.         ]
24.       }
25.     }
26.   },
27.   "agents": {
28.     "defaults": {
29.       "model": {
30.         "primary": "ollama/gpt-oss:20b"
31.       }
32.     }
33.   }
34. }

复制代码

修改配置文件后重启网关：

1. openclaw gateway restart

复制代码

然后，通过网络仪表板进行检查。
仪表板基本上可以通过“http://127.0.0.1:18789/”访问。
7.ChatGPT 订阅集成

点击 OPENAI 后进行 OAuth 授权，即可将其与 GPT 订阅关联，或从 OpenAI 获取 API 密钥，通过 API 方式进行访问。

8. Messenger 渠道集成（Telegram）

Telegram 的设置难度最低。
8.1 创建 Telegram 机器人

在 Telegram 应用中搜索“@BotFather”并开始对话

2.输入/n​​ewbot命令

输入机器人名称（例如“MyOpenClaw”）输入机器人用户名（例如my_openclaw_bot，必须以_bot结尾）

5.复制BotFather颁发的Bot Token（格式：123456789:ABCdefGHI...）
8.2 在 OpenClaw 中注册 Telegram 令牌

如果您在入门向导中选择 Telegram，则会出现令牌输入屏幕。

1. openclaw onboard

复制代码

手动注册：

1. openclaw channels add --channel telegram --token <YOUR_BOT_TOKEN>

复制代码

注意： 您也可以在openclaw configure --sectionchannels（交互式向导）中注册，但是直接使用CLI注册时，必须使用channels add命令。 openclaw config setchannels.telegram.token ...不起作用（键名称不同）。

注册令牌后，您必须重新启动网关才能反映它：

1. openclaw gateway restart

复制代码

8.2.1 401 未经授权的错误

如果网关日志中重复出现以下错误：

1. [telegram] telegram deleteWebhook failed: Call to 'deleteWebhook' failed! (401: Unauthorized)
2. [telegram] [default] channel exited: Call to 'deleteWebhook' failed! (401: Unauthorized)
3. [telegram] [default] auto-restart attempt 1/10 in 5s

复制代码

原因： Telegram 机器人令牌无效或已过期。
解决：

在 Telegram 中，转到 @BotFather -> /mybots -> 选择机器人 -> 使用 API Token 重新确认令牌

2.如果token不匹配，则使用/revoke重新颁发

使用新令牌重新注册：

1. openclaw 频道添加 --channel telegram --token <new_token>
2. openclaw gateway restart

复制代码

如果令牌问题未解决，请尝试创建新的机器人。
8.3 配对

在 Telegram 中找到您刚刚创建的机器人并发送 /start机器人发送一条包含配对码的消息批准终端配对：

1. openclaw pairing approve telegram <CODE>

复制代码

8.4 好

在 Telegram 上向机器人发送任何消息。
如果收到响应，则链接完成。
9. Messenger 渠道集成 (Discord)

您可以链接 Discord 来代替 Telegram 或作为 Telegram 的补充。
访问https://discord.com/developers/applications

单击“新建应用程序”，输入名称（例如“OpenClawBot”）单击左侧菜单中的机器人选项卡点击重置令牌复制机器人令牌

9.2 特权网关意图设置（必填）

在“机器人”选项卡中，滚动找到“特权网关意图”部分。打开 全部 以下三个：

存在意图 - 检测在线状态服务器成员意图 - 查询服务器成员消息内容意图 - 读取消息内容（必填）

激活后，请务必单击“保存更改”。

如果省略此步骤，机器人将无法工作。 网关日志中将重复出现以下错误：

1. [discord] discord: gateway closed with code 4014 (missing privileged gateway intents)
2. [discord] [default] auto-restart attempt 1/10 in 5s

复制代码

如果您看到此错误，请确保在 Discord 开发者门户中打开意图切换。如果您打开开关并保存，网关将在自动重试时正常连接。

9.3 邀请机器人到您的服务器

1.点击左侧菜单OAuth2

滚动查看 OAuth2 URL 生成器 部分在 Scopes 列表中选中“bot”（左上列第 5 列）如果您选中“机器人”，机器人权限面板将出现在底部。检查机器人权限：

-发送消息

阅读消息历史记录阅读消息/查看频道嵌入链接附加文件

生成的 URL 显示在页面底部。复制 URL 并将其粘贴到浏览器中选择您想要邀请机器人加入的服务器并批准

9.4 在 OpenClaw 中注册 Discord 令牌

1. openclaw channels add --channel discord --token "YOUR_BOT_TOKEN"

复制代码

警告： 在 PowerShell 中，令牌必须 用引号括起来。 Discord 机器人令牌中包含的特殊字符（例如“.”）可能会被解释为 shell 运算符。在CMD中，它无需引号即可工作，但建议习惯性将其换行。

注册完成后，重启网关：

1. openclaw gateway restart

复制代码

9.5 配对

如果您向 Discord 上的机器人发送私信，您将收到配对码。

1. openclaw pairing approve discord <CODE>

复制代码

9.6 好

向 Discord 上的机器人发送 DM 消息。如果收到响应，则链接完成。

注意： 首先使用 DM 进行测试，而不是服务器通道。要在服务器通道中使用机器人，您必须通过提及（@OpenClawBot）来调用它，或者在 OpenClaw 设置中调整提及门控。

10.启动并验证网关

1. # 启动网关
2. openclaw gateway start
4. # 检查状态
5. openclaw gateway status
7. # 打开网页仪表板
8. openclaw dashboard

复制代码

默认可以通过“http://127.0.0.1:18789/”访问Web仪表板，通过GUI可以轻松查看状态一目了然。
要更改端口：

1. openclaw gateway --port 18790

复制代码

---

11.工作区定制

安装后，会在 %USERPROFILE%\.openclaw\ 目录中创建以下结构：

1. %USERPROFILE%\.openclaw\
2. openclaw.json # 主要设置（模型、通道、网关等）
3.   workspace\
4. AGENTS.md # 代理行为说明（引导程序）
5. SOUL.md # Persona（个性、语气、态度）
6. USER.md # 用户信息（姓名、工作背景、偏好）
7. MEMORY.md # 长期记忆（你从对话中学到的东西）
8. IDENTITY.md # 代理自我介绍（姓名、表情符号等）
9. Skills/ # 技能插件目录

复制代码

11.1 各文件的作用

OpenClaw 在每次会话开始时读取工作区文件，构建代理的性格与上下文。由于代理没有跨会话记忆，这些文件就是它的记忆。
[table][tr][td]文件[/td][td]作用[/td][td]由谁编辑[/td][td]示例[/td][/tr][tr][td]SOUL.md[/td][td]定义代理的性格、说话风格、行为原则。回答"你是什么样的存在"。[/td][td]用户自行编写[/td][td]讽刺语气、直接风格、毒舌程度等[/td][/tr][tr][td]USER.md[/td][td]用户信息。姓名、职业、工作背景、偏好的沟通方式。[/td][td]用户自行编写或由引导向导生成[/td][td]"JDW，技术 CEO，无需客套"[/td][/tr][tr][td]AGENTS.md[/td][td]代理行为指令（引导程序）。工具使用规则、响应格式、工作流程定义。[/td][td]用户自行编写[/td][td]"对外发送前必须确认"，"修改文件前备份"[/td][/tr][tr][td]MEMORY.md[/td][td]从对话中学习的长期记忆。代理在对话中记录的内容存储于此。[/td][td]代理自动更新（用户也可编辑）[/td][td]"JDW 讨厌 setx PATH"[/td][/tr][tr][td]IDENTITY.md[/td][td]代理的自我介绍。名称、Emoji、一句话介绍。[/td][td]引导向导生成（用户也可编辑）[/td][td]"名称：Secretary，Emoji：