OpenClaw：跑在你自己设备上的开源 AI 助手完整中文翻译

一、官方信息表

二、官方图

OpenClaw 是一个开源 AI 助手，它运行在你自己的电脑上，并在你已经在使用的聊天渠道里与你碰面：Discord、iMessage、Slack、Teams、Telegram、WhatsApp，以及另外 20 多种消息平台，同时还提供 macOS、iOS、Android、Windows 和 Linux 的原生客户端。同一个 Gateway（网关）既可以在笔记本电脑上当作个人助手运行，也可以作为团队共享部署运行——两者之间唯一的区别只是配置。

它属于你，没有任何附加条件。 会话状态、记忆和凭证都存放在你自己的硬件上。模型与智能体运行时（Claude、Codex、本地模型）都是可以替换的插件，更换它们不需要改动其他任何东西。你的提示词只会发送给你配置的模型供应商和聊天平台，以及你自己主动开启的诊断导出；默认情况下 OpenClaw 自身每天只做一次版本检查，匿名功能统计是可选开启的，把 update.checkOnStart 设为 false 就会把这两项全部关掉（官方对具体上报内容有完整说明）。OpenClaw 由独立的 501(c)(3) 非营利组织 OpenClaw Foundation 托管治理，没有付费档位、没有托管服务、也没有代币。这套架构主张——可信网关、不可信执行、策略由代码强制——完整记录在为什么选择 OpenClaw 一文中。

OpenClaw 由 Peter Steinberger 与社区为「Molty」——一只太空龙虾形象的 AI 助手——而打造，小龙虾图标正是这个项目的彩蛋文化。社区贡献非常活跃，官方欢迎 AI 辅助编写的 PR；新功能通常做成基于插件 SDK 的独立插件，再通过 ClawHub 共享分发。发现安全漏洞请通过 SECURITY.md 私下报告，不要发到公开 Issue 区。

三、环境要求与前置条件

在开始安装之前，请先确认以下环境。OpenClaw 官方要求的运行时是 Node.js 24.22.1 以上，或 26.12.1 以上，其中推荐使用 Node 26。如果你使用官方安装脚本，脚本会在检测到系统缺少 Node 时自动为你准备好一个受支持的运行时：macOS 上自动安装 Node 26，Linux 上自动安装 Node 24 LTS。只有当你打算从源码构建时才需要额外安装 pnpm。

操作系统方面，OpenClaw 支持 macOS、Linux 和 Windows。Windows 用户既可以选择原生 Windows Hub 应用、PowerShell 命令行安装脚本，也可以在 WSL2 里运行 Gateway。

另外一个重要前置条件是：你需要已有 Claude Code 或 Codex CLI 的登录态，或者至少有一个模型供应商的 API Key——引导流程可以直接复用这些已有的登录凭证，省去手动配置的麻烦。可以用 node --version 命令确认当前 Node 版本。

四、部署步骤（全部安装路径）

4.1 一键安装脚本（推荐）

安装脚本支持 macOS、Linux 和 Windows，它会自动探测操作系统、在需要时安装 Node.js 运行时、装好 OpenClaw 并自动启动引导向导。

macOS / Linux / WSL2 用户执行：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell 用户执行：

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

如果你想跳过引导直接静默安装，可以在 macOS/Linux 下加上 --no-onboard 参数：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Windows 下对应的写法是：

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

4.2 桌面应用下载

不喜欢命令行的用户可以直接下载桌面伴侣应用。Windows 官方推荐使用原生签名安装包 OpenClaw Companion，提供 x64 和 arm64 两个版本，下载地址分别是 OpenClawCompanion-Setup-x64.exe 和 OpenClawCompanion-Setup-arm64.exe，所有发布版本都在 Windows Hub 发布页。macOS 用户则从 OpenClaw GitHub Releases 下载 OpenClaw-<version>.dmg（首选）或 .zip 安装后启动 OpenClaw.app。两款原生桌面应用在首次启动时都可以本地初始化一个 Gateway，也可以直接连接一个已有的远程 Gateway。

4.3 手动包管理器安装

如果你自己管理 Node.js 环境，可以直接安装发布好的 npm 包。npm 12 或 npm 11.16 及以上版本执行：

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

需要特别说明的是：npm 12 默认会拦截未经批准的包生命周期脚本，--allow-scripts=openclaw 这个参数就是显式允许 OpenClaw 的 preinstall 和 postinstall 步骤运行；在 npm 11.15 及更早版本上既没有这个拦截策略也没有这个参数，所以必须把该参数去掉。

pnpm 用户执行：

pnpm add -g --allow-build=openclaw openclaw@latest
openclaw onboard --install-daemon

Bun 用户执行（需要 Bun 1.4.4 以上）：

bun add -g --trust openclaw@latest
bun run --bun openclaw onboard --install-daemon --daemon-runtime bun

4.4 从源码构建

仓库本身是一个 pnpm workspace，在仓库根目录直接跑 npm install 是不支持的。完整步骤如下：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
pnpm install
pnpm build
pnpm ui:build
pnpm add --global "openclaw@link:$PWD"
openclaw onboard --install-daemon

其中 pnpm add --global "openclaw@link:$PWD" 会把命令行工具链接到当前检出的源码目录，而不改动包文件本身。如果只是在服务器上运行 OpenClaw 而不做开发，可以用 pnpm build:runtime 只构建 JavaScript、插件、Control UI 和元数据，跳过 TypeScript 声明文件。

4.5 容器与其他部署方式

OpenClaw 还官方支持 Docker 容器部署（需要 Docker Desktop 或 Docker Engine 加上 Docker Compose v2，本地源码构建镜像至少需要 6GB 内存）、Nix flake 声明式安装、Ansible 批量部署、Podman 无根容器，以及 Kubernetes、云服务器 VPS、Render、Cloudflare Containers 等多种云端部署路径。Docker 场景下常用命令如下：

docker compose pull openclaw-gateway openclaw-cli
docker compose stop openclaw-gateway
docker compose up -d openclaw-gateway

容器内还可以通过 docker compose run --rm openclaw-cli dashboard --no-open、docker compose run --rm openclaw-cli channels login 等子命令完成后台初始化与渠道登录。

五、使用方法

5.1 五分钟跑通第一次对话

README 里的官方文档导航表，按目标分为六类：配置模型与认证从「Models」和「Model providers」两篇开始；接入消息服务从「Channels」开始；添加工具、技能和插件则看「Tools」「Skills」「Plugins」以及插件市场 ClawHub；运行应用与设备节点看「Platforms」和「Nodes」；使用命令行与聊天指令看「CLI reference」和「Slash commands」；配置或运维 Gateway 则从「Configuration」「Architecture」「Updating」「Release channels」四篇入手。

5.2 五分钟跑通第一次对话

全新安装时，安装脚本会自动启动引导向导并打开浏览器。如果你是通过 npm、pnpm 或 Bun 直接装的包，则手动执行：

openclaw onboard --install-daemon

引导流程会自动验证模型访问权限、创建工作区、配置 Gateway。更省事的方式是直接一行命令体验：

npx openclaw@latest

它会自动找到本机已有的 Claude Code 或 Codex 登录态或 API Key，用一次真实的模型调用验证凭证，保存配置并打开网页控制台。Gateway 此时在当前前台终端运行，按 Ctrl+C 不会丢失配置。

5.3 安装后台服务并验证

引导完成后，建议把 Gateway 安装成后台服务：

openclaw gateway install

这会在 macOS 上安装 LaunchAgent、在 Linux/WSL2 上安装 systemd 用户服务、在原生 Windows 上安装计划任务。随后验证运行状态：

openclaw gateway status
openclaw dashboard

正常情况下你会看到 Gateway 监听在 18789 端口，openclaw dashboard 会在浏览器里打开 Control UI 控制台，在对话框里发一条消息收到回复，就说明整个链路工作正常。

5.4 架构如何组合在一起

OpenClaw 的各个组件分工明确：Gateway 是本地控制平面，负责会话、工具、事件和所有渠道连接；Control UI、命令行 CLI 和终端 TUI 都连接到 Gateway 工作；Channels（渠道） 把助手接入 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage 等消息服务；Companion 应用和节点 则在受支持的平台上提供语音、Canvas、摄像头、屏幕和设备本地操作。OpenClaw 同时支持托管模型和本地模型，它的工具（Tools）、技能（Skills）和插件（Plugins）负责扩展助手能做的事情，新能力通常以插件形式开发并通过 ClawHub 分享。

5.5 安全须知

OpenClaw 明确要求：把收到的入站消息一律当作不可信输入处理。支持私聊的渠道默认会对陌生发送者发起配对请求，你需要用以下命令批准：

openclaw pairing approve <channel> <code>

主会话的工具默认直接运行在宿主机上，除非你专门配置了沙箱。在把其他用户接进来或把 Gateway 暴露到远程网络之前，务必先阅读官方的安全指南、暴露风险操作手册和沙箱指南。

5.6 常用运维命令

openclaw --version        # 确认 CLI 可用
openclaw doctor           # 检查并自动修复配置问题
openclaw triage           # 一键诊断并生成修复建议
openclaw gateway restart  # 重启 Gateway

5.7 出问题后的「60 秒快速排查通道」

官方文档给出了一条标准的排障阶梯，按顺序执行即可定位绝大多数问题。第一步先看整体状态：

openclaw status

它会快速汇总操作系统与版本更新情况、Gateway/服务是否可达、智能体与会话、模型供应商配置以及运行时问题。第二步生成一份可以安全分享的只读报告：

openclaw status --all

这份报告带有日志尾部摘要，且所有令牌都会被自动脱敏。第三步确认守护进程与端口状态：

openclaw gateway status

它会展示监督进程运行状态、RPC 可达性、检查目标 URL 以及服务实际使用的配置文件。如果 Gateway 可达，可以继续做深度健康检查：

openclaw status --deep

它会对 Gateway 做实时健康探测，并在支持时顺带检查各渠道连通性。需要看最新日志时执行：

openclaw logs --follow

如果 RPC 通道已经中断，可以直接回落到底层日志文件，例如 /tmp/openclaw/openclaw-2026-10-28.log 这类按天命名的文件。最后执行 openclaw doctor 修复或迁移配置与状态，再跑一遍健康检查即可收尾。

六、常见问题（FAQ）

问：为什么提示 openclaw: command not found？ 几乎都是 PATH 问题——npm 的全局 bin 目录不在你 shell 的 PATH 里。依次运行 node -v（确认 Node 已安装）、npm prefix -g（查看全局包目录）、echo "$PATH"（确认 bin 目录在路径中）即可定位。

问：配置不工作怎么办？ 执行 openclaw triage，它会跑一轮只读健康检查，生成一份脱敏后的诊断提示，并且可以直接把这份提示交给你机器上的编码代理（Claude Code、Codex CLI 或内置 OpenClaw 代理）处理。在你选择代理之前，任何内容都不会离开你的机器，密钥、令牌、原始聊天负载和原始日志都会从提示中排除。

问：有哪些环境变量可以自定义？ 以服务账号运行或想自定义路径时，可以设置 OPENCLAW_HOME（内部路径解析的主目录）、OPENCLAW_STATE_DIR（覆盖状态目录）、OPENCLAW_CONFIG_PATH（覆盖配置文件路径）三个变量。

问：如何更新 OpenClaw？ 推荐用 openclaw update 命令；包安装和 git 安装之间可以通过 openclaw update --channel stable 和 openclaw update --channel dev 切换。更新后记得跑一次 openclaw doctor 并重启 Gateway 验证。

问：OpenAI 是不是项目的所有者？ 不是。OpenClaw 由独立的 OpenClaw Foundation 公开开发，基金会雇佣核心团队并签署发布版本，捐款人和基础设施赞助商（包括 Amazon、OpenAI、Red Hat、密歇根大学等）支持基金会，但没有任何一方拥有或指挥这个项目。

问：设置了 ANTHROPIC_API_KEY 之后，默认用哪个模型？ 凭证和模型选择是两回事。设置 ANTHROPIC_API_KEY 只是完成了认证，真正的默认模型由 agents.defaults.model.primary 配置决定，例如 anthropic/claude-sonnet-4-6。如果报错 No credentials found for profile "anthropic:default"，说明 Gateway 在可用的 SQLite 认证存储里找不到 Anthropic 凭证。

问：Gateway 默认监听哪个端口？ 默认监听 18789 端口。如果出现 another gateway instance is already listening 提示，说明同一台机器上已经有另一个 Gateway 实例占用了该端口；官方支持在同一台主机上运行多个 Gateway，但需要为不同实例配置不同的端口与工作目录。

问：我能远程在另一台 VPS 上跑 Gateway、本地电脑只当客户端吗？ 可以，这就是官方推荐的远程模式（remote mode）。把 Gateway 部署在云服务器上，在本地电脑安装节点（node）或客户端即可连接，节点可以在你自己的电脑上执行本地操作（语音、摄像头、屏幕等），而对话和调度都在远程 Gateway 上完成。官方同时提供了 Tailscale 组网的完整指南。

问：记忆和会话数据存在哪里？ 所有状态、记忆和凭证都存放在你自己的硬件上，默认位于工作区目录下；可以通过 OPENCLAW_STATE_DIR 环境变量覆盖状态目录。官方文档提供了专门的备份与恢复策略，以及完全卸载的步骤。

问：如何开启网络搜索与网页抓取能力？ 在配置中启用 web search / web fetch 工具即可，具体开关项与 Brave 等浏览器控制的对接方式见官方配置基础文档；自定义浏览器也支持 headless 无头模式运行。

问：把助手暴露到聊天渠道里安全吗？ 官方安全文档的核心原则是：所有入站消息都按不可信输入处理，提示词注入不只是公开机器人的问题，私聊场景同样存在风险。支持私聊的渠道默认对陌生发送者执行配对审批，你需要显式批准 openclaw pairing approve 后对方才能对话。是否给助手短信、通讯录等敏感权限，完全由你授权，建议先用沙箱模式隔离验证第三方技能和插件再放开权限。

七、跳转链接

• 官方文档首页：docs.openclaw.ai
• 入门指南：Getting started
• 为什么选择 OpenClaw：Why OpenClaw
• 安装总览：Install
• 模型与认证配置：Models · Model providers
• 消息渠道接入：Channels
• 工具、技能与插件：Tools · Skills · Plugins · ClawHub
• CLI 参考：CLI reference
• 常见问题：FAQ
• 官方社区支持：community.openclaw.ai
• 问题反馈：GitHub Issues