OpenClaw 安装文档

作者：CSDN博客
本文介绍如何从零安装 OpenClaw（openclaw-cn），并完成首次配置与启动，便于后续接入多 Agent 协同。

---

一、环境要求

Node.js：建议 v18 或以上（需支持当前 LTS）npm：随 Node 安装即可操作系统：Windows / macOS / Linux 均可；本文示例以 Windows 为主，路径会标注差异网络：能访问 npm registry 及你将要使用的 LLM API（如 DeepSeek、OpenAI 等）

---

二、安装 OpenClaw

2.1 全局安装

1. npminstall-g openclaw-cn

复制代码

安装完成后，在终端执行 openclaw-cn --version 可确认版本。
2.2 配置目录（.openclaw）

OpenClaw 的配置与状态默认存放在用户目录下的 .openclaw 中：

Windows：C:\Users\你的用户名\.openclawmacOS / Linux：~/.openclaw

若未存在，首次运行相关命令（如 openclaw-cn onboard 或 openclaw-cn gateway）时会引导创建。

---

三、首次配置（向导）

推荐使用官方向导完成基础配置：

1. openclaw-cn onboard

复制代码

按提示可完成：

选择运行模式（本地 / 远程等）配置 LLM 提供商与 API Key（如 DeepSeek、OpenAI）生成或确认 Gateway 认证（密码或 token）创建默认 main Agent 与工作区

向导结束后，.openclaw 下会生成或更新 openclaw.json，以及 workspace/、agents/main/ 等目录。

---

四、核心配置文件 openclaw.json

主要结构说明（便于后续多 Agent 部署时对照）：

配置块	作用
agents	Agent 列表、默认模型、工作区与 agentDir 路径
gateway	端口、认证方式（password/token）、绑定地址
models / auth	LLM 提供商、模型、API Key 等
tools.agentToAgent	是否允许 Agent 之间互发消息（多 Agent 时必须开启）
channels	Discord 等渠道的 token、开关
cron	定时任务在 cron/jobs.json，此处多为开关或引用

注意：agents.list 中每一项的 workspace、agentDir 多为绝对路径。迁移到另一台电脑时，若 .openclaw 路径变化，需在 openclaw.json 中全局替换为新路径。

---

五、启动 Gateway

Gateway 是 OpenClaw 的本地服务，负责会话、工具调用与多 Agent 通信。安装并配置完成后需要先启动 Gateway：

1. openclaw-cn gateway

复制代码

默认会在本机监听一个端口（如 18789，以 openclaw.json 中 gateway.port 为准）。使用 Control UI（网页） 或 TUI（终端 UI） 时，需要连接到该 Gateway（本地一般为 http://127.0.0.1:18789 或 ws://127.0.0.1:18789）。若配置了 gateway.auth，打开网页或 TUI 时需输入密码或 token。

---

六、验证安装

Gateway 是否在跑：保持 openclaw-cn gateway 运行，或以后台/服务方式运行，确认端口可访问。TUI 连接：新开终端执行
openclaw-cn tui
若提示输入 Gateway 密码，输入你在 onboard 或配置里设置的密码，能进入 TUI 即表示连接正常。与 main 对话：在 TUI 或 Control UI 中给 main 发一条消息，能收到回复即说明单 Agent 流程正常。

---

七、配置 Discord（可选）

若希望通过 Discord 与 OpenClaw 对话（在频道或私聊中 @ 机器人即可），按以下步骤配置。
7.1 在 Discord 创建机器人并获取 Token

打开 Discord 开发者门户，登录后点击 New Application，填写应用名称（如 OpenClaw Bot）并创建。左侧进入 Bot，点击 Add Bot（若已有 Bot 则跳过）。在 TOKEN 区域点击 Reset Token 或 View Token，复制生成的 Bot Token（格式类似 MTQ3NjEz...xxx）。请妥善保管，不要泄露或提交到代码库。

• 在 Privileged Gateway Intents 中按需开启：
  
  Message Content Intent：必须开启，否则机器人无法读取消息正文。Server Members Intent / Presence Intent：仅当需要识别服务器成员或在线状态时再开启。
  
  保存更改（Save Changes）。
  

7.2 邀请机器人到你的服务器

开发者门户中，左侧进入 OAuth2 → URL Generator。SCOPES 勾选 bot。

• BOT PERMISSIONS 至少勾选：
  
  Read Messages/View ChannelsSend MessagesRead Message History若需在频道内回复，可勾选 Mention Everyone 或按需勾选 Manage Messages 等。
  
  复制页面底部生成的 Generated URL，在浏览器中打开，选择要邀请机器人的服务器并授权。邀请完成后，机器人在该服务器中可见；在任意有权限的频道中 @ 机器人即可触发对话（若已配置允许列表，需在允许的频道内）。
  

7.3 在 openclaw.json 中配置 Discord

编辑 .openclaw/openclaw.json，在顶层增加或修改 channels 与 bindings。
1）启用 Discord 并填入 Token
在 channels 下添加或修改 discord 段：

1. "channels":{"discord":{"enabled":true,"token":"你的_Bot_Token","groupPolicy":"allowlist"}}

复制代码

token：替换为你在 7.1 中复制的 Bot Token。

• groupPolicy：
  
  allowlist（推荐）：仅在「允许列表」内的服务器/频道中回复；需在 channels.discord.guilds 中配置允许的服务器 ID（及可选频道 ID），否则机器人不会在群组中响应。open：在所有加入的服务器中响应（慎用，易被滥用）。
  
  
  

若使用 allowlist，可进一步指定允许的服务器与频道，例如：

1. "channels":{"discord":{"enabled":true,"token":"你的_Bot_Token","groupPolicy":"allowlist","guilds":{"你的服务器ID":{"channels":["频道ID1","频道ID2"]}}}}

复制代码

不写 channels 则允许该服务器下所有频道。服务器 ID、频道 ID 可在 Discord 中开启「开发者模式」后右键服务器/频道复制 ID 获取。
2）绑定到 main Agent
在 bindings 中增加一条，把 Discord 消息路由到 main（或你希望接管的 Agent）：

1. "bindings":[{"agentId":"main","match":{"channel":"discord","accountId":"default","peer":{"kind":"channel","id":"目标频道ID"}}}]

复制代码

若希望 所有 Discord 消息都由 main 处理，可省略 peer 或按 openclaw-cn 文档使用更宽泛的 match。多 Agent 场景下，若希望某频道由总监（director）接管，可增加一条 "agentId": "director" 且 match.peer.id 为该频道 ID。

保存 openclaw.json 后，重启 Gateway（openclaw-cn gateway）使配置生效。
7.4 验证

在 Discord 中于已允许的频道内 @ 你的机器人并发送一条消息。若配置正确，机器人会回复（由 main 或你绑定的 Agent 处理）。若未回复，检查：Token 是否正确、Message Content Intent 是否开启、groupPolicy 与 guilds/channels 是否包含当前服务器与频道、Gateway 是否已重启。可执行 openclaw-cn channels status 或 openclaw-cn status --deep 查看渠道与 Gateway 状态。

---

八、下一步

单 Agent（main）可正常对话后，即可继续部署 多 Agent 协同（总监 + 写稿/设计/风控/发布等），详见《多 Agent 协同部署文档》。若需绑定 Telegram、Slack 等，可参考 openclaw-cn 官方渠道文档，在 openclaw.json 的 channels、bindings 中增加对应配置，并保证 Gateway 常驻运行。

---

九、常见问题

找不到 openclaw-cn 命令：确认 npm 全局 bin 目录在系统 PATH 中（npm list -g openclaw-cn 可看安装位置）。Gateway 启动报错：检查端口是否被占用、openclaw.json 是否合法 JSON、路径是否存在。API 调用失败：检查 auth、models 中的 API Key 与 baseUrl 是否正确，网络是否可达。Discord 机器人不回复：确认 Bot 的 Message Content Intent 已开启；channels.discord.token 正确；若使用 groupPolicy: "allowlist"，确认当前服务器/频道已在 guilds 中配置；修改配置后需重启 Gateway。

以上为 OpenClaw 的安装与首次使用说明，多 Agent 架构与流水线配置请见下一篇部署文档。

原文地址：https://blog.csdn.net/qq_54203750/article/details/158500022