OpenClaw 新手入门完全指南

什么是 OpenClaw？

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

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

• 个人化：为你个人服务，而非企业级多用户系统
• 本地运行：Gateway 运行在你的设备上（macOS、Linux、Windows WSL2）
• 多渠道接入：支持几乎所有主流通讯平台
• 功能丰富：浏览器控制、Canvas 可视化、语音交互、定时任务等

架构概览

WhatsApp / T@elegrimm / 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 安装

# 使用 npm
npm install -g openclaw@latest

# 或使用 pnpm
pnpm 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 +15555550123 --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/ # 凭证存储

核心文件说明

️配置 openclaw.json

~/.openclaw/openclaw.json 是 OpenClaw 的核心配置文件，使用 JSON5 格式（支持注释和尾随逗号）。

最小配置示例

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC...",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123456789"]
    }
  }
}

Agents 配置

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-5.2"]
      },
      "heartbeat": {
        "every": "30m",
        "target": "last"
      }
    }
  }
}

Session 会话管理

{
  "session": {
    "dmScope": "per-channel-peer",
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    }
  }
}

配置对话终端（Channels）

DM 安全策略

T@elegrimm 配置

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123456789"],
      "streaming": "partial"
    }
  }
}

配置多智能体（Multi-Agent）

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main",
        "description": "通用助手"
      },
      {
        "id": "coder",
        "workspace": "~/.openclaw/workspace-coder",
        "description": "编程专家"
      }
    ]
  }
}

技能安装

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

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

安装 ClawHub CLI

首先确保已安装 ClawHub 命令行工具：

npm install -g clawhub

搜索技能

在 ClawHub 上搜索你需要的技能：

# 搜索关键词
clawhub search "postgres backups"
clawhub search "image generation"
clawhub search "weather"

安装技能

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

# 安装最新版本
clawhub install baoyu-image-gen

# 安装指定版本
clawhub install baoyu-image-gen --version 1.2.3

管理技能

常用推荐技能

技能工作原理

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

my-skill/├── SKILL.md # 技能定义和使用说明└── 其他文件 # 脚本、配置等

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

发布自己的技能

如果你有自己开发的技能，可以发布到 ClawHub 分享：

# 登录 ClawHub
clawhub login

# 发布技能
clawhub publish ./my-skill 
  --slug my-skill 
  --name "My Skill" 
  --version 1.0.0 
  --changelog "Initial release"

️

注意： 技能默认注册表为 clawhub.com，可通过 CLAWHUB_REGISTRY 环境变量或 --registry 参数覆盖。

⌨️常用 CLI 命令

Gateway 管理

# 查看状态
openclaw gateway status

# 启动/停止/重启
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

配置管理

# 运行配置向导
openclaw onboard

# 获取/设置配置值
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.model.primary "openai/gpt-5.2"

诊断工具

# 健康检查
openclaw doctor

# 自动修复
openclaw doctor --fix

# 查看日志
openclaw logs --follow

安全最佳实践

️

永远不要在未经保护的情况下公开 DM：
使用 dmPolicy: "pairing" 或 allowlist 而非 open

多用户环境

{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

沙盒执行

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      }
    }
  }
}

故障排除

资源链接

• 官网: openclaw.ai
• 文档: docs.openclaw.ai
• GitHub: github.com/openclaw/op…
• Discord: discord.gg/clawd
• 技能市场: clawhub.com

总结

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

1. Gateway 是核心 - 所有功能都围绕 Gateway 展开
2. Workspace 是工作空间 - 保持文件整洁，控制 token 使用
3. 配置即代码 - openclaw.json 定义一切行为
4. 安全第一 - 默认使用配对模式，谨慎开放 DM
5. 多智能体支持 - 可以为不同任务创建专门的助手