OpenClaw 完全新手指南 - 个人 AI 助手本地部署与配置

本文是一份详尽的 OpenClaw 新手指南，旨在帮助用户快速了解核心概念、完成初始配置，并成功部署专属于你个人的本地 AI 助手。

🚀 什么是 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

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

Windows (PowerShell)

1	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. 打开控制面板

1
2
3

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

3. 发送测试消息

1	openclaw message send --to +15555550123 --message "Hello from OpenClaw"

4. 与智能体对话

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

📁 Workspace 工作空间

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

核心文件说明

AGENTS.md：定义多智能体信息。
SOUL.md：核心灵魂设定。
TOOLS.md：可调用的工具描述。
USER.md：用户的个性化档案。
IDENTITY.md：智能体身份及边界设定。
MEMORY.md：智能体长短期记忆文件。

⚙️ 配置 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 安全策略

安全策略配置参数：

pairing：配对模式（默认推荐）。
allowlist：白名单模式。
open：开放模式（危险）。
disabled：禁用私聊。

Telegram 配置

{
  "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 安装。

安装 ClawHub CLI

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

1	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

管理技能

列表技能：clawhub list
更新技能：clawhub update <skill>
比如：clawhub update baoyu-image-gen
更新全部：clawhub update --all
强制更新：clawhub update --force

常用推荐技能

baoyu-image-gen：clawhub install baoyu-image-gen
weather：clawhub install weather
github：clawhub install github
video-frames：clawhub install video-frames
xurl：clawhub install xurl
find-skills：clawhub install find-skills

技能工作原理

技能是包含特定功能的文件夹。你可以创建自己的功能包。

发布自己的技能

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

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

你也可以指定特定的镜像源发布技能配置 (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.json (Config validation failed)，可使用 openclaw doctor 修复。
认证失败: 检查 Unauthorized 或 auth 相关日志，重新验证 Token 配置。
会话未找到 (Session not found): 如果发生会话不同步，可以在聊天中发送 /new 重启会话。

🔗 资源链接

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

📝 总结

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

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

如果想要深入了解更多，可以参考官方文档：docs.openclaw.ai。祝你使用愉快！🦞

prev
Home
next