OpenClaw 完全指南：从入门到精通

声明：本文基于公开资料整理，包含官方文档、社区教程与实践验证。内容截至 2026 年 3 月，建议以官方最新文档为准。

1. OpenClaw 是什么

OpenClaw 是一个自托管（Self-hosted）的多模型 AI 助手网关平台，目标是在本地运行并连接多种聊天/消息通道（如 WhatsApp、Telegram、Discord、iMessage 等）到可自定义的 AI Agent 上，以保持对数据的控制与隐私。

核心特性

特性	说明
多渠道支持	WhatsApp、Telegram、Discord、iMessage 等并行运行
本地存储	Agent 数据默认存储在本地 SQLite，保护隐私
多模型接入	支持 OpenAI、Anthropic、Ollama、vLLM、GLM 等
可扩展技能	通过 Skills 系统扩展功能
MIT 许可证	开源免费，社区活跃

适用场景

搭建个人 AI 助手
企业内部知识管理
自动化工作流
多渠道客服机器人
开发测试环境

2. 核心架构与组件

OpenClaw 采用模块化架构，主要包含以下核心组件：

2.1 Gateway（网关）

Gateway 是整个系统的核心进程，负责：

客户端连接管理：处理 WebSocket 连接、会话与路由
消息转发：在消息通道与 Agent 之间转发消息
API 暴露：提供 OpenAI 风格的 HTTP API（/v1/chat/completions 等）
工具端点：/tools/invoke 供第三方调用

┌─────────────────────────────────────────────┐
│                 Gateway                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────────┐ │
│  │WebSocket│  │ REST    │  │  SSE/       │ │
│  │ Server  │  │ API     │  │  Streaming  │ │
│  └─────────┘  └─────────┘  └─────────────┘ │
│              Port: 18789                   │
└─────────────────────────────────────────────┘

配置参数：

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "127.0.0.1",
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    }
  }
}

mode：运行模式（local/loopback/lan/tailnet/0.0.0.0）
port：默认监听端口 18789
bind：绑定地址，建议本地部署使用 127.0.0.1
auth：认证模式，支持 token 或密码

2.2 Dashboard（控制面板）

Web 界面的控制面板，用于：

聊天对话
配置管理
会话历史查看
节点与技能管理

启动命令：

openclaw dashboard

启动后会在浏览器中打开 http://127.0.0.1:18789

⚠️ 安全提醒：Dashboard 不建议直接暴露在公网，应通过反向代理+TLS 保护或保持在内网。

2.3 TUI（终端界面）

终端交互界面，适合无浏览器环境或偏好终端操作的用户。

启动命令：

# 基本启动
openclaw tui

# 指定参数
openclaw tui --url http://127.0.0.1:18789 --token your-token --session session-id

2.4 Workspace 与 Memory

Workspace 是 Agent 的工作目录，包含：

workspace/
├── agents/
│   └── /
│       ├── agent.md      # Agent 定义（系统提示、人格）
│       ├── memory/       # 记忆存储
│       └── skills/       # 专属技能
├── memory/               # 全局记忆
├── agent.md              # 默认 Agent 定义
├── identity.md           # 身份定义
└── user.md               # 用户偏好

优先级规则：Workspace 内的 Skills > 全局 Skills > 内置 Skills

3. 环境要求与安装

3.1 环境要求

项目	要求
Node.js	v22+（推荐 v22 LTS 或 v24）
操作系统	macOS 12+、Linux（Ubuntu/Debian）、Windows 10/11（推荐 WSL2）
内存	最低 4GB，推荐 8GB+
存储	至少 100GB SSD

💡 若运行本地大型模型（如 Llama 3.3 70B），需要 64GB+ 内存。

3.2 安装方式

方式一：一键安装脚本（推荐新手）

macOS / Linux：

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

Windows（管理员 PowerShell）：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
iwr -useb https://openclaw.ai/install.ps1 | iex

方式二：npm 全局安装

# macOS / Linux
sudo npm install -g openclaw@latest

# Windows (WSL2 或管理员 PowerShell)
npm install -g openclaw@latest

# 如遇权限问题
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

方式三：Docker 部署

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 使用 docker-compose 启动
docker compose up -d

# 查看日志
docker compose logs -f openclaw-gateway

# 停止
docker compose down

docker-compose.yml 示例：

version: '3.8'
services:
  openclaw-gateway:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-token
      - OPENAI_API_KEY=sk-xxx
      - ANTHROPIC_API_KEY=sk-ant-xxx
    volumes:
      - ./data:/root/.openclaw
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:18789/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3

方式四：源码构建

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
pnpm install

# 构建
pnpm ui:build
pnpm build

# 链接全局
pnpm link --global

# 运行入门向导
openclaw onboard --install-daemon

3.3 初始化配置

安装完成后，运行入门向导：

openclaw onboard --install-daemon

向导会引导完成：

创建工作区
选择并配置 AI 模型（API Key）
选择消息通道
配置技能
启动 Gateway

4. 配置详解

4.1 配置文件位置

Linux/macOS：~/.openclaw/openclaw.json
Windows：C:\Users\<user>\.openclaw\openclaw.json

4.2 完整配置示例

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "127.0.0.1",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    },
    "rate_limit": {
      "enabled": true,
      "requests_per_minute": 60
    }
  },
  "agents": {
    "defaults": {
      "primaryModel": "anthropic/claude-sonnet-4-6",
      "fallbacks": ["openai/gpt-5.2"]
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-xxx",
        "baseUrl": "https://api.openai.com/v1"
      },
      "anthropic": {
        "apiKey": "sk-ant-xxx",
        "baseUrl": "https://api.anthropic.com"
      },
      "ollama": {
        "baseUrl": "http://localhost:11434"
      }
    }
  },
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/openclaw.log",
    "redactSensitive": "tools"
  },
  "cron": {
    "enabled": true,
    "storage": "~/.openclaw/cron",
    "maxConcurrentRuns": 2
  },
  "sandbox": {
    "enabled": false
  }
}

4.3 环境变量

常用环境变量：

变量	说明
`OPENAI_API_KEY`	OpenAI API 密钥
`ANTHROPIC_API_KEY`	Anthropic API 密钥
`OPENCLAW_GATEWAY_TOKEN`	Gateway 认证令牌
`OPENCLAW_HOME`	自定义配置目录
`OPENCLAW_SANDBOX`	启用沙箱模式
`OPENCLAW_LOG_LEVEL`	日志级别（debug/info/warn/error）
`OPENCLAW_RAW_STREAM`	开启原始流调试

4.4 生成 Gateway Token

# 使用 openssl 生成
openssl rand -hex 32

# 或使用 OpenClaw 工具
openclaw doctor --generate-gateway-token

5. 模型接入

5.1 支持的模型提供方

提供方	模型示例	说明
OpenAI	gpt-5.2, gpt-4o	需 API Key
Anthropic	claude-opus-4-6, claude-sonnet-4-6	需 API Key
Ollama	llama3.3, qwen3:32b	本地运行
vLLM	qwen2.5-32b	本地/远程
OpenRouter	多模型聚合	需 API Key
MiniMax	M2.7	国内模型
GLM	glm-4-6	需 API Key

5.2 配置示例

OpenAI

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-xxx",
        "baseUrl": "https://api.openai.com/v1"
      }
    }
  }
}

Anthropic

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx",
        "baseUrl": "https://api.anthropic.com"
      }
    }
  }
}

Ollama（本地模型）

# 先下载模型
ollama pull qwen3:32b
ollama pull llama3.3

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434"
      }
    }
  }
}

5.3 模型标识格式

使用 provider/model 格式：

anthropic/claude-sonnet-4-6
openai/gpt-5.2
ollama/llama3.3
openrouter/anthropic/claude-sonnet-4-5

5.4 Agent 级别的模型配置

{
  "agents": {
    "my-agent": {
      "primaryModel": "anthropic/claude-opus-4-6",
      "fallbacks": [
        "openai/gpt-5.2",
        "ollama/llama3.3"
      ]
    }
  }
}

6. Agents 管理

6.1 创建 Agent

# 创建新 Agent
openclaw agents add my-agent

# 指定工作区
openclaw agents add my-agent --workspace /path/to/workspace

创建后会在 ~/.openclaw/agents/ 目录生成：

my-agent/
├── agent.md      # Agent 定义（系统提示）
├── memory/       # 记忆存储
└── config.json   # Agent 配置

6.2 Agent 配置文件

agent.md 示例：

---
name: MyAgent
description: 一个有用的 AI 助手
---

# 角色

你是一个专业、友好的 AI 助手，专门帮助用户解决技术问题。

## 能力

- 编写和调试代码
- 回答技术问题
- 协助项目管理

## 约束

- 不执行任何有害操作
- 保护用户隐私

config.json 示例：

{
  "model": "anthropic/claude-sonnet-4-6",
  "fallbacks": ["openai/gpt-5.2"],
  "systemPrompt": "agent.md",
  "temperature": 0.7,
  "maxTokens": 4096
}

6.3 多 Agent 协作

支持协调器-专家模式：

{
  "agents": {
    "coordinator": {
      "model": "anthropic/claude-opus-4-6",
      "systemPrompt": "你是一个任务协调器，负责分配任务给专家..."
    },
    "coder": {
      "model": "anthropic/claude-sonnet-4-6",
      "systemPrompt": "你是一个专业程序员..."
    },
    "reviewer": {
      "model": "openai/gpt-5.2",
      "systemPrompt": "你是一个代码审查专家..."
    }
  }
}

6.4 Agent 命令汇总

# 列出所有 Agent
openclaw agents list

# 查看 Agent 信息
openclaw agents info my-agent

# 删除 Agent
openclaw agents remove my-agent

# 切换默认 Agent
openclaw agents primary my-agent

7. Skills 技能系统

7.1 Skills 概念

Skills 是 OpenClaw 的功能扩展系统，本质是带 YAML frontmatter 的 Markdown 文件，可包含脚本和参考资料。

7.2 Skills 存放位置（优先级）

workspace/skills/（工作区专属）
~/.openclaw/skills/（全局）
内置技能

7.3 创建 Skill

创建目录结构：

my-skill/
├── SKILL.md          # 技能定义
├── references/        # 参考资料
│   └── README.md
└── scripts/           # 脚本
    └── run.sh

SKILL.md 示例：

---
name: my-skill
description: 这是一个示例技能
version: 1.0.0
dependencies:
  - git
  - node
---

# 功能说明

这个技能用于执行特定任务。

## 使用方法

直接调用即可。

## 脚本

脚本位置：scripts/run.sh

7.4 安装社区 Skills

# 列出可用 Skills
openclaw skills list

# 安装 Skills
openclaw skills install web-browse
openclaw skills install code-runner

# 卸载 Skills
openclaw skills uninstall web-browse

7.5 调试 Skills

# 查看已加载的 Skills
openclaw skills loaded

# 测试 Skill
openclaw skills test my-skill

8. 消息通道集成

8.1 支持的通道

通道	配置难度	说明
Telegram	⭐ 简单	只需 Bot Token
Discord	⭐⭐ 中等	需配置 Intents
WhatsApp	⭐⭐ 复杂	需要 WhatsApp Web
iMessage	⭐⭐⭐ 困难	需要 Mac + Apple Script

8.2 Telegram 配置

与 @BotFather 对话创建机器人，获取 Token
在配置中添加：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "bot_token": "your-telegram-bot-token",
      "allowFrom": ["user_id_1", "user_id_2"]
    }
  }
}

8.3 Discord 配置

创建 Discord Application
启用 Privileged Intents：
- GUILDS
- GUILD_MESSAGES
- MESSAGE_CONTENT
创建机器人并获取 Token

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token": "your-discord-bot-token",
      "intents": ["GUILDS", "GUILD_MESSAGES", "MESSAGE_CONTENT"],
      "allowFrom": ["channel_id_1"]
    }
  }
}

8.4 WhatsApp 配置

⚠️ 风险提示：使用第三方库实现，存在供应链风险，建议仅用于测试。

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "session_path": "~/.openclaw/whatsapp-session"
    }
  }
}

9. 安全设置

9.1 执行策略

OpenClaw 的 exec 工具支持三种安全策略：

{
  "exec": {
    "policy": "deny",    // deny | allowlist | full
    "allowlist": [
      "/usr/bin/git",
      "/usr/bin/npm"
    ]
  }
}

deny：默认拒绝所有执行
allowlist：仅允许列表中的命令
full：允许所有执行（危险！）

9.2 沙箱模式

# 启用沙箱
export OPENCLAW_SANDBOX=1

# 或在配置中
{
  "sandbox": {
    "enabled": true
  }
}

9.3 敏感信息脱敏

{
  "logging": {
    "redactSensitive": "tools"  // tools | all | none
  }
}

9.4 Gateway 安全建议

绑定地址：使用 127.0.0.1 而非 0.0.0.0
Token 保密：不要在公网暴露 Token
使用 TLS：生产环境使用反向代理+HTTPS
定期轮换：定期更换 Gateway Token
限制来源：使用 allowFrom 限制可访问用户

⚠️ 安全漏洞提醒：CVE-2026-25253 在 2026.1.29 版本修复，漏洞允许通过恶意链接获取 Gateway Token。请及时升级到最新版本。

10. 运维与故障排查

10.1 常用命令

# 健康检查
curl -fsS http://127.0.0.1:18789/healthz

# 查看日志
openclaw logs --follow

# 诊断问题
openclaw doctor

# 修复配置
openclaw doctor --fix

# 生成 Token
openclaw doctor --generate-gateway-token

# 更新 OpenClaw
openclaw update

# 切换发布通道
openclaw update --channel stable  # stable | beta | dev

10.2 常见问题

问题	解决方案
Node 版本过旧	升级到 Node 22+：`nvm use 22`
模型 not found	检查模型标识、API Key、配置后重启 Gateway
通道无法接收消息	检查 Token 权限、重新生成 Token
Gateway 无法启动	检查端口占用、查看日志
WebSocket 连接失败	检查 Nginx 配置（需转发 WebSocket 头）

10.3 日志位置

Linux/macOS：~/.openclaw/logs/
Docker：/var/log/openclaw/
系统日志：/tmp/openclaw/openclaw-YYYY-MM-DD.log

10.4 性能优化

{
  "cron": {
    "maxConcurrentRuns": 2  // 限制并发任务数
  },
  "gateway": {
    "rate_limit": {
      "enabled": true,
      "requests_per_minute": 60
    }
  }
}

11. 参考资源

官方资源

社区教程

视频教程

结语

OpenClaw 是一个功能强大的自托管 AI 助手平台，通过本文档，你应该已经掌握：

OpenClaw 的核心架构
各种安装与部署方式
模型配置与接入
Agent 与 Skill 的管理
消息通道集成
安全设置与运维

建议从最小配置开始，逐步增加功能，先让一个 Agent 跑起来，再逐步探索高级特性。

📌 更新说明：本文将持续更新，建议收藏。如有疏漏，欢迎指出。

参考资料：