OpenClaw 安装文档

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

未曾※放弃꿈

2356人浏览 · 2026-02-28 11:41:19

未曾※放弃꿈 · 2026-02-28 11:41:19 发布

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

一、环境要求

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

二、安装 OpenClaw

2.1 全局安装

npm install -g openclaw-cn

安装完成后，在终端执行 openclaw-cn --version 可确认版本。

2.2 配置目录（.openclaw）

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

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

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

三、首次配置（向导）

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

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：

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 Channels
- Send Messages
- Read Message History
- 若需在频道内回复，可勾选 Mention Everyone 或按需勾选 Manage Messages 等。
复制页面底部生成的 Generated URL，在浏览器中打开，选择要邀请机器人的服务器并授权。
邀请完成后，机器人在该服务器中可见；在任意有权限的频道中 @ 机器人即可触发对话（若已配置允许列表，需在允许的频道内）。

7.3 在 openclaw.json 中配置 Discord

编辑 .openclaw/openclaw.json，在顶层增加或修改 channels 与 bindings。

1）启用 Discord 并填入 Token

在 channels 下添加或修改 discord 段：

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

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

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

"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）：

"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。