OpenClaw

概述

OpenClaw 是一款开源的个人 AI 助手网关，运行在你自己的设备上。它是一个多通道 AI 控制平面，将 AI 能力连接到你已有的消息平台。它的口号是"真正能干活的 AI"。

开发者：Peter Steinberger（@steipete）及社区
类型：开源软件
许可：MIT License
语言：TypeScript
GitHub：https://github.com/openclaw/openclaw
官网：https://openclaw.ai
文档：https://docs.openclaw.ai
Stars：362,815+

TIP

OpenClaw 不只是编码工具，它是完整的 AI 助手网关。你可以通过 WhatsApp、Telegram、Slack、Discord 等 20+ 消息平台与 AI 交互，完成编码、信息查询、任务自动化等。

系统要求

要求	说明
Node.js	v24（推荐）或 v22.16+
操作系统	macOS / Linux / Windows（需 WSL2，强烈推荐）
包管理器	npm / pnpm / bun
网络	需要互联网连接

可选组件：

macOS 菜单栏应用
iOS 节点应用
Android 节点应用
Docker

安装

Windows 用户请使用 WSL2 安装

OpenClaw 在 Windows 下运行需要 WSL2，强烈建议在 WSL2（Ubuntu 24.04）中安装使用：

powershell

# 1. 先安装 WSL2 + Ubuntu 24.04（PowerShell 管理员）
wsl --install -d Ubuntu-24.04

# 2. 进入 WSL2
wsl

# 3. 在 WSL2 中安装 OpenClaw
npm install -g openclaw@latest
openclaw onboard --install-daemon

# 4. 访问 Windows 磁盘文件
cd /mnt/d/projects/my-app
openclaw

通过 /mnt/磁盘号/ 路径访问 Windows 文件，如 /mnt/c/、/mnt/d/。

方式一：npm / pnpm / bun（推荐）

bash

# npm
npm install -g openclaw@latest

# pnpm
pnpm add -g openclaw@latest

# 安装后运行引导向导
openclaw onboard --install-daemon

方式二：Docker

bash

# 详见 https://docs.openclaw.ai/install/docker
docker run -d openclaw/openclaw

方式三：Nix

bash

# 使用 Nix 安装
# 详见 https://github.com/openclaw/nix-openclaw

方式四：从源码构建

bash

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm openclaw setup
pnpm ui:build
pnpm gateway:watch

认证配置

引导向导（推荐）

bash

openclaw onboard

交互式向导将引导你设置：

网关配置
工作区
消息通道
技能
模型认证

可选择不同的认证方式：

bash

# Anthropic API Key
openclaw onboard --auth-choice apiKey

# OpenAI API Key
openclaw onboard --auth-choice openai-api-key

# OpenAI Codex（OAuth）
openclaw onboard --auth-choice openai-codex

# Google Gemini API Key
openclaw onboard --auth-choice gemini-api-key

环境变量方式

环境变量	提供商
`OPENAI_API_KEY`	OpenAI
`ANTHROPIC_API_KEY`	Anthropic（Claude）
`GEMINI_API_KEY`	Google Gemini
`GROQ_API_KEY`	Groq
`XAI_API_KEY`	xAI（Grok）
`MISTRAL_API_KEY`	Mistral
`OPENROUTER_API_KEY`	OpenRouter
`HUGGINGFACE_HUB_TOKEN`	Hugging Face

API Key 轮换

支持多 Key 轮换和故障转移，优先级从高到低：

OPENCLAW_LIVE_<PROVIDER>_KEY（最高优先级）
<PROVIDER>_API_KEYS（逗号/分号分隔列表）
<PROVIDER>_API_KEY（主 Key）
<PROVIDER>_API_KEY_1、<PROVIDER>_API_KEY_2（编号 Key）

基础使用

启动网关

bash

openclaw gateway --port 18789 --verbose

通过消息通道交互

bash

# 发送消息
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# 与 AI 助手对话
openclaw agent --message "发布检查清单" --thinking high

诊断与配置

bash

# 健康检查
openclaw doctor

# 配置管理
openclaw configure
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"

# 模型管理
openclaw models list
openclaw models set <provider/model>
openclaw models status

# 配对安全
openclaw pairing approve <channel> <code>

# 更新
openclaw update --channel stable   # 稳定频道
openclaw update --channel beta     # 测试频道
openclaw update --channel dev      # 开发频道

聊天内命令

在对话中可使用以下斜杠命令：

命令	说明
`/status`	查看状态
`/new`	新建对话
`/reset`	重置对话
`/compact`	压缩上下文
`/think <level>`	设置思考级别
`/verbose on\|off`	切换详细模式
`/trace on\|off`	切换追踪模式
`/usage off\|tokens\|full`	切换用量显示
`/model`	查看当前模型
`/model list`	列出可用模型
`/model <provider/model>`	切换模型
`/models add <provider> <modelId>`	添加模型
`/restart`	重启

核心功能

多通道收件箱

支持 20+ 消息平台，统一的 AI 收件箱：

平台	类型
WhatsApp	即时通讯
Telegram	即时通讯
Slack	团队协作
Discord	社区/团队
Google Chat	企业协作
Signal	安全通讯
iMessage	Apple 生态
BlueBubbles	iMessage 桥接
IRC	传统聊天
Microsoft Teams	企业协作
Matrix	去中心化通讯
飞书/Lark	企业协作
LINE	亚洲即时通讯
Mattermost	自托管团队
Nextcloud Talk	自托管协作
Nostr	去中心化社交
Synology Chat	NAS 聊天
Tlon	Urbit 生态
Twitch	直播聊天
Zalo	越南即时通讯
微信（WeChat）	中国即时通讯
QQ	中国即时通讯
WebChat	网页聊天

多代理路由

将不同的通道/账户/联系人路由到隔离的代理，各自拥有独立的工作区和会话：

json5

{
  agents: {
    list: [
      {
        name: "coding-assistant",
        model: "anthropic/claude-opus-4-6",
        channels: ["slack-dev-channel"],
      },
      {
        name: "general-helper",
        model: "openai/gpt-5.4",
        channels: ["whatsapp", "telegram"],
      },
    ],
  },
}

语音唤醒 + 对话模式

macOS/iOS：语音唤醒词
Android：持续语音模式
使用 ElevenLabs + 系统 TTS 作为后备

Live Canvas

智能体驱动的可视化工作区，支持 A2UI（AI-to-UI）。

一等公民工具

浏览器 — 网页浏览和交互
Canvas — 可视化工作区
节点 — 分布式计算
Cron — 定时任务
会话 — 持久化对话
Discord/Slack 动作 — 平台集成

伴侣应用

macOS 菜单栏应用 — 快速访问
iOS 节点 — 移动端控制
Android 节点 — 移动端控制

技能市场

通过 ClawHub（https://clawhub.ai）发现和安装技能：

内置技能
社区技能
自定义工作区技能

沙箱

为非主会话提供隔离执行环境：

Docker 沙箱
SSH 沙箱
OpenShell 沙箱

模型故障转移

认证档案轮换
冷却时间
故障转移链

热重载配置

对 openclaw.json 的修改自动应用，无需重启。

配置

配置文件位置

~/.openclaw/openclaw.json（JSON5 格式，支持注释和尾逗号）

最小配置

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
    },
  },
}

模型配置

json5

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
}

编辑方式

openclaw onboard / openclaw configure（交互式向导）
openclaw config get/set/unset（CLI 命令行）
控制面板 UI：http://127.0.0.1:18789（网页表单 + 原始 JSON 编辑器）
直接编辑文件（热重载）

关键配置项

json5

{
  // 代理默认配置
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-6",
      workspace: "~/.openclaw/workspace",
      sandbox: "docker",
      skills: ["default"],
      heartbeat: {
        every: "2h",
      },
    },
    list: [
      {
        name: "coding-agent",
        model: "anthropic/claude-opus-4-6",
        groupChat: { enabled: true },
      },
    ],
  },

  // 通道配置
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      dmPolicy: "pairing",
    },
    slack: {
      botToken: "xoxb-xxxxx",
      allowFrom: ["C0XXXXXX"],
    },
    telegram: {
      botToken: "xxxxx:xxxxx",
      allowFrom: [123456789],
    },
  },

  // 自定义模型提供商
  models: {
    providers: {
      "my-custom": {
        baseURL: "https://api.example.com/v1",
        apiKeyEnv: "MY_CUSTOM_API_KEY",
      },
    },
  },

  // 会话配置
  session: {
    dmScope: "per-peer",
    threadBindings: true,
    dailyReset: false,
  },

  // 网关配置
  gateway: {
    port: 18789,
    healthCheck: true,
    staleThreshold: "5m",
    restartLimits: { maxRestarts: 3, window: "10m" },
  },
}

配置验证

严格 Schema 验证，未知键会导致网关拒绝启动
保留最后已知良好配置备份机制
使用 openclaw doctor 检查配置问题

支持的 AI 模型

内置提供商

提供商	认证	示例模型
OpenAI	`OPENAI_API_KEY`	`openai/gpt-5.4`
Anthropic	`ANTHROPIC_API_KEY`	`anthropic/claude-opus-4-6`
OpenAI Codex (OAuth)	ChatGPT OAuth	`openai-codex/gpt-5.4`
Google Gemini	`GEMINI_API_KEY`	`google/gemini-3-flash-preview`
Google Vertex	gcloud ADC	`google-vertex/gemini-2.5`
Z.AI (GLM)	`ZAI_API_KEY`	`zai/glm-5.1`
xAI	`XAI_API_KEY`	`xai/grok-4`
Mistral	`MISTRAL_API_KEY`	`mistral/mistral-large-latest`
Groq	`GROQ_API_KEY`	Groq 模型
OpenRouter	`OPENROUTER_API_KEY`	`openrouter/auto`
Hugging Face	`HUGGINGFACE_HUB_TOKEN`	`huggingface/deepseek-ai/DeepSeek-R1`
Qianfan	`QIANFAN_API_KEY`	`qianfan/deepseek-v3.2`
NVIDIA	`NVIDIA_API_KEY`	NVIDIA 模型
Cerebras	`CEREBRAS_API_KEY`	`cerebras/zai-glm-4.7`
GitHub Copilot	`COPILOT_GITHUB_TOKEN`/`GH_TOKEN`	Copilot 模型
MiniMax	`MINIMAX_API_KEY`	`minimax/MiniMax-M2.7`
Moonshot	`MOONSHOT_API_KEY`	`moonshot/kimi-k2.6`
Kimi Coding	`KIMI_API_KEY`	`kimi/kimi-code`
StepFun	`STEPFUN_API_KEY`	`stepfun/step-3.5-flash`
Together	`TOGETHER_API_KEY`	`together/moonshotai/Kimi-K2.5`
BytePlus	`BYTEPLUS_API_KEY`	`byteplus-plan/ark-code-latest`
Volcano Engine	`VOLCANO_ENGINE_API_KEY`	`volcengine-plan/ark-code-latest`
Xiaomi	`XIAOMI_API_KEY`	`xiaomi/mimo-v2-flash`
Cloudflare AI Gateway	`CLOUDFLARE_AI_GATEWAY_API_KEY`	—
Vercel AI Gateway	`AI_GATEWAY_API_KEY`	`vercel-ai-gateway/...`
Kilo Gateway	`KILOCODE_API_KEY`	`kilocode/kilo/auto`

自定义提供商

任何 OpenAI/Anthropic 兼容的代理都可以通过 models.providers 配置添加。

通道插件生态系统

npm 上有 6,763+ 个通道插件，包括：

插件	用途
`@tencent-weixin/openclaw-weixin`	微信通道
`@larksuite/openclaw-lark`	飞书/Lark 通道
`@ollama/openclaw-web-search`	Ollama 网页搜索
`@wecom/wecom-openclaw-cli`	企业微信 CLI
`coze-openclaw-plugin`	Coze 工具
`@tloncorp/tlon-skill`	Tlon/Urbit 技能

安全模型

DM 安全默认值

默认使用配对访问控制
新通道/联系人需要通过 openclaw pairing approve 授权

沙箱支持

为非主会话提供隔离执行：

Docker 沙箱
SSH 沙箱
OpenShell 沙箱

诊断

bash

# 检查配置和安全问题
openclaw doctor

# 配对管理
openclaw pairing approve <channel> <code>
openclaw pairing list
openclaw pairing revoke <channel>

常见工作流

编程辅助

bash

# 通过消息通道
> 帮我写一个 Python 的 REST API，使用 FastAPI

# 通过 CLI
openclaw agent --message "为用户模型编写 CRUD API" --thinking high

多通道消息

bash

# WhatsApp
openclaw message send --to +1234567890 --message "部署完成"

# Slack
openclaw message send --channel slack --to "#general" --message "新版本已发布"

定时任务

json5

{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h",
        message: "检查未完成的工作",
      },
    },
  },
}

会话管理

json5

{
  session: {
    dmScope: "per-peer",            // 每个联系人独立会话
    threadBindings: true,           // 线程绑定
    dailyReset: false,              // 每日重置
  },
}

控制面板

Web 控制面板运行在 http://127.0.0.1:18789，提供：

表单化配置编辑
原始 JSON 编辑器
通道管理
代理管理
模型切换
会话监控

故障排查

bash

# 运行诊断
openclaw doctor

# 启动网关并查看详细日志
openclaw gateway --port 18789 --verbose

# 检查模型状态
openclaw models status

# 常见问题
# - 配置文件错误：使用 openclaw doctor 检查
# - 通道连接失败：检查 API Key 和网络
# - 模型不可用：检查 provider 配置和 API 余额
# - WSL2 问题：确保 Node.js 版本正确
# - 热重载不生效：检查 JSON 语法是否正确

OpenClaw ​

概述 ​

系统要求 ​

安装 ​

方式一：npm / pnpm / bun（推荐） ​

方式二：Docker ​

方式三：Nix ​

方式四：从源码构建 ​

认证配置 ​

引导向导（推荐） ​

环境变量方式 ​

API Key 轮换 ​

基础使用 ​

启动网关 ​

通过消息通道交互 ​

诊断与配置 ​

聊天内命令 ​

核心功能 ​

多通道收件箱 ​

多代理路由 ​

语音唤醒 + 对话模式 ​

Live Canvas ​

一等公民工具 ​

伴侣应用 ​

技能市场 ​

沙箱 ​

模型故障转移 ​

热重载配置 ​

配置 ​

配置文件位置 ​

最小配置 ​

模型配置 ​

编辑方式 ​

关键配置项 ​

配置验证 ​

支持的 AI 模型 ​

内置提供商 ​

自定义提供商 ​

通道插件生态系统 ​

安全模型 ​

DM 安全默认值 ​

沙箱支持 ​

诊断 ​

常见工作流 ​

编程辅助 ​

多通道消息 ​

定时任务 ​

会话管理 ​

控制面板 ​

故障排查 ​

OpenClaw

概述

系统要求

安装

方式一：npm / pnpm / bun（推荐）

方式二：Docker

方式三：Nix

方式四：从源码构建

认证配置

引导向导（推荐）

环境变量方式

API Key 轮换

基础使用

启动网关

通过消息通道交互

诊断与配置

聊天内命令

核心功能

多通道收件箱

多代理路由

语音唤醒 + 对话模式

Live Canvas

一等公民工具

伴侣应用

技能市场

沙箱

模型故障转移

热重载配置

配置

配置文件位置

最小配置

模型配置

编辑方式

关键配置项

配置验证

支持的 AI 模型

内置提供商

自定义提供商

通道插件生态系统

安全模型

DM 安全默认值

沙箱支持

诊断

常见工作流

编程辅助

多通道消息

定时任务

会话管理

控制面板

故障排查