OpenClaw

整体流程

Info

事前准备（Node.js、PowerShell 配置）
安装 OpenClaw
PATH 设置（核心 —— 必须用 GUI 或 PowerShell）
PATH 丢失恢复（setx 事故时）
运行引导向导
Ollama 集成（本地 / 云端模型）
ChatGPT 订阅集成（Codex CLI 认证，推荐）
消息渠道集成 —— Telegram
消息渠道集成 —— Discord
启动并验证网关
工作区自定义

OpenClaw（前身为 Clawbot / Moldbot）是一个运行在本地机器上的开源 AI 代理。通过 Telegram、WhatsApp、Discord 等消息工具发送指令，它可以代为执行文件操作、发送邮件、运行代码、管理日程等任务。

开始前说明

大多数路径在安装时会自动写入，以推荐默认路径为准。路径中的 <UserName> 替换为实际的 Windows 用户名。

1. 事前准备

第一步：安装 WSL2 与 Ubuntu 24.04

以管理员权限打开 PowerShell，执行：

wsl --update
wsl --install -d Ubuntu-24.04

安装完成后必须重启。重启后 Ubuntu 终端自动打开，设置用户名和密码。

未自动打开时：

wsl -d Ubuntu-24.04

故障排查：WSL_E_DISTRO_NOT_FOUND 错误

首次激活 WSL 功能时可能出现，依次执行：

wsl --update
wsl --list --online
wsl --install -d Ubuntu-24.04

第二步：启用 systemd

在 Ubuntu 终端中执行：

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

在 PowerShell 中终止 WSL 并重启：

wsl --shutdown

1.1 安装 Node.js 22 及以上版本

OpenClaw 需要 Node.js 22+。

下载地址：https://nodejs.org
选择"Recommended For Most Users"版本
安装向导保持默认设置

验证安装：

node --version
# v22.x.x 이상이면 정상

OpenClaw 安装脚本会自动检测 Node.js，未安装时会尝试自动安装，但提前装好可以减少出错概率。

1.2 安装 Git（推荐）

部分 npm 包需要从 GitHub 拉取源码，依赖 Git。

下载地址：https://git-scm.com
安装向导保持默认设置

1.3 CMD 与 PowerShell 的区别

OpenClaw 安装脚本是 PowerShell 专用，必须在 PowerShell 中运行。

终端	提示符样式
CMD（命令提示符）	`C:\Users\<UserName>>`
PowerShell	`PS C:\Users\<UserName>>`

在 CMD 中切换到 PowerShell：输入 powershell 回车。

1.4 检查 PowerShell 执行策略

Windows 默认执行策略可能阻止脚本运行。以管理员模式打开 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

出现确认提示时输入 Y。

2. 安装 OpenClaw

以管理员模式打开 PowerShell，运行安装脚本：

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

该脚本执行的操作：

检查 Node.js 版本
使用 npm 全局安装 OpenClaw CLI
创建初始配置目录（~/.openclaw/）
启动引导向导

3. PATH 设置（核心）

安装 OpenClaw 后，openclaw 命令通常无法直接识别。原因是 npm 全局二进制目录没有被注册到用户 PATH 中。

3.1 确认问题

C:\Users\<UserName>>openclaw --version
'openclaw' 不是内部或外部命令，也不是可运行的程序或批处理文件。

3.2 确认二进制文件是否存在

먼저 설치 자체가 됐는지 확인한다:

npm prefix -g
# 示例输出：C:\Users\<UserName>\AppData\Roaming\npm

dir "C:\Users\<UserName>\AppData\Roaming\npm\openclaw*"
# 存在 openclaw、openclaw.cmd、openclaw.ps1 则安装成功

직접 경로 지정으로 동작 확인:

"C:\Users\<UserName>\AppData\Roaming\npm\openclaw.cmd" --version
# 输出版本号则二进制正常

3.3 添加 PATH 的两种方法

方法 A：GUI（sysdm.cpl）—— 最安全

Win + R，输入 sysdm.cpl，回车
点击「高级」选项卡
点击「环境变量」
在上方「用户变量」中选中 Path，点击「编辑」
点击「新建」
输入 C:\Users\<UserName>\AppData\Roaming\npm
依次点击「确定」→「确定」→「确定」

修改后必须完全关闭当前 CMD/PowerShell 窗口，重新打开才能生效。

方法 B：PowerShell —— 安全追加到现有值

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

警告：绝对不要在 CMD 中使用 setx PATH。

setx PATH "%PATH%;新路径" 会将用户 PATH + 系统 PATH 的合并值写入用户 PATH，而合并后的字符串通常超过 1024 字符限制，导致末尾路径被截断。Ollama、Go、Python 等之后安装的程序路径会因此丢失。

实际案例：
C:\Windows\System32>setx PATH "%PATH%;C:\Users\<UserName>\AppData\Roaming\npm"
警告：所保存的数据被截断至 1024 个字符。
成功：指定的值已得到保存。
执行后 ollama 命令立即失效。详细恢复方法见第 4 节。

3.4 验证

在新终端中：

powershell

openclaw --version
ollama --version

两者均正常输出即 PATH 设置完成。

4. PATH 丢失恢复（setx 事故时）

误执行 setx PATH 导致现有路径丢失的恢复方法。

4.1 setx 破坏 PATH 的机制

Windows 的 PATH 分为两类：

最终 PATH = 系统 PATH + 用户 PATH

在 CMD 中引用 %PATH% 得到的是合并后的值。执行 setx PATH "%PATH%;新路径" 时：

试图将整个合并 PATH（数千字符）写入用户 PATH
系统 PATH 内容被复制并合并到用户 PATH 中
超过 1024 字符被截断
末尾的 Ollama、Rancher Desktop 等路径丢失

4.2 诊断当前状态

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

powershell

Write-Host "=== USER PATH ==="
[Environment]::GetEnvironmentVariable("PATH", "User")
Write-Host ""
Write-Host "=== SYSTEM PATH ==="
[Environment]::GetEnvironmentVariable("PATH", "Machine")

setx 只覆盖用户 PATH，系统 PATH 大概率完好。当前状态是：用户 PATH 中混入了系统 PATH 的全部内容，加上 1024 字符截断，末尾的 Ollama 等路径已丢失。

4.3 找回丢失的路径

查找 Ollama 等无法识别的程序的实际位置：

powershell

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

4.4 重置用户 PATH

由于系统 PATH 已经包含 Git、Python、Go、Node、Windows 默认路径，用户 PATH 只需保留用户自行安装的程序路径。

在 PowerShell 中：

powershell

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

根据实际情况，用分号追加其他用户程序路径。

4.5 验证

完全关闭 CMD/PowerShell，重新打开：

ollama --version
openclaw --version

两者均被识别则恢复完成。

4.6 经验总结

方法	安全性	说明
`setx PATH`（CMD）	危险	1024 字符截断，混合系统+用户 PATH
`sysdm.cpl`（GUI）	安全	用户/系统 PATH 分开编辑
`[Environment]::SetEnvironmentVariable()`（PowerShell）	安全	只精确操作用户 PATH

添加 PATH 始终通过 GUI 或 PowerShell 完成。setx PATH 不使用。

5. 引导向导

安装脚本会自动启动引导向导。如果跳过了，手动运行：

powershell

openclaw onboard --install-daemon

向导配置项：

顺序	项目	说明
1	模型提供商	选择 Ollama、Anthropic、OpenAI、Google 等
2	API 密钥或认证	输入所选提供商的认证信息
3	消息渠道	选择 Telegram、WhatsApp、Discord 等
4	技能	是否安装捆绑技能（可稍后添加，可跳过）
5	Hook / Webhook	不需要则跳过

出现提示时选择 Yes 继续。

之后会显示模型名称，根据所选 AI 不同而有所差异。

API 方式费用往往超出预期，个人推荐与 OpenAI 订阅制集成，或与本地 LLM 集成。

关于 Ollama

Ollama 是一个开源平台，让你能在本地计算机上轻松运行和使用大型语言模型（LLM）。无需复杂配置，通过简单命令即可运行 DeepSeek、LLaMA 等模型，并像调用 API 一样使用它们。

6. Ollama 集成

Ollama 0.17 版本之后可以与 OpenClaw 联动。本节假设 Ollama 已安装在 Windows 上。

6.1 ollama launch 命令

OpenClaw 安装与 PATH 设置完成后，直接执行：

ollama launch openclaw

此时会显示模型选择界面。本文以 gpt-oss:20b 为例。

正常执行时的输出示例：

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

Ollama 执行的操作：

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

6.2 模型选择参考

OpenClaw 建议上下文窗口至少 64K token。

Ollama 云端模型（推荐，提供免费套餐）：

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

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

模型	VRAM	用途
`qwen3:8b`	8GB	轻量问答
`qwen2.5-coder:32b`	24GB	编码专用，支持 tool calling
`deepseek-r1:32b`	24GB	推理专用
`glm-4.7-flash`	25GB	推理 + 代码生成

6.3 仅更改配置，不启动网关

ollama launch openclaw --config

6.4 手动更改模型

网关运行中时切换模型：

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

或直接编辑配置文件：

notepad %USERPROFILE%\.openclaw\openclaw.json

配置示例（openclaw.json 中的 models 段）：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-oss:20b",
            "name": "gpt-oss:20b",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/gpt-oss:20b"
      }
    }
  }
}

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

openclaw gateway restart

之后通过 Web 仪表板确认状态。仪表板默认地址：http://127.0.0.1:18789/

7. ChatGPT 订阅集成（Codex CLI 认证）

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

8. 消息渠道集成（Telegram）

Telegram 的设置难度最低。

8.1 创建 Telegram 机器人

在 Telegram 中搜索 @BotFather，开始对话
输入 /newbot 命令
输入机器人名称（例：MyOpenClaw）
输入机器人用户名（例：my_openclaw_bot，必须以 _bot 结尾）
复制 BotFather 颁发的 Bot Token（格式：123456789:ABCdefGHI...）

8.2 在 OpenClaw 中注册 Telegram Token

引导向导中选择了 Telegram 的话，会出现 Token 输入界面：

openclaw onboard

注册模型后，

选择 Telegram 渠道，在 Token 输入框中填入 Token。手动注册：

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

注意： openclaw configure --section channels（交互式向导）也可以注册，但 CLI 直接注册时必须使用 channels add 命令。openclaw config set channels.telegram.token ... 无效（键名不同）。

openclaw gateway restart

8.2.1 401 Unauthorized 错误

网关日志中反复出现以下错误：

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

原因： Telegram 机器人 Token 无效或已过期。

解决：

在 Telegram 中进入 @BotFather → /mybots → 选择机器人 → API Token，重新确认 Token
不匹配则用 /revoke 重新颁发
用新 Token 重新注册：

openclaw channels add --channel telegram --token <새_토큰>
openclaw gateway restart

Token 问题无法解决时，尝试创建新机器人。

8.3 配对

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

openclaw pairing approve telegram <CODE>

8.4 验证

在 Telegram 中向机器人发送任意消息。收到回复则集成完成。

9. 消息渠道集成（Discord）

可以替代 Telegram 或同时使用。

9.1 创建 Discord 机器人

访问 https://discord.com/developers/applications
点击「New Application」，输入名称（例：OpenClawBot）
左侧菜单点击「Bot」选项卡
点击「Reset Token」，复制机器人 Token

9.2 Privileged Gateway Intents 设置（必须）

在「Bot」选项卡中滚动到「Privileged Gateway Intents」，将以下三项全部打开：

Presence Intent —— 检测在线状态
Server Members Intent —— 查询服务器成员
Message Content Intent —— 读取消息内容（必须）

打开后必须点击「Save Changes」保存。

跳过此步骤机器人将无法工作。网关日志中会反复出现：
[discord] discord: gateway closed with code 4014 (missing privileged gateway intents)
[discord] [default] auto-restart attempt 1/10 in 5s
确认 Developer Portal 中 Intent 开关已打开并保存后，网关重试时会自动正常连接。

9.3 邀请机器人到服务器

左侧菜单点击「OAuth2」
滚动到「OAuth2 URL Generator」
在 Scopes 中勾选 bot
勾选 bot 后，下方出现「Bot Permissions」面板
勾选以下权限：
- Send Messages
- Read Message History
- Read Messages/View Channels
- Embed Links
- Attach Files
复制页面底部生成的 URL，粘贴到浏览器
选择要邀请机器人的服务器并授权

9.4 在 OpenClaw 中注册 Discord Token

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

注意： 在 PowerShell 中 Token 必须用引号包裹。Discord Bot Token 中包含的特殊字符（如 .）可能被 Shell 解释为运算符。CMD 中不加引号也能运行，但养成加引号的习惯更安全。

注册后重启网关：

openclaw gateway restart

9.5 配对

在 Discord 中向机器人发送私信，会收到配对码：

openclaw pairing approve discord <CODE>

9.6 验证

向 Discord 机器人发送私信。收到回复则集成完成。

注意： 优先在私信（DM）中测试，不要在服务器频道中测试。在服务器频道中使用机器人需要用 @OpenClawBot 提及，或在 OpenClaw 配置中调整 mention gating 设置。

10. 启动并验证网关

# 启动网关
openclaw gateway start

# 检查状态
openclaw gateway status

# 打开 Web 仪表板
openclaw dashboard

Web 仪表板默认地址：http://127.0.0.1:18789/，可通过 GUI 一目了然地查看状态。

更改端口：

openclaw gateway --port 18790

11. 工作区自定义

安装后在 %USERPROFILE%\.openclaw\ 目录下生成以下结构：

%USERPROFILE%\.openclaw\
  openclaw.json          # 主配置（模型、渠道、网关等）
  workspace\
    AGENTS.md            # 代理行为指令（引导程序）
    SOUL.md              # 人格设定（性格、说话风格、态度）
    USER.md              # 用户信息（姓名、工作背景、偏好）
    MEMORY.md            # 长期记忆（从对话中学习的内容）
    IDENTITY.md          # 代理自我介绍（名称、Emoji 等）
    skills/              # 技能插件目录

11.1 各文件的作用

OpenClaw 在每次会话开始时读取工作区文件，构建代理的性格与上下文。由于代理没有跨会话记忆，这些文件就是它的记忆。

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

11.2 SOUL.md 与 AGENTS.md 的区别

容易混淆的两个文件：

SOUL.md = "是谁"（性格）

说话方式、态度、幽默风格
讽刺程度、夸奖标准
情感边界（何时认真对待）

AGENTS.md = "做什么，怎么做"（行为规则）

工具使用权限与限制
任务执行流程与优先级
响应格式（代码风格、语言等）
需要用户确认的操作列表

例如："用讽刺语气回复"放在 SOUL.md；"发送邮件前必须获得用户确认"放在 AGENTS.md。

11.3 编辑 SOUL.md

notepad %USERPROFILE%\.openclaw\workspace\SOUL.md

11.4 编辑 USER.md

notepad %USERPROFILE%\.openclaw\workspace\USER.md

11.5 编辑 AGENTS.md

notepad %USERPROFILE%\.openclaw\workspace\AGENTS.md

11.6 会话中切换模型

/model opus4.5

12. 添加技能

技能是为 OpenClaw 添加功能的插件。

12.1 用 ClawHub CLI 搜索并安装技能

powershell

npm i -g clawhub

clawhub search "calendar"
clawhub install <skill-slug>
clawhub list

12.2 直接创建技能文件

也可以在 workspace/skills/ 文件夹中直接创建 SKILL.md 文件。新会话开始时自动加载。

13. 常用命令速查

命令	说明
`openclaw --version`	检查安装版本
`openclaw doctor`	诊断配置问题
`openclaw status`	查看整体状态
`openclaw gateway start`	启动网关
`openclaw gateway restart`	重启网关
`openclaw gateway status`	检查网关状态
`openclaw dashboard`	打开 Web 仪表板
`openclaw models set <model>`	更改模型
`openclaw config get gateway.auth.token`	检查网关认证 Token
`openclaw channels login`	渠道登录
`openclaw pairing approve <channel> <code>`	渠道配对批准
`openclaw pairing list <channel>`	查看配对列表
`ollama launch openclaw`	通过 Ollama 运行
`ollama launch openclaw --config`	仅更改配置（不启动网关）

14. 故障排查

14.1 `openclaw` 命令无法识别

原因： npm 全局路径不在 PATH 中。

诊断：

# 确认二进制位置
npm prefix -g

# 确认文件是否存在
dir "C:\Users\<UserName>\AppData\Roaming\npm\openclaw*"

# 用绝对路径测试
"C:\Users\<UserName>\AppData\Roaming\npm\openclaw.cmd" --version

绝对路径能输出版本号，则安装完成，只需添加 PATH。参考 3.3 节。

14.2 `ollama` 命令无法识别

原因 A： setx PATH 导致用户 PATH 丢失（参考 14.3 节）

原因 B： Ollama 路径未注册到 PATH

诊断：

where /R "C:\Users\<UserName>" ollama.exe
# example C:\Users\<UserName>\AppData\Local\Programs\Ollama\ollama.exe

路径存在则说明已安装，只是不在 PATH 中。用 3.3 节的方法将对应目录加入 PATH。

14.3 setx PATH 导致环境变量丢失

症状：

CMD 中执行 setx PATH "%PATH%;新路径" 后
出现"警告：所保存的数据被截断至 1024 个字符"
之后 ollama、go、python 等原本正常的命令全部失效

原因： %PATH% 是用户 PATH + 系统 PATH 的合并值，setx PATH 只覆盖用户 PATH。合并后的长字符串在 1024 字符处截断，末尾的路径（Ollama 等）丢失。

恢复： 参考第 4 节。

预防： PATH 添加始终通过 GUI（sysdm.cpl）或 PowerShell 完成。14.4 CMD 中执行 PowerShell 专用命令报错

症状：

C:\Windows\System32>[Environment]::SetEnvironmentVariable(...)
文件名、目录名或卷标语法不正确。

原因： [Environment]::SetEnvironmentVariable() 是 PowerShell 专用的 .NET 语法，不能在 CMD 中运行。

解决： 在 CMD 中输入 powershell 切换到 PowerShell 后执行，或直接从开始菜单打开 PowerShell。

14.5 修改 PATH 后命令仍然无法识别

原因： 环境变量修改不会反映到已打开的终端窗口中。

解决： 必须完全关闭 CMD/PowerShell 窗口，重新打开才能生效。在同一窗口中不管重新输入多少次，都会继续使用旧的 PATH。

14.6 `ollama` 命令无输出退出（system32 幽灵文件）

症状： PowerShell 中运行 ollama --version 提示符返回但无任何输出。或运行 ollama launch openclaw 时弹出"选择打开 'ollama' 的应用"对话框。

诊断：

Get-Command ollama
# Source 为 C:\Windows\system32\ollama 则有问题

(Get-Item "C:\Windows\system32\ollama").Length
# 输出 0 则确认为幽灵文件

原因： C:\Windows\system32 中存在 0 字节的空 ollama 文件，其优先级高于真正的 ollama.exe（用户 PATH），将其拦截。可能是 WSL 安装过程中创建的。

解决： 在管理员 PowerShell 中：

Remove-Item "C:\Windows\system32\ollama" -Force

删除后在新终端中：

ollama --version
# 정상적으로 버전 출력되면 해결

14.7 `ollama launch openclaw` 不支持（版本问题）

症状： 运行 ollama launch openclaw 无响应或报错。

诊断：

ollama --version

原因： ollama launch openclaw 需要 Ollama 0.17 及以上版本。0.16.x 及以下不存在此命令。

解决： 从 https://ollama.com/download/windows 下载最新版本安装。

ollama --version
# 0.17.x 이상이면 정상

14.8 node.exe 崩溃（0xc0000005）

Windows Defender 对 node.exe 的误报。

解决：

临时关闭 Windows Defender 实时保护
重新运行安装脚本
安装完成后重新开启实时保护

14.9 PowerShell 中脚本执行被阻止

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

14.10 引导向导安全提示自动选择 No

症状： 运行 ollama launch openclaw 后，安全确认提示未等待键入就自动选择"No"退出：

o  I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
|  No
Error: exit status 1

原因： Windows 原生 CMD 无法识别 OpenClaw TUI 的交互式输入。OpenClaw 本身也会给出警告：

Windows detected -- OpenClaw runs great on WSL2!
Native Windows might be trickier.

解决： 在 Windows Terminal 中运行。从 Microsoft Store 搜索安装"Windows Terminal"，在其中运行命令，TUI 输入即可正常工作。

14.11 `ollama launch openclaw` 中模型连接失败

确认 Ollama 服务是否正在运行：

ollama ps

未运行则启动 Ollama 应用，或：

ollama serve

14.12 网关无法启动

# 诊断
openclaw doctor

# 查看日志
openclaw gateway --verbose

14.13 npm install 中内存不足

PowerShell 中：

$env:NODE_OPTIONS="--max-old-space-size=4096"
iwr -useb https://openclaw.ai/install.ps1 | iex

CMD 中：

set NODE_OPTIONS=--max-old-space-size=4096

14.14 Discord 机器人连接失败（code 4014）

症状： 网关日志中反复出现：

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

原因： Discord Developer Portal 中 Privileged Gateway Intents 处于关闭状态。

解决：

访问 https://discord.com/developers/applications
点击机器人应用 → 左侧「Bot」选项卡
滚动到「Privileged Gateway Intents」，将三项全部打开：
- Presence Intent
- Server Members Intent
- Message Content Intent
点击「Save Changes」

网关会自动重试，无需单独重启。日志中无错误输出则连接成功。

14.15 PowerShell 中输入 Discord Token 时报错

症状：

openclaw channels add --channel discord --token <MTQ3NzY3...>
At line:1 char:49
+ ... --token <MTQ3NzY3...
+             ~
The '<' operator is reserved for future use.

原因： PowerShell 将 Token 中的 <> 或特殊字符解释为 Shell 运算符。

解决： 用引号包裹 Token：

openclaw channels add --channel discord --token "MTQ3NzY3..."

或使用交互式向导，不存在引号问题：

openclaw configure --section channels

15. 安全注意事项

OpenClaw 的创建者 Peter Steinberger 在官方文档中亲自警告：

"在个人电脑上运行 AI 代理是有风险的。"

应遵守的原则：

与金融环境隔离。 不在有银行应用、证券账户、加密货币钱包的用户账号下运行。
建议创建独立用户账号运行。 在 Windows 中新建一个标准用户账号，隔离运行。
不安装来源不明的技能。 已有通过恶意技能发起攻击的案例报告。
使用本地模型时更需谨慎。 小型本地模型可能误解指令，导致错误的文件操作。文件操作或自动化等代理行为，建议使用 API 模型（Claude、GPT 等）执行更安全。

定期运行安全诊断：

openclaw doctor

6. 费用

OpenClaw 本身是开源免费的。但使用 LLM 可能产生费用：

类型	费用	计费方式
Ollama 本地模型	免费（仅电费）	无
Ollama 云端模型	提供免费套餐，超出后计费	按量付费
ChatGPT Plus（Codex CLI）	月 $20 定额	无限制
ChatGPT Pro	月 $200 定额	无限制（可用顶级模型）
Anthropic Claude API	按使用量计费	按量付费
OpenAI GPT API	按使用量计费	按量付费

代理自主运行时 Token 消耗难以预测。使用 API 按量付费时，建议监控使用量并设置每日上限。

17. 结语

按照本文走完的话，OpenClaw 应该能正常运行了。发 Telegram 消息也会有回应。笔者是在 Docker 环境而非 Windows 中安装的，不过会配 Docker 环境的人看都不用看这篇就能搞定。

但说实话，这东西到底有没有用，我持怀疑态度。

"AI 替我控制电脑"——听起来很酷。但实际用下来，大多数操作直接自己做反而更快。想移动一个文件，在资源管理器里拖过去比在 Telegram 输命令等确认快三秒。

那这个生态系统为什么存在？

答案很简单：这是恐惧营销。

它贩卖的是焦虑——"不搭 AI 代理就会被时代抛下"。没有 AI 助手守着自己的电脑，就会让人觉得自己效率低下。安装过程越复杂，排故障越多，完成时的成就感就越强。哪怕这种成就感和实际生产力提升毫无关系。

我个人把这称为虚假成就感。生产力没有提升，只是把"问题解决了"的感觉卖给你。对我来说安装很顺利，但对非开发者而言这是一个相当费力的过程。

这篇指南最长的一节恰恰是故障排查，这说明了什么？

本地 AI 代理真正有意义的场景极少。条件是：重复性任务明确、该任务确实频繁发生、委托给代理比自己做更有效率。不满足这些条件，它就只是个耗电的聊天机器人。和直接开个网页聊天相比，优势在哪里？

用 Python 可以自动化简单的 Excel 工具。

因为跨节上下文的问题，用代理改 Excel 工具的效果往往不如预期。

PPT 这类现在基本都能做了。开个 CLI 跑多代理，编码也没必要专门用 OpenClaw。

仔细审视那些所谓的"代理自动化"行为，大部分根本不需要自由化。当然也会有人从中找到真正有用的场景。

选择多了当然是好事。但它是否真的像媒体鼓吹的那样带来爆炸性的生产力提升，我仍然持保留意见。

整体流程

1. 事前准备

第一步：安装 WSL2 与 Ubuntu 24.04

故障排查：WSL_E_DISTRO_NOT_FOUND 错误

第二步：启用 systemd

1.1 安装 Node.js 22 及以上版本

1.2 安装 Git（推荐）

1.3 CMD 与 PowerShell 的区别

1.4 检查 PowerShell 执行策略

2. 安装 OpenClaw

3. PATH 设置（核心）

3.1 确认问题

3.2 确认二进制文件是否存在

3.3 添加 PATH 的两种方法

3.4 验证

4. PATH 丢失恢复（setx 事故时）

4.1 setx 破坏 PATH 的机制

4.2 诊断当前状态

4.3 找回丢失的路径

4.4 重置用户 PATH

4.5 验证

4.6 经验总结

5. 引导向导

关于 Ollama

6. Ollama 集成

6.1 ollama launch 命令

6.2 模型选择参考

6.3 仅更改配置，不启动网关

6.4 手动更改模型

7. ChatGPT 订阅集成（Codex CLI 认证）

8. 消息渠道集成（Telegram）

8.1 创建 Telegram 机器人

8.2 在 OpenClaw 中注册 Telegram Token

8.2.1 401 Unauthorized 错误

8.3 配对

8.4 验证

9. 消息渠道集成（Discord）

9.1 创建 Discord 机器人

9.2 Privileged Gateway Intents 设置（必须）

9.3 邀请机器人到服务器

9.4 在 OpenClaw 中注册 Discord Token

9.5 配对

9.6 验证

10. 启动并验证网关

11. 工作区自定义

11.1 各文件的作用

11.2 SOUL.md 与 AGENTS.md 的区别

11.3 编辑 SOUL.md

11.4 编辑 USER.md

11.5 编辑 AGENTS.md

11.6 会话中切换模型

12. 添加技能

12.1 用 ClawHub CLI 搜索并安装技能

12.2 直接创建技能文件

13. 常用命令速查

14. 故障排查

14.1 openclaw 命令无法识别

14.2 ollama 命令无法识别

14.3 setx PATH 导致环境变量丢失

14.5 修改 PATH 后命令仍然无法识别

14.6 ollama 命令无输出退出（system32 幽灵文件）

14.7 ollama launch openclaw 不支持（版本问题）

14.8 node.exe 崩溃（0xc0000005）

14.9 PowerShell 中脚本执行被阻止

14.10 引导向导安全提示自动选择 No

14.11 ollama launch openclaw 中模型连接失败

14.12 网关无法启动

14.13 npm install 中内存不足

14.14 Discord 机器人连接失败（code 4014）

14.15 PowerShell 中输入 Discord Token 时报错

15. 安全注意事项

6. 费用

17. 结语

14.1 `openclaw` 命令无法识别

14.2 `ollama` 命令无法识别

14.6 `ollama` 命令无输出退出（system32 幽灵文件）

14.7 `ollama launch openclaw` 不支持（版本问题）

14.11 `ollama launch openclaw` 中模型连接失败