概述

适用于任何操作系统的 AI 智能体 Gateway 网关

安装

命令

Node >=22
curl -fsSL https://openclaw.ai/install.sh | bash
Windows（PowerShell）：
iwr -useb https://openclaw.ai/install.ps1 | iex

安装器标志
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help

非交互式（跳过新手引导）：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

全局安装（手动）
如果已经有 Node：
npm install -g openclaw@latest

从源代码（贡献者/开发）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon

安装后

运行新手引导：openclaw onboard --install-daemon
快速检查：openclaw doctor
检查 Gateway 网关健康状态：openclaw status + openclaw health
打开仪表板：openclaw dashboard

配对 WhatsApp 并启动 Gateway 网关
openclaw channels login
openclaw gateway --port 18789v

安装器支持两种方式：
npm（默认）：npm install -g openclaw@latest
git：从 GitHub 克隆/构建并从源代码 checkout 运行

CLI 标志
显式 npm
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

从 GitHub 安装（源代码 checkout）
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

常用 CLI 标志：
--install-method npm|git
--git-dir <path>（默认：~/openclaw）
--no-git-update（使用现有 checkout 时跳过 git pull）
--no-prompt（禁用提示；CI/自动化中必需）
--dry-run（打印将要执行的操作；不做任何更改）
--no-onboard（跳过新手引导）

环境变量
等效的环境变量（对自动化有用）：
OPENCLAW_INSTALL_METHOD=git|npm
OPENCLAW_GIT_DIR=…
OPENCLAW_GIT_UPDATE=0|1
OPENCLAW_NO_PROMPT=1
OPENCLAW_DRY_RUN=1
OPENCLAW_NO_ONBOARD=1
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1（默认：1；避免 sharp 针对系统 libvips 构建）

故障排除：找不到 openclaw（PATH）
快速诊断

node -v
npm -v
npm prefix -g
echo "$PATH"

消息渠道

消息平台

QQ
https://q.qq.com/qqbot/openclaw/index.html
飞书

配置

私信配对（谁被允许与机器人对话）
节点配对（哪些设备/节点被允许加入 Gateway 网关网络）

渠道路由

OpenClaw 将回复路由回消息来源的渠道。
模型不会选择渠道；路由是确定性的，由主机配置控制。

关键术语
渠道：QQ 微信飞书。
AccountId：每个渠道的账户实例（在支持的情况下）。
AgentId：隔离的工作区 + 会话存储（“大脑”）。
SessionKey：用于存储上下文和控制并发的桶键。

会话键格式（示例）
私信会折叠到智能体的主会话：
agent::（默认：agent:main:main）
群组和渠道按渠道隔离：
群组：agent:::group:
渠道/房间：agent:::channel:
线程：
Slack/Discord 线程会在基础键后追加 :thread:。
Telegram 论坛主题在群组键中嵌入 :topic:。
示例：
agent:main:telegram:group:-1001234567890:topic:42
agent:main:discord:channel:123456:thread:987654

路由规则（如何选择智能体）
路由为每条入站消息选择一个智能体：
精确对端匹配（bindings 中的 peer.kind + peer.id）。
Guild 匹配（Discord）通过 guildId。
Team 匹配（Slack）通过 teamId。
账户匹配（渠道上的 accountId）。
渠道匹配（该渠道上的任意账户）。
默认智能体（agents.list[].default，否则取列表第一项，兜底为 main）。
匹配到的智能体决定使用哪个工作区和会话存储。

回复上下文
入站回复包含：
ReplyToId、ReplyToBody 和 ReplyToSender（在可用时）。
引用的上下文会以 [Replying to …] 块的形式追加到 Body 中。
这在所有渠道中保持一致。

渠道位置解析
OpenClaw 将聊天渠道中分享的位置标准化为：
附加到入站消息体的可读文本，以及
自动回复上下文负载中的结构化字段。
目前支持：
Telegram（位置图钉 + 地点 + 实时位置）
WhatsApp（locationMessage + liveLocationMessage）
Matrix（m.location 配合 geo_uri）

代理

基础

Pi 集成架构
Gateway 网关架构
智能体运行时
智能体循环
系统提示词
上下文
智能体工作区
OAuth

OpenClaw 如何与 pi-coding-agent 及其相关包（pi-ai、pi-agent-core、pi-tui）集成以实现其 AI 智能体能力。
OpenClaw 使用 pi SDK 将 AI 编码智能体嵌入到其消息 Gateway 网关架构中。
OpenClaw 不是将 pi 作为子进程生成或使用 RPC 模式，而是通过 createAgentSession() 直接导入并实例化 pi 的 AgentSession。
这种嵌入式方法提供了：

对会话生命周期和事件处理的完全控制
自定义工具注入（消息、沙箱、渠道特定操作）
每个渠道/上下文的系统提示自定义
支持分支/压缩的会话持久化
带故障转移的多账户认证配置文件轮换
与提供商无关的模型切换

包依赖

{
  "@mariozechner/pi-agent-core": "0.49.3",
  "@mariozechner/pi-ai": "0.49.3",
  "@mariozechner/pi-coding-agent": "0.49.3",
  "@mariozechner/pi-tui": "0.49.3"
}

包名	用途
`pi-ai`	核心 LLM 抽象：Model、streamSimple、消息类型、提供商 API
`pi-agent-core`	智能体循环、工具执行、AgentMessage 类型
`pi-coding-agent`	高级 SDK：createAgentSession、SessionManager、AuthStorage、ModelRegistry、内置工具
`pi-tui`	终端 UI 组件（用于 OpenClaw 的本地 TUI 模式）

工具

工具管道
基础工具：pi 的 codingTools（read、bash、edit、write）
自定义替换：OpenClaw 将 bash 替换为 exec/process，为沙箱自定义 read/edit/write
OpenClaw 工具：消息、浏览器、画布、会话、定时任务、Gateway 网关等
渠道工具：Discord/Telegram/Slack/WhatsApp 特定的操作工具
策略过滤：工具按配置文件、提供商、智能体、群组、沙箱策略过滤
Schema 规范化：为 Gemini/OpenAI 的特殊情况清理 Schema
AbortSignal 包装：工具被包装以尊重中止信号