OpenClaw 完全新手指南

🚀 什么是 OpenClaw？

OpenClaw 是一款个人 AI 助手，运行在你自己的设备上。它可以通过你已经在使用的通讯渠道（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat 等）与你交互，还支持语音对话、Canvas 可视化等高级功能。

OpenClaw 是一个本地优先的 AI 助手网关，它的核心设计理念是：

个人化：为你个人服务，而非企业级多用户系统

本地运行：Gateway 运行在你的设备上（macOS、Linux、Windows WSL2）

多渠道接入：支持几乎所有主流通讯平台

功能丰富：浏览器控制、Canvas 可视化、语音交互、定时任务等

架构概览

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / WebChat               │               ▼┌───────────────────────────────┐│            Gateway            ││       (控制平面 - 核心)        ││     ws://127.0.0.1:18789      │└──────────────┬────────────────┘               │               ├─ AI 智能体 (Agent)               ├─ CLI 命令行工具               ├─ WebChat 网页界面               ├─ macOS/iOS/Android 客户端               └─ 浏览器控制 (Chrome CDP)

📦 安装指南

系统要求

Node.js ≥ 22（必须）操作系统：macOS、Linux、Windows (WSL2)包管理器：npm、pnpm 或 bun

快速安装（推荐）

macOS / Linux

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

Windows (PowerShell)

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

npm 安装

使用 npmnpm install -g openclaw@latest# 或使用 pnpmpnpm add -g openclaw@latest

运行引导向导

完整安装向导 + 安装系统服务openclaw onboard --install-daemon # 仅运行配置向导openclaw onboard# 查看 Gateway 状态openclaw gateway status# 打开控制面板openclaw dashboard

⚡ 快速开始

1. 启动 Gateway

前台运行（适合调试）openclaw gateway --port 18789 --verbose# 使用守护进程（后台运行）openclaw gateway start

2. 打开控制面板

openclaw dashboard或直接在浏览器访问：http://127.0.0.1:18789

3. 发送测试消息

openclaw message send --to +15555555555 --message "Hello from OpenClaw"

4. 与智能体对话

命令行直接对话openclaw agent --message "帮我总结今天的会议" --thinking high

📁 Workspace 工作空间

Workspace 是 OpenClaw 智能体的工作目录，也是它读取上下文、保存记忆、执行工具操作的唯一位置。

Workspace 结构

~/.openclaw/├── openclaw.json 主配置文件├── workspace/ # 默认工作空间│ ├── AGENTS.md # 操作指令和记忆│ ├── SOUL.md# 人格、边界、语气│ ├── TOOLS.md # 工具使用笔记│ ├── IDENTITY.md # 助手名称/头像/表情│ ├── USER.md # 用户信息│ ├── MEMORY.md # 长期记忆（仅主会话加载）│ └── skills/# 工作空间级技能├── agents/ # 多智能体会话存储├── skills/ # 全局技能└── credentials/# 凭证存储

核心文件说明

文件	用途	加载时机
`AGENTS.md`	操作指令、连续性规则、重要记忆	每会话首条消息
`SOUL.md`	人格定义、语气、边界	每会话首条消息
`TOOLS.md`	环境特定的工具说明	每会话首条消息
`USER.md`	用户信息、偏好、项目背景	每会话首条消息
`IDENTITY.md`	助手身份（名称、表情、头像）	每会话首条消息
`MEMORY.md`	长期记忆（安全敏感内容）	仅主会话

🧩 技能安装

OpenClaw 使用技能系统来扩展功能。技能是可复用的功能模块，可以通过 ClawHub CLI 从安装。

Skills三层查找法：

第一级：项目专属技能（最高优先级）

~/.openclaw/workspace/skills

适用场景：只在当前项目中使用的技能。

第二级：用户通用技能

~/.openclaw/skills

适用场景：跨项目共享的技能。

第三级：系统内置技能（最低优先级）

OpenClaw 自带的技能，比如 github、memory、summarize 等 52 个。不需要安装，开箱即用

💡技能让你可以一键添加新能力，如图像生成、天气查询、GitHub 操作、视频处理等，无需手动配置每个工具。

安装 ClawHub CLI

npm install -g clawhub

安装技能

找到想要的技能后，使用以下命令安装：

通过 ClawdHub（推荐）

clawhub install self-improving-agent

Manual（手动安装）

git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent

管理技能

命令	说明	示例
`clawhub list`	列出已安装的技能	查看当前工作空间的所有技能
`clawhub update <skill>`	更新指定技能到最新版本	`clawhub update weather`
`clawhub update --all`	更新所有技能	批量更新所有已安装技能
`clawhub update --force`	强制更新（忽略版本检查）	解决版本冲突时使用

常用推荐技能

1、安全防护（最优先）

技能名称	功能	安装命令
skill-vetter	安装任何技能前自动检查安全性	clawhub install skill-vetter
ClawSec	完整安全套件：drift 检测、安全审计、技能完整性验证	clawhub install clawsec
backup	备份 OpenClaw 配置	clawhub install openclaw-backup

2、搜索与研究

tavily-search

AI 优化搜索引擎，专为 agent设计

clawhub install

openclaw-tavily-search

Summarize

从 URL/播客/本地文件提取摘要（97.6K 下载，官方内置）

clawhub install summarize

find-skills

用户问“怎么做x"时自动搜索并推荐可安装的技能

clawhub install find-skills-skill

3、编程开发

frontend-design	打造独特的生产级前端界面，避免千篇一律的“AI 粗糙”美学	clawhub install frontend-design-3
GitHub	GitHub 全套操作：issues/PRs/CI（10K下载）	clawhub install github
coding-agent	运行Codex/Claude Code/OpenCode 等编程助手	clawhub install agentic-coding

4、自动化与工作流

agent-browser	无头浏览器自动化 CLI 优化，针对 AI 代理	clawhub install agent-browser-clawdbot
GOG	Google workspace全家桶: Gmail/Calendar/Drive/Sheets/Docs（14K 下载）	clawhub install gog
n8n	跨平台自动化集成（连接n8n 实例）	clawhub install n8n

5、生产力

Mission Control	AI Agent编排仪表盘，多 agent任务管理	clawhub install openclaw-mission-control
self-improving-agent	记录错误/纠正/学习到Markdown, 持续改进agent 表现	clawhub install self-improving-agent
`video-frames`	视频帧提取和剪辑	`clawhub install video-frames`

技能工作原理

技能是包含以下内容的文件夹：

SKILL.md 结构：├── YAML Frontmatter（元数据）│   ├── name + description（必填）│   ├── version│   └── metadata.openclaw（运行时需求）│       ├── requires（依赖声明）│       ├── install（自动安装规格）│       └── emoji / os / always 等└── Markdown Body（指令正文）    ├── 触发条件    ├── 工作流步骤    └── 注意事项

✅安装后，OpenClaw 会自动识别技能能力，并在相关任务触发时自动调用。无需额外配置。

⌨️ 常用 CLI 命令

Gateway 管理

查看状态openclaw gateway status# 启动/停止/重启openclaw gateway startopenclaw gateway stopopenclaw gateway restart

配置管理

运行配置向导openclaw onboard# 获取/设置配置值openclaw config get agents.defaults.workspaceopenclaw config set agents.defaults.model.primary "openai/gpt-5.2"

诊断工具

健康检查openclaw doctor# 自动修复openclaw doctor --fix# 查看日志openclaw logs --follow

🔒 安全最佳实践

官方60秒安全基线

为什么需要这个基线？OpenClaw 默认配置优先考虑"开箱即用”，而非安全。这意味着 Gateway 可能无鉴权、工具权限全开、DM 通道不设限。下面这段配置一次性覆盖最关键的攻击面——Gateway 鉴权、工具最小权限、消息通道管控，是投入产出比最高的单次操作。

~/.openclaw/openclaw.json：

解决什么： bind: "loopback" 限制只有本机能连；auth.mode: "token" 要求每次请求携带密钥，防止未授权访问。不设置等于裸奔。

{  gateway: {    mode: "local",    bind: "loopback",    auth: { mode: "token", token: "replace-with-long-random-token" }  }

解决什么： deny 列表禁用高危工具组；exec.security: "deny" 禁止命令执行；fs.workspaceOnly: true 限制文件访问范围；elevated: false 禁止提权。最小权限原则：只给 Agent 它真正需要的能力。

  tools: {    profile: "messaging",    deny: ["group:automation", "group:runtime", "group:fs",           "sessions_spawn", "sessions_send"],    fs: { workspaceOnly: true },    exec: { security: "deny", ask: "always" },    elevated: { enabled: false }  }

解决什么： dmPolicy: "pairing" 要求配对确认才能建立对话；requireMention: true 在群组中必须 @提及才响应，防止 Agent 被群消息意外触发。

{  channels: {    whatsapp: {      dmPolicy: "pairing",      groups: { "*": { requireMention: true } }    }  },  session: { dmScope: "per-channel-peer" }}

生成token：

openclaw doctor --generate-gateway-token

🔧 故障排除

错误	原因	解决
`Config validation failed`	配置格式错误	运行 `openclaw doctor`
`Unauthorized`	API Key 无效	检查 `auth` 配置
`Session not found`	会话已过期	发送 `/new` 重置

🔗 资源链接

官网:https://openclaw.ai/

文档:https://docs.openclaw.ai/start/getting-started

GitHub:https://github.com/openclaw/openclaw

技能市场:https://clawhub.ai/

📝 总结

OpenClaw 是一个功能强大、灵活的个人 AI 助手平台。关键要点：

Gateway是核心- 所有功能都围绕 Gateway 展开

Workspace 是工作空间- 保持文件整洁，控制 token 使用

配置即代码- openclaw.json 定义一切行为

安全第一- 默认使用配对模式，谨慎开放 DM

多智能体支持- 可以为不同任务创建专门的助理