OpenClaw 使用指南

安装 OpenClaw#

官方当前推荐的安装方式是 安装脚本。

macOS / Linux / WSL2#

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

Windows PowerShell#

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

文档里明确建议：Windows 场景优先用 WSL2。

系统要求#

根据官方最新文档：

• Node 22 或更高
• 支持 macOS、Linux、Windows
• 如果从源码运行，还需要 pnpm

第一次运行#

安装完成后，官方推荐直接执行引导命令：

openclaw onboard --install-daemon

这个命令会做几件事：

• 配置模型认证
• 配置 Gateway
• 初始化工作区
• 选择是否接入渠道
• 安装并启动守护进程

完成后，可以先检查 Gateway 状态：

openclaw gateway status

最快上手方式：先用浏览器 Control UI#

官方文档给出的最快路径是直接打开浏览器控制台：

openclaw dashboard

默认本地地址一般是：

http://127.0.0.1:18789/

最基础的使用方式#

1. 启动引导#

openclaw onboard --install-daemon

2. 检查 Gateway#

openclaw gateway status

3. 打开浏览器控制台#

openclaw dashboard

4. 前台运行 Gateway 做调试#

如果你想本地排查问题，可以直接前台启动：

openclaw gateway --port 18789

常见命令#

查看 Gateway 状态#

openclaw gateway status

停止 Gateway#

openclaw gateway stop

重启 Gateway#

openclaw gateway restart

打开浏览器控制台#

openclaw dashboard

查看日志#

openclaw logs --follow

运行诊断#

openclaw doctor

自动修复常见问题#

openclaw doctor --repair

给目标发送测试消息#

openclaw message send --target +1234567890 --message "Hello from OpenClaw"

直接让 agent 执行任务#

openclaw agent --message "Ship checklist" --thinking high

模型和认证怎么配#

官方推荐的方式仍然是：优先在 openclaw onboard 里做认证。

如果后面要补充新的模型提供商，也可以直接走命令：

openclaw models auth login --provider <provider-id>

例如 OpenAI Codex 这类支持 OAuth 的提供商，可以直接接入；
Anthropic 则更建议走 API Key 路线，而不是依赖订阅兼容方案。

模型选择本身由 OpenClaw 的模型配置控制。
文档建议把主模型设成能用到的最强一档，再给低成本场景加 fallback。

OpenClaw 的核心概念#

1. Gateway#

Gateway 是 OpenClaw 的核心守护进程。
它会长期运行，统一管理：

• 消息渠道
• 模型调用
• 会话
• 技能
• 插件
• 控制 UI

它默认监听本地 127.0.0.1:18789。

2. Workspace#

OpenClaw 的工作区默认在：

~/.openclaw/workspace

官方文档明确强调：把它当作 agent 的私有记忆空间。
它和 ~/.openclaw/ 不是一回事：

• ~/.openclaw/ 放配置、凭据、会话状态
• ~/.openclaw/workspace 放 agent 工作区、技能、记忆和长期上下文

3. Skills#

OpenClaw 的技能本质上是 SKILL.md 驱动的能力包，兼容 AgentSkills 格式。

常见位置有：

• bundled skills：安装自带
• ~/.openclaw/skills
• <workspace>/skills

如果同名技能冲突，工作区里的优先级最高。

4. Plugins#

OpenClaw 的扩展能力大量通过插件提供。
插件可以注册：

• Gateway RPC
• HTTP 路由
• Agent 工具
• CLI 命令
• 后台服务
• 技能目录

查看当前插件：

openclaw plugins list

安装官方插件示例：

openclaw plugins install @openclaw/voice-call

启用插件示例：

openclaw plugins enable open-prose

Slash Commands 怎么用#

OpenClaw 支持两套命令体系：

• /... slash commands
• ! <cmd> 主机 bash 命令

比较常见的 slash commands / directives 包括：

• /help
• /commands
• /status
• /model
• /compact
• /tts

而 bash 相关命令常见的是：

! <command>
!poll
!stop

其中 ! <command> 更接近“让宿主机执行一个命令”。

配置文件在哪里#

OpenClaw 的主配置文件是：

~/.openclaw/openclaw.json

它实际支持的是 JSON / JSON5 风格配置。
官方文档里提到，很多情况下不用直接手改，而是优先用：

openclaw onboard
openclaw configure
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"

这样更不容易把配置搞乱。

安全方面#

OpenClaw 不是普通的聊天玩具，它会接真实渠道、真实设备、真实自动化能力，所以安全一定要注意。

1. Dashboard 是管理面#

官方文档明确写了，Control UI 是一个 admin surface。
不要随便公开暴露到公网。

更稳妥的方式是：

• 本机 localhost
• Tailscale
• SSH 隧道

2. 工作区不是硬沙箱#

文档里特别说明：workspace 只是默认 cwd，不等于绝对隔离。
如果要强隔离，要单独启用 sandbox 配置。

3. 工作区建议私有 Git 备份#

OpenClaw 官方建议把 workspace 当成私有记忆，用 私有仓库 备份。
但注意不要把 secrets 一起提交进去。

4. 不认识的插件和技能别乱装#

因为插件和 skills 都能扩展 agent 的工具面，来源不明的第三方扩展要谨慎启用。

一个最小上手流程#

第一次使用，建议按这个顺序来：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

确认浏览器里能连上 Control UI 以后，再决定是否继续：

• 接入 Telegram / Discord / WhatsApp
• 配置模型
• 加 skills
• 装 plugins

升级和维护#

OpenClaw 官方更新文档里反复强调一件事：
升级后优先跑 openclaw doctor。

最实用的维护习惯是：

openclaw doctor
openclaw gateway status
openclaw logs --follow

如果发现配置漂移、旧服务残留、认证异常或危险 DM 策略，doctor 会给出修复建议。