OpenClaw「龙虾」完整指南

一、项目概述

OpenClaw 是一款开源 AI 执行引擎，由奥地利开发者 Peter Steinberger 主导开发，于 2026 年 1 月完成品牌定名。其核心定位是「本地运行、可自托管的 AI 执行引擎」，主打「从给建议到做事情」—— 能通过自然语言指令自主规划并完成全流程任务的「数字员工」，而非被动的聊天机器人。

截至 2026 年 2 月，GitHub 仓库星标数已突破 18.6 万。项目采用 MIT 开源协议，支持免费使用、自由修改、二次开发与私有化部署。

二、30 分钟上手（推荐先做）

如果你是第一次接触 OpenClaw，不要先纠结“架构/配置/安全”。先把它跑起来，看到控制面板能连上、能发消息收到回复，你就已经成功 70%。

2.1 快速健康检查（你遇到问题先看这里）

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

2.2 环境准备：Node.js + Git（强烈建议先确认）

node -v

git --version

2.3 先用浏览器把第一句话聊通（最省事）

1. 运行引导：openclaw onboard（建议 QuickStart）。
2. 打开控制面板：openclaw dashboard，浏览器访问 http://127.0.0.1:18789/。
3. 按提示填入 token（或在向导里自动生成），在 WebChat 里发送一句“你好”。

2.4 Windows（WSL2）从 0 到可用（照抄即可）

# PowerShell（管理员）
wsl --install
wsl --list --online
wsl --install -d Ubuntu-24.04

# WSL 里（Ubuntu）
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

# PowerShell
wsl --shutdown

# WSL 里
openclaw onboard --install-daemon
openclaw dashboard

2.5 Docker Compose（最快跑通容器版）

1. 准备：安装 Docker Desktop/Engine + Compose v2（2GB+ 内存更稳）。
2. 在 OpenClaw 仓库根目录执行：./docker-setup.sh（会自动生成 token 写入 .env 并启动网关）。
3. 浏览器打开 http://127.0.0.1:18789/，在 Control UI 里粘贴 token。

2.6 一键安装 OpenClaw（Quick Install）

1. 打开浏览器访问 https://openclaw.ai 官方网站，找到首页的“快速安装”指令。
2. 复制完整命令（一般是一行很长的 shell 脚本调用）。
3. 在 Windows 的 PowerShell（管理员）或 macOS/Linux 的 Terminal 中粘贴并回车。
4. 等待脚本自动下载、构建并安装 OpenClaw，期间保持终端不要关闭。

2.7 配置大模型（初级版）

1. 在向导中选择你要使用的模型提供方：例如 Claude、GPT、Gemini、Qwen、GLM、Kimi、Ollama 等。
2. 到对应平台控制台获取 API Key（复制好保存），在向导中粘贴。
3. 在“模型版本”步骤选择默认推荐的型号即可；除非你非常清楚要用哪个特定版本。

2.8 接入第一个聊天软件（以 Telegram 为例）

1. 在手机或桌面端打开 Telegram，搜索 @BotFather，按提示创建一个新 Bot，拿到 Bot Token。
2. 在 OpenClaw 向导或配置中，将 Bot Token 填入 channels.telegram.botToken 或对应的输入框。
3. 启动 Gateway 后，在 Telegram 中给 Bot 发送第一条消息，并根据日志/向导提示完成 pairing（配对）或 allowlist（白名单）设置。

2.9 获取 Gateway Token 并在 Dashboard 中使用

1. 在命令行中运行：openclaw doctor generate gateway token（或在向导中选择生成 Token）。
2. 如果命令返回了一串 token，将其复制保存到安全位置（例如密码管理器）。
3. 如果命令没有返回，可打开 ~/.openclaw/openclaw.json，在 gateway.auth.token 字段中找到已有 Token。
4. 打开 Dashboard，在设置页的“Gateway Token”输入框中粘贴该 Token 并点击连接。

三、中国用户特别说明（强烈建议先读）

这章专门解决国内用户上手 OpenClaw 最常见的 3 类问题：网络可达性、模型选择、渠道选择。你按这里做，基本就能少踩一半坑。

3.1 网络与部署位置：本机可以学习，生产建议“国内云 + 合规网络出口”

3.2 模型选择（国内优先推荐）

OpenClaw 支持很多 provider。国内用户建议优先选：通义 Qwen、GLM（Z.AI）、Kimi（月之暗面 Moonshot）、百度千帆。下面给你“能直接复制”的最小配置。

A) 通义 Qwen（免费 OAuth 流，适合入门）

# 启用 Qwen OAuth 插件
openclaw plugins enable qwen-portal-auth

# 登录并设为默认 provider（设备码 OAuth）
openclaw models auth login --provider qwen-portal --set-default

# 切换模型（示例）
openclaw models set qwen-portal/coder-model

B) GLM（走 Z.AI 平台，API Key）

# 向导方式（推荐）
openclaw onboard --auth-choice zai-api-key

# 或配置方式（最小）
{
  env: { ZAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "zai/glm-5" } } },
}

C) Kimi（月之暗面 Moonshot，OpenAI 兼容）

openclaw onboard --auth-choice moonshot-api-key

{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "moonshot/kimi-k2.5" } } },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        # 国内建议用 cn endpoint
        baseUrl: "https://api.moonshot.cn/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
      },
    },
  },
}

D) 百度千帆（统一网关，OpenAI 兼容思路）

openclaw onboard --auth-choice qianfan-api-key

千帆 key 形如 bce-v3/ALTAK-...。适合企业采购与合规落地。

3.3 渠道选择：国内优先用飞书（Feishu/Lark），再考虑 Telegram/WhatsApp

飞书最小配置示例（可复制）

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "企业 AI 助手",
        },
      },
    },
  },
}

上线前记得：在飞书开放平台把事件订阅设置成“长连接 WebSocket”，并添加事件 im.message.receive_v1。

3.4 国内镜像与依赖加速（可选）

• npm 镜像：示例里已用 --registry https://registry.npmmirror.com（更适合国内）。
• Docker 镜像：可使用你企业/云厂商镜像加速，或在内网建 registry mirror。
• 注意：生产环境建议使用官方 GHCR 镜像（ghcr.io/openclaw/openclaw）或你公司自建的受控镜像仓库，避免来源不明的镜像。

四、核心特性

• 本地优先：所有用户数据默认存储于用户自有设备，实现数据主权与隐私安全自主。
• 模型兼容：支持接入 Claude、GPT、Ollama 等主流大模型，可按需切换或配置回退。
• 多渠道支持：兼容 Telegram、WhatsApp、Discord、钉钉、飞书、QQ、Slack、iMessage、Google Chat、Signal、Mattermost 等十余种通讯渠道。
• 可扩展：通过可插拔的 Skills（技能）无限扩展能力；官方技能市场 ClawHub 提供大量现成技能。
• 轻内核、重插件：核心能力完全依赖 Skills 扩展，默认不包含搜索、文件处理等，需按需安装。

4.1 新手先记住这 5 个“开关”

五、架构与组件

OpenClaw 采用「轻内核 + 重插件」设计，主要组件包括：

• Gateway 网关：核心服务，负责配置加载、渠道连接、会话与消息路由、RPC 调用等。默认端口 18789，配置来自 ~/.openclaw/openclaw.json（JSON5，支持注释与尾逗号）。
• 节点（Nodes）：iOS、Android、Windows、macOS、Linux 等客户端，用于与用户交互并连接 Gateway。
• Web 控制面板 / WebChat：浏览器端控制与聊天界面，可远程访问（需配置远程访问与认证）。
• RPC 适配器：供 CLI、节点、自动化脚本与 Gateway 通信的接口（如 config.get、config.apply、config.patch 等）。
• 工作区（Workspace）：每个智能体拥有独立工作区目录，用于文件与上下文存储；可配合工作区模板（如 AGENTS）使用。
• 多智能体路由：通过 agents.list 与 bindings 在一个 Gateway 中运行多个隔离智能体，按渠道/账号/群组等路由。

配置需严格符合 Schema，未知键或类型错误会导致 Gateway 拒绝启动。可使用 openclaw doctor --fix 进行迁移与修复。

六、Skills 与 ClawHub

Skills 是教导 AI Agent 如何操作外部工具的结构化指令集，包含依赖、SKILL.md 及技能目录。OpenClaw 默认不具备搜索、文件处理等能力，需通过安装 Skills 扩展。

6.1 ClawHub 与安装命令

推荐通过 ClawHub 管理技能（截至 2026 年，已收录 1700+ 技能）：

# 全局安装 ClawHub CLI（仅需一次）
npm i -g clawhub --registry https://registry.npmmirror.com

# 搜索技能
clawhub search "日历"

# 安装指定技能
clawhub install browser

# 批量更新所有技能
clawhub update --all

你也可以用 npx（不想全局安装时很方便）：

• 安装：npx clawhub@latest install <skill-slug>
• 查看状态：openclaw skills list --status ready
• 启用/禁用：openclaw skills enable <skill> / openclaw skills disable <skill>

6.2 技能配置

所有技能配置位于 ~/.openclaw/openclaw.json 的 skills 字段：

• entries：单技能启用/禁用及 API Key、环境变量等。
• install.nodeManager：npm、pnpm、yarn、bun 等包管理器。
• load.watch：监视技能目录自动刷新（默认 true）。
• load.extraDirs：扫描额外技能目录。

6.3 推荐必装技能（示例）

新手常用“从易到难”的装法（建议按顺序来）：

1. 元技能/技能发现：先装 Find Skills（帮助你在 ClawHub 里找技能）。
2. 搜索：Tavily Search / Multi Search Engine（让它能查资料）。
3. 浏览器：Agent Browser（适合没有 API 的网站自动化）。
4. 命令与脚本：Shell（务必配合确认/审批策略）。
5. 自动化：Cron/Wake（定时任务、每日简报）。
6. 业务集成：Telegram、飞书、Gmail、Google Calendar、GitHub、Notion…（按需求选）。

6.4 安全建议

• 定期更新：clawhub update --all
• 权限清单：涉及账号的技能（邮箱/网盘/IM）务必先确认最小权限
• 高危技能要确认：浏览器、Shell、文件写入类技能建议开启确认/审批
• 选择标准：优先官方认证、下载量高、近期有更新的技能

七、部署指南

7.1 前置条件

如果你只想先跑起来：你只需要 OpenClaw CLI + 一个能长期运行的环境。

7.2 Windows 小白推荐：WSL2（windows_wsl）

1. 启用 WSL2，并安装一个 Linux 发行版（推荐 Ubuntu）。
2. 在 WSL 里安装 Docker（或使用 Docker Desktop，但建议让 Docker 引擎跑在 WSL2）。
3. 在 WSL 里运行 OpenClaw（Gateway/CLI）。

让 Gateway 随 Windows 启动（可选，但很实用）

如果你希望网关在不开 Ubuntu 终端的情况下也能常驻，WSL2 需要把“用户服务 + WSL 启动链”打通：

# WSL（Ubuntu）里：允许在未登录时运行 user service
sudo loginctl enable-linger "$(whoami)"

# 安装网关为用户服务
openclaw gateway install

# PowerShell（管理员）：开机启动 WSL（把 Ubuntu-24.04 替换成你的发行版名）
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu-24.04 --exec /bin/true" /sc onstart /ru SYSTEM

7.3 Docker 部署要点（docker_compose）

• 基础镜像：Debian GNU/Linux bookworm-slim；按具体版本号拉取（如 2026.2.22-beta.1），生产环境避免使用 latest。
• 国内镜像加速：可使用轩辕等国内镜像源拉取，例如 docker pull docker.xuanyuan.run/alpine/openclaw:2026.2.22-beta.1（以实际仓库为准）。
• 目录与环境：创建工作目录如 /opt/openclaw/{config,logs,data}；生成并保管 OPENCLAW_TOKEN（如 openssl rand -hex 32），写入 .env 并 chmod 600 .env。
• 生产建议：设置资源限制（如 mem_limit: 2g、cpus: 2）、restart: unless-stopped、健康检查、持久化卷（如 openclaw_home）；Gateway 仅绑定 127.0.0.1:18789，通过 Nginx 反向代理提供 HTTPS 与公网访问，并配置防火墙与日志策略。

官方推荐一键脚本（最省事）

# 在 OpenClaw 仓库根目录
./docker-setup.sh

# 完成后：浏览器打开
# http://127.0.0.1:18789/

手动 Compose（你想自己掌控每一步时）

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

# 需要 dashboard 链接但不自动打开浏览器：
docker compose run --rm openclaw-cli dashboard --no-open

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

生产模板（国内云常用）：Gateway 内网 + Nginx HTTPS 反代

这是最常见、也最稳的企业落地方式：网关只监听本机/内网，公网只暴露 443，并且强制 token 鉴权。

1. 准备域名与证书（可用 Nginx + 证书，或接入云厂商 SLB/CLB 的 HTTPS）。
2. 服务器防火墙/安全组只开：22（运维）、80/443（网站/反代）。不要开 18789 到公网。
3. 把 OpenClaw 作为服务常驻（Compose restart）。

# 目录结构建议（示例）
/opt/openclaw/
  ├─ docker-compose.yml
  ├─ .env
  ├─ nginx/
  │   ├─ openclaw.conf
  │   └─ certs/  # 证书
  └─ state/      # 持久化 ~/.openclaw

# docker-compose.yml（示例：用官方 GHCR 镜像，实际 tag 请按版本锁定）
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    restart: unless-stopped
    environment:
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_TOKEN}
      - TZ=Asia/Shanghai
    volumes:
      - ./state:/home/node/.openclaw
    ports:
      - "127.0.0.1:18789:18789"

  nginx:
    image: nginx:stable
    restart: unless-stopped
    depends_on:
      - openclaw-gateway
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/openclaw.conf:/etc/nginx/conf.d/openclaw.conf:ro
      - ./nginx/certs:/etc/nginx/certs:ro

# nginx/openclaw.conf（最小示例：WS/WSS 反代必须包含 Upgrade 头）
map $http_upgrade $connection_upgrade {
  default upgrade;
  '' close;
}

server {
  listen 80;
  server_name openclaw.example.com;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl http2;
  server_name openclaw.example.com;

  ssl_certificate     /etc/nginx/certs/fullchain.pem;
  ssl_certificate_key /etc/nginx/certs/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }
}

注意：反代场景建议在 OpenClaw 配置里设置 gateway.trustedProxies（只信任你的反代 IP），并保持 gateway.auth.mode=token。

7.4 华为云 / 国内服务器

• 安全组/防火墙：只开放必要端口（常见：22、80/443）。不建议把 18789 直接暴露公网。
• 公网访问方式：使用 Nginx HTTPS 反代（上一节模板）或 SSH/Tailscale 隧道。
• 境外 API 可达性：如需要访问 Claude 等境外服务，建议使用企业代理/合规网络出口，或选择香港/新加坡等节点。

八、配置详解

主配置文件：~/.openclaw/openclaw.json（JSON5）。若不存在，OpenClaw 使用安全默认值（内置 Pi 智能体 + 按发送者分会话 + 工作区 ~/.openclaw/workspace）。

8.1 常用配置项概览

• agents：agents.defaults（默认模型、工作区、沙箱等）、agents.list[]（多智能体 id、workspace、identity、groupChat 等）。
• channels：各渠道启用与认证（如 channels.telegram.botToken、channels.whatsapp.allowFrom）、群组白名单与提及行为（groups、requireMention）。
• gateway：port、auth.token 等。
• messages：消息前缀、队列模式、入站防抖、群组历史条数等。
• env：环境变量与 ${VAR} 替换；敏感信息也可放在 ~/.openclaw/.env。
• $include：将配置拆分为多文件，便于按环境或客户管理。

8.2 最小配置示例

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

应用与重启可通过 RPC：config.get 获取当前配置与 hash，再使用 config.apply（全量替换）或 config.patch（部分合并）写入并触发重启。建议修改前备份 openclaw.json。

九、通讯渠道

OpenClaw 支持多种通讯渠道，各渠道在 channels 下独立配置，常见包括：

• Telegram：channels.telegram.botToken，支持多账号、群组白名单、提及门控、自定义命令、webhook 等。
• WhatsApp：通过 Gateway 的 Web 渠道（Baileys）运行；allowFrom 私聊白名单、dmPolicy（pairing/allowlist/open/disabled）、groups 群组策略。
• Discord：channels.discord.token，guilds 按服务器与频道配置 allow、requireMention、systemPrompt 等。
• Slack：Socket Mode，需 botToken 与 appToken；channels 按频道控制。
• 其他：Google Chat（webhook + 服务账号）、iMessage（如 BlueBubbles）、Signal、Mattermost、飞书、钉钉等，详见官方文档各渠道章节。

群组策略可设为 allowlist、disabled 或 open；提及门控由 agents.list[].groupChat.mentionPatterns 与渠道的 requireMention 等控制。

9.1 小白最推荐的第一条渠道：Telegram

1. 在 Telegram 找 BotFather 创建机器人，拿到 Bot Token。
2. 把 token 写入配置：channels.telegram.botToken（或用环境变量引用）。
3. 先只允许你自己的账号（DM allowlist / pairing），确认跑通后再开放群聊。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

1. 启动网关：openclaw gateway。
2. 查看配对请求：openclaw pairing list telegram。
3. 批准配对码：openclaw pairing approve telegram <CODE>（1 小时过期）。

9.2 WhatsApp（扫码登录 + 配对/白名单）

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+8613900000000"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+8613900000000"],
    },
  },
}

1. 扫码登录：openclaw channels login --channel whatsapp。
2. 启动网关：openclaw gateway。
3. 配对批准：openclaw pairing list whatsapp → openclaw pairing approve whatsapp <CODE>。

9.3 如果你要做“多人私聊”：一定要开启 DM 会话隔离

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

9.4 飞书（Feishu/Lark）：国内企业优先推荐

飞书通道使用WebSocket 事件订阅，不需要暴露公网 webhook URL，更适合国内企业网络环境。

1. 到飞书开放平台创建企业应用，拿到 App ID 与 App Secret。
2. 在“事件订阅”里选择“长连接 WebSocket”，添加事件 im.message.receive_v1（网关要先启动）。
3. 发布应用并让管理员审批生效。

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: { appId: "cli_xxx", appSecret: "xxx", botName: "企业 AI 助手" },
      },
    },
  },
}

测试流程：

openclaw gateway
openclaw logs --follow
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

9.5 QQ：通过网关绑定 QQ 机器人（示例）

当前 QQ 并不像 Telegram 那样有统一的官方 Bot API，大多数实践会通过 第三方 QQ 网关（如基于 OneBot 协议的 go-cqhttp 等）来把 QQ 消息“转换”为 OpenClaw 能理解的 WebSocket / HTTP 事件。

1. 准备 QQ 网关
   • 选择一个支持 OneBot 协议 的 QQ 机器人网关（例如 go-cqhttp）。
   • 按照网关文档完成登录流程（扫码 / 设备锁验证等），确认它已经可以正常收发 QQ 私聊与群聊信息。
   • 在网关配置中开启 WebSocket / HTTP 上报接口，并记录监听地址与鉴权方式（例如 ws://127.0.0.1:6700、access_token 等）。
2. 在 OpenClaw 中新增 QQ 渠道配置

   下面是一个示例思路（具体字段以你实际使用的 QQ 网关适配器为准）：

   {
     channels: {
       qq: {
         enabled: true,
         kind: "onebot",              // 使用 OneBot 协议的 QQ 网关
         endpoint: "ws://127.0.0.1:6700", // QQ 网关 WebSocket 地址
         accessToken: "${QQ_BOT_TOKEN}",  // 与网关配置一致的 token（如有）
         dmPolicy: "pairing",             // DM 采用配对模式，避免被陌生人刷消息
         groups: {
           "*": {
             requireMention: true,        // 群聊默认需要 @ 才触发
           },
         },
       },
     },
   }

   如果你的视频或适配器使用的是 channels.qq.onebot、channels.onebot 等命名，只需要按相同思路，把 endpoint / token / 群策略 映射进去即可。

3. 启动并测试
   • 先启动 QQ 网关进程，确认它已成功登录 QQ、状态正常。
   • 再启动 OpenClaw 网关：openclaw gateway，观察日志中是否有“QQ / OneBot 连接成功”之类的提示。
   • 从 QQ 私聊或测试群发一条简单消息，例如“ping”，确认能在 OpenClaw 日志中看到对应事件，并收到回复。

十、使用案例（照抄就能用）

下面这些案例来自社区常见玩法的“可落地版本”。你不需要一次做完，建议先做案例 1（最通用），再按业务挑一个。

10.1 案例 1：群聊“技术支持机器人”（只在@我时回复）

• 适用：企业技术支持群、交付群、售后群。
• 关键点：群白名单 + requireMention=true + 工具最小化。

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: true },
      },
    },
  },
  tools: { profile: "messaging", deny: ["gateway", "cron", "sessions_spawn", "sessions_send"] },
}

你可以这么用（在群里）：

@YourBot 这段日志是什么意思？我应该先排查哪些点？

10.2 案例 2：每周自动“计划 + 下单”（纯浏览器自动化）

• 适用：采购、订餐、订票、填报等“没 API 但有网页”的工作流。
• 关键点：浏览器工具 + 审批（ask always）+ 限制可访问站点。

你可以这么用：

每周五 10:00 帮我生成下周工作日的晚餐计划（偏低脂），把常买清单带上。
然后打开网站，添加到购物车，但不要付款，等我确认。

10.3 案例 3：GitHub PR 自动审查（Telegram 通知）

• 适用：研发团队，想要“有人先看一眼”再合并。
• 关键点：GitHub skill + 只读权限为主 + 输出“必须改/建议改/可合并”。

你可以这么用：

收到 PR 链接后：
1) 给我 5 条最关键问题（安全/性能/逻辑）。
2) 给出合并建议：阻塞 or 可合并。
3) 如果可合并，列出最小修改清单。

10.4 案例 4：WhatsApp 多人私聊“个人助理”（不串线）

• 适用：你希望多个人都能 DM 机器人，但互相内容隔离。
• 关键点：session.dmScope=per-channel-peer + DM allowlist/pairing。

{
  session: { dmScope: "per-channel-peer" },
  channels: {
    whatsapp: { dmPolicy: "pairing" },
  },
}

10.5 案例 5：财务/报销“PDF 收集 + 归档”

• 适用：每月票据/合同很多，想自动分类、命名、归档。
• 关键点：文件工具（workspaceOnly）+ 结构化输出（表格/清单）。

你可以这么用：

把这个月的 PDF 发给你：
1) 识别发票类型/金额/日期/供应商
2) 生成一张汇总表（CSV）
3) 按“月份/供应商”归档到 workspace 目录

10.6 案例 6：飞书“客服工单分流”（国内企业高频）

• 适用：客户群/售后群/内部支持群，希望机器人先做“分流与标准化提问”。
• 关键点：飞书群 requireMention=true（避免刷屏）+ 输出工单模板 + 明确升级人工规则。

你可以这么用（在飞书群里 @ 机器人）：

@企业AI助手 帮我把这个问题整理成工单：
现象：xxx
环境：Windows/WSL2/Docker
报错：xxx
期望：xxx

期望输出（机器人模板）：

【工单标题】
【影响范围】（单人/团队/生产）
【现象】
【复现步骤】1) 2) 3)
【日志关键字】
【已尝试】
【建议下一步排查】（按优先级列 3-5 条）
【是否需要人工介入】（是/否 + 原因）

10.7 案例 7：群内“知识库问答（带引用）”

• 适用：企业制度/流程/产品手册多，群里反复问同一类问题。
• 关键点：把文档放进 workspace；回答必须给出“引用片段/文件路径”，避免瞎编。

你可以这么用：

@企业AI助手 公司的报销标准是什么？
回答请引用：给出文件名 + 原文片段 + 所在章节。

10.8 案例 8：日报/周报自动生成（国内常用）

• 适用：项目组固定节奏汇报。
• 关键点：固定模板 + 固定字段 + 只从你提供的素材总结（不添加臆测）。

你可以这么用：

把今天的工作要点发给你（可能很乱）：
- ...
- ...
请按模板输出日报：
1) 今日完成（3-6条）
2) 进行中（含风险/阻塞）
3) 明日计划（3-6条）
4) 需要协助（可选）

10.9 案例 9：国内模型优先的“稳定助手”（Qwen/GLM/Kimi）

• 适用：国内网络不稳定、希望随时可用。
• 关键点：优先配置国内 provider + 做模型 fallback（主模型不可用时自动切换）。

你可以这么用：

默认用 Kimi（moonshot.cn），如果失败就切到 GLM（zai）。
并且告诉我：这次用了哪个模型、消耗了多少 token。

十一、网关协议（你用 UI/CLI 也在走它）

OpenClaw 的所有客户端（CLI、控制面板、桌面 App、手机节点）都通过 WebSocket 连接 Gateway。理解协议的价值在于：当你遇到“面板连不上 / 设备认证失败 / token 不对”时，你知道该查哪里。

11.1 连接握手的 3 个关键点

十二、安全与运维（生产必看）

• 故障排除：openclaw doctor、openclaw logs、openclaw health、openclaw status；官方文档提供 Gateway 故障排除专题。
• 安全：Gateway 仅监听本地时，通过 Nginx 等反向代理暴露 HTTPS；妥善保管 OPENCLAW_TOKEN 与各渠道 token；使用 logging.redactSensitive 与 redactPatterns 避免日志泄露密钥。
• Webhooks：用于外部系统触发或接收事件，见自动化章节。
• 定时任务：Cron 与 Wake 等技能或内置能力，用于定时执行任务。
• 更新与回滚：遵循官方更新与回滚文档，在测试环境验证后再升级生产。

12.1 60 秒安全基线（强烈建议照抄）

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "${OPENCLAW_TOKEN}" },
  },
  session: { dmScope: "per-channel-peer" },
  tools: {
    profile: "messaging",
    deny: ["gateway", "cron", "sessions_spawn", "sessions_send"],
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
  logging: { redactSensitive: true },
}

十三、常见问题与排障表

Q：Gateway 启动失败？

运行 openclaw doctor 查看校验错误；使用 openclaw doctor --fix 或 --yes 应用迁移/修复。确保 openclaw.json 符合 Schema，无未知键或类型错误。

Q：国内无法访问 Claude API？

在运行 OpenClaw 的服务器上配置 HTTP(S)/SOCKS 代理，或将部署放在香港/新加坡等可访问境外 API 的节点。

Q：技能安装后不生效？

确认技能已 enable（openclaw skills list --status ready）；检查 skills.entries 中该技能的 API Key 或环境变量是否配置；必要时重启 Gateway。

Q：如何限制谁可以触发机器人？

使用各渠道的 allowFrom、groupPolicy + 群组白名单、pairing 配对码等；多智能体场景下用 bindings 将不同渠道/账号路由到不同智能体。

Q：更多问题？

请查阅 官方文档 与社区，或通过下方「咨询途径」联系科施博技术团队。

13.1 排障对照表（最常见的 8 个坑）

十四、术语表（小白翻译）

十五、高级篇：生产部署与安全（进阶读者必看）

前面的章节已经帮助你在本机 / WSL2 / Docker 上跑通了 OpenClaw，并接入了至少一个渠道。这个高级篇假设你已经完成了这些基础操作，接下来要把它变成可长期运行、可多人协作、可审计的生产级系统。

15.1 生产环境推荐架构与流程

1. 环境切分：开发 / 测试 / 生产
   • 为每个环境准备单独的 openclaw.json 或使用 $include 拆分 base.json5 + prod.json5。
   • 开发环境可以使用本机或 WSL2，生产环境推荐使用国内云（华为云 / 阿里云 / 腾讯云等）。
   • 不同环境之间不要共用 Gateway Token / 模型 Key / 渠道 Bot。
2. 网关部署形态
   • 推荐：Docker Compose 在服务器上常驻运行，Gateway 仅监听内网或 127.0.0.1。
   • 通过 Nginx / Caddy 做 HTTPS 反向代理，对外只暴露 443 端口，隐藏 18789。
   • 内网访问可以直接访问网关，外网访问通过 VPN / Tailscale / SSH 隧道或反代进入。
3. 上线流程示例（从测试到生产）
   • 在测试环境完成：模型配置、两个典型使用案例、至少 1 个渠道的群聊验证。
   • 将 openclaw.json 拆分为通用配置 + 生产覆盖配置，并使用 Git 管理版本。
   • 在生产服务器上以 Compose 形式部署，先只对少量内部人员开放，再逐步扩大范围。

15.2 openclaw.json 高级配置策略

• 拆分配置文件
  • 在主配置中只保留结构与默认值，例如 agents / channels / session 策略。
  • 通过 $include 引入 ./conf/dev.json5、./conf/prod.json5 等环境专属配置。
  • 敏感信息（Token、API Key）优先放在环境变量中，通过 env 节点引用。
• 多智能体与路由
  • 为不同业务场景（客服、内部工具、代码审查等）定义不同的 agent，并配置各自的 workspace 与 tools。
  • 通过 bindings 和 session.dmScope 控制：谁从哪个渠道来，会路由到哪个智能体。
  • 使用清晰的命名规范，例如 agent_support_cn、agent_dev_tools，便于团队协作。
• 日志与审计
  • 开启 logging.redactSensitive，避免日志中出现完整 Token、手机号、身份证号等信息。
  • 为生产环境配置独立的日志目录，并定期轮转与备份。
  • 关键操作（例如 tools 调用外部系统、批量修改数据）建议额外记录审计日志（可通过自定义 Skill 实现）。

15.3 多渠道 / 多团队协作设计

当你既要服务外部客户（例如飞书 / 企业微信），又要服务内部研发（例如 Telegram / Slack）时，可以采用如下设计：

• 按“人群 + 语言 + 敏感度”拆分渠道
  • 外部客户：飞书 / 企业微信渠道，Agent 只开放与客户相关的 Skills，不访问内部代码库。
  • 内部技术团队：Telegram / Slack 渠道，Agent 可以访问 Git、CI、监控等敏感资源。
  • 个人助理：WhatsApp / 私人 Telegram Bot，仅绑定到个人账户或小范围群。
• 按“场景”拆分 Agent
  • 支持场景：agent_support_cn 负责中文客服与知识库问答。
  • 运维场景：agent_ops 负责监控、日志查询、变更建议。
  • 自动化场景：agent_automation 负责定时任务、批量操作等。
• 配合权限系统
  • 使用 IM 平台自身的群权限与成员管理，控制谁可以拉机器人进群、谁可以触发敏感命令。
  • 对高风险操作（重启服务、删除数据等）增加“二次确认”或人工审批流程。

15.4 生产安全与合规清单

1. 入口安全
   • Gateway 不直接暴露在公网，优先使用 HTTPS 反向代理或 VPN。
   • 配置 gateway.auth.mode 与强随机的 token，关闭匿名访问。
   • 对 IM 频道启用 pairing / allowlist / requireMention，避免被陌生人刷消息。
2. 工具与文件安全
   • 限制文件系统访问范围，只允许访问指定 workspace 与数据目录。
   • 对执行类工具（如 shell / exec）采用“默认禁止，按需放行”的策略。
   • 对外部 API 调用（尤其是涉及个人信息 / 业务数据的）进行域名与 IP 白名单控制。
3. 合规与审计
   • 根据公司与行业要求，评估是否需要对会话内容进行脱敏或加密存储。
   • 为管理员与运维人员设置独立账号，避免多人共用一个高权限账号。
   • 定期导出审计日志并与安全团队一起评估异常行为。

15.5 运维、升级与故障预案

• 运维日常
  • 通过 openclaw status、openclaw gateway status、openclaw logs --follow 做日常健康检查。
  • 为关键容器启用自动重启策略（如 Docker 的 restart: always）。
  • 监控 CPU / 内存 / 磁盘与网络延迟，避免大模型调用导致资源打满。
• 升级策略
  • 先在测试环境升级镜像与配置，跑完整回归用例（包括几条典型会话与工具调用）。
  • 生产环境采用蓝绿发布或滚动升级，必要时可以快速回滚到上一版本镜像。
  • 升级前备份关键配置与数据目录，记录当前版本号与变更内容。
• 故障预案
  • 为“服务不可用”、“回复异常慢”、“消息不再推送”等情况预先写好排查脚本或操作手册。
  • 准备“降级方案”：例如在模型不可用时退回到简单 FAQ / 知识库检索。
  • 为核心业务场景设定 RTO / RPO 目标，并定期演练恢复流程。