OpenClaw 完整教程：从安装到第一个自动化工作流

OpenClaw 是一款运行在本地的开源 AI 代理，通过 WhatsApp、Telegram、Slack 等你已在使用的消息工具接收指令，自动执行邮件管理、代码运行、文件操作等真实任务。本教程覆盖从环境安装到配置第一个自动化工作流的完整流程，预计耗时 15-30 分钟，所有步骤可在 macOS / Linux / Windows（WSL2）上执行。

第一章：环境准备

系统要求

项目	要求
操作系统	macOS、Linux、Windows（推荐 WSL2）
Node.js	22 及以上（必须满足）
AI 模型 API Key	Anthropic / OpenAI / 七牛云等任选其一
安装耗时	约 5 分钟

检查 Node.js 版本

node --version
# 输出需为 v22.x.x 或更高

若版本不满足，使用 nvm 升级：

nvm install 22 && nvm use 22 && nvm alias default 22

第二章：安装 OpenClaw

推荐方式：一键安装脚本

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

脚本会自动检测系统类型、安装依赖并完成初始化。

备选方式：npm 手动安装

npm install -g openclaw@latest

验证安装成功

openclaw --version
# 应输出版本号，例如：openclaw/2.x.x

第三章：Onboard 初始化

安装完成后，运行引导式初始化向导：

openclaw onboard --install-daemon

--install-daemon 参数会将 OpenClaw Gateway 注册为系统后台服务（macOS 使用 launchd，Linux 使用 systemd），开机自动启动，无需手动运行。

Onboard 向导会引导完成：

模型提供商选择与 API Key 配置
通信渠道连接（Telegram / WhatsApp 等）
Gateway 守护进程安装
基础配置文件生成（~/.openclaw/openclaw.json）

完成后运行诊断确认一切正常：

openclaw doctor
# 预期输出：No blocking issues found

第四章：配置 AI 模型

OpenClaw 支持多个模型提供商，通过 provider/model 格式指定。

方式一：使用 Anthropic Claude（国际）

# 设置 API Key
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

在 ~/.openclaw/openclaw.json 中配置：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-haiku-4-5"]
      }
    }
  }
}

方式二：使用七牛云推理服务（国内推荐）

七牛云推理服务兼容 OpenAI 标准接口，可接入 DeepSeek V3.2、Kimi K2.5、GLM-5 等国产主流模型，网络延迟低，无数据出境问题。

# ~/.openclaw/.env（API Key 存放此处，不写入配置文件）
QINIU_API_KEY=sk-your-qiniu-key-here

配置文件中指定模型：

{
  agents: {
    defaults: {
      model: {
        primary: "qiniu/deepseek-v3.2-251201",
        fallbacks: ["qiniu/z-ai/glm-5"]
      }
    }
  }
}

七牛云可用模型速查：

模型 ID	说明	上下文窗口
`qiniu/deepseek-v3.2-251201`	DeepSeek V3.2，综合推理	128K
`qiniu/moonshotai/kimi-k2.5`	Kimi K2.5，长文档处理	256K
`qiniu/z-ai/glm-5`	GLM-5，中文对话	128K
`qiniu/minimax/minimax-m2.5`	Minimax M2.5	128K

第五章：连接通信渠道

OpenClaw 支持 30+ 通信平台，以下以最常用的 Telegram 为例。

Telegram 配置（完整步骤）

Step 1：在 Telegram 创建 Bot

打开 Telegram，搜索 @BotFather，发送：

/newbot

按提示输入 Bot 名称，BotFather 会返回一个 Token，格式类似 1234567890:ABCDefGHIJKlmNoPQRstuVWXyz。

Step 2：写入配置文件

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",  // 或直接填 Token
      dmPolicy: "pairing",  // 首次使用推荐 pairing
    }
  }
}

将 Token 存入环境变量文件：

# ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=1234567890:ABCDefGHIJKlmNoPQRstuVWXyz

Step 3：启动 Gateway

openclaw gateway start

Step 4：完成配对

在 Telegram 向你的 Bot 发送任意消息，Bot 会返回一个 6 位配对码。然后在终端执行：

# 查看待配对请求
openclaw pairing list telegram

# 批准配对（替换为实际配对码）
openclaw pairing approve telegram <CODE>

配对成功后，向 Bot 发送消息，OpenClaw 将开始响应。

其他渠道快速配置

{
  channels: {
    // Discord：需在 Discord Developer Portal 创建应用并获取 Bot Token
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}"
    },
    // Slack：需在 Slack API 平台创建 App
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      appToken: "${SLACK_APP_TOKEN}"
    }
  }
}

第六章：配置文件完整结构

~/.openclaw/openclaw.json 是 JSON5 格式（支持注释和尾随逗号），以下是覆盖主要功能的参考配置：

{
  // Gateway 基础设置（修改后需重启）
  gateway: {
    mode: "local",
    port: 18789,
    reload: { mode: "hybrid", debounceMs: 300 }
  },

  // AI 模型配置
  agents: {
    defaults: {
      model: {
        primary: "qiniu/deepseek-v3.2-251201",
        fallbacks: ["qiniu/z-ai/glm-5"]
      },
      // 心跳检测：每 30 分钟向最近联系的渠道发送存活信号
      heartbeat: { every: "30m", target: "last" }
    }
  },

  // 通信渠道（热重载，修改后无需重启）
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }  // 群组需 @Bot
    }
  },

  // 会话管理（热重载）
  session: {
    dmScope: "per-channel-peer",  // 每个用户独立会话
    reset: { mode: "daily", atHour: 4 }  // 每天凌晨 4 点重置
  },

  // 定时任务（热重载）
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h"
  },

  // Webhook 自动化（热重载）
  hooks: {
    enabled: true,
    token: "${WEBHOOK_SECRET}",
    path: "/hooks"
  }
}

第七章：发送第一条指令

Gateway 启动、渠道配对完成后，在 Telegram 向 Bot 发送：

帮我列出 ~/Downloads 目录下最近 5 个修改的文件

OpenClaw 会调用系统工具执行 ls 命令并返回结果。

进阶指令示例：

总结 ~/Documents/report.pdf 的核心内容，不超过 200 字

检查一下 https://github.com/hiyouga/LLaMA-Factory 最近有什么新的 release

把这段话翻译成英文并帮我润色：[内容]

第八章：进阶功能

8.1 Cron 定时任务

在配置文件中添加定时任务，实现无需指令的自动化：

{
  cron: {
    enabled: true,
    jobs: [
      {
        id: "morning-briefing",
        schedule: "0 8 * * 1-5",   // 工作日早 8 点
        prompt: "总结昨天 GitHub 上的重要更新，推送到 Telegram",
        channel: "telegram"
      },
      {
        id: "weekly-summary",
        schedule: "0 9 * * 0",     // 每周日早 9 点
        prompt: "生成本周工作总结并发送给我",
        channel: "telegram"
      }
    ]
  }
}

8.2 Webhook 触发器

配置外部系统（GitHub、监控平台等）通过 Webhook 触发 OpenClaw：

{
  hooks: {
    enabled: true,
    token: "${WEBHOOK_SECRET}",
    mappings: [
      {
        match: { path: "github-pr" },
        action: "agent",
        agentId: "main",
        // GitHub PR 创建后自动进行代码审查
        deliver: true
      }
    ]
  }
}

在 GitHub 仓库 Settings → Webhooks 中填写：

Payload URL：http://your-server:18789/hooks/github-pr
Secret：与 WEBHOOK_SECRET 一致

8.3 多代理工作区

OpenClaw 支持配置多个独立代理，各自拥有独立的上下文和工具权限：

{
  agents: {
    main: {
      model: { primary: "qiniu/deepseek-v3.2-251201" },
      description: "主代理，处理日常任务"
    },
    coder: {
      model: { primary: "qiniu/moonshotai/kimi-k2.5" },
      description: "代码专用代理，长上下文处理"
    }
  }
}

发送指令时可指定代理：@coder 帮我 review 这段代码

第九章：常用命令速查

# ── 生命周期管理 ──────────────────────────────
openclaw gateway start          # 启动 Gateway
openclaw gateway stop           # 停止 Gateway
openclaw gateway restart        # 重启 Gateway
openclaw gateway status --deep  # 查看详细状态（含 RPC probe）
openclaw gateway install --force  # 强制重装 Daemon 元数据

# ── 诊断与调试 ────────────────────────────────
openclaw doctor                 # 健康检查
openclaw doctor --fix           # 自动修复
openclaw logs --follow          # 实时日志
openclaw logs | grep ERROR      # 过滤错误日志
openclaw status                 # 整体状态概览

# ── 渠道管理 ──────────────────────────────────
openclaw channels login         # 连接/重连渠道
openclaw channels status --probe  # 检测渠道连通性
openclaw pairing list telegram  # 查看待配对请求
openclaw pairing approve telegram <CODE>  # 批准配对

# ── 配置管理 ──────────────────────────────────
openclaw config get model       # 查看当前模型配置
openclaw config set gateway.mode local  # 设置配置项
openclaw config unset <key>     # 删除配置项
openclaw configure              # 交互式配置向导

# ── 其他 ──────────────────────────────────────
openclaw models                 # 查看已配置模型
openclaw --version              # 查看版本号

常见问题

Q：Onboard 完成后 Telegram Bot 不响应消息，怎么排查？
按顺序检查：① openclaw gateway status 确认 Runtime: running；② openclaw channels status --probe 确认 Telegram 渠道状态为 connected；③ openclaw logs | grep drop 查看是否存在消息被静默丢弃（常见原因：dmPolicy: "pairing" 下未完成配对）。

Q：配置文件修改后需要重启吗？
视配置类型而定。channels、session、cron、hooks、agents.defaults.model 支持热重载，修改后无需重启。gateway.port、gateway.auth、gateway.bind 等基础设施配置修改后需运行 openclaw gateway restart。

Q：如何同时连接多个 Telegram 账号（Bot）？
在 channels.telegram 下配置 accounts 数组，每个账号独立的 botToken 和策略，OpenClaw 会同时监听多个 Bot。

Q：定时任务（Cron）的时区是什么？
默认使用服务器本地时区。如需指定时区，在 job 配置中添加 timezone: "Asia/Shanghai"。

Q：OpenClaw 有没有 Docker 一键部署方案？
有。官方提供 Docker 镜像，适合服务器环境：

docker run -d \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/gateway:latest

挂载配置目录后，与本地安装方式配置完全一致。

总结

至此，你已完成 OpenClaw 从安装到第一个工作流的全部流程：

✅ Node.js 22+ 环境准备
✅ 安装 + Onboard 初始化
✅ 配置 AI 模型（七牛云/Anthropic）
✅ 接入 Telegram 渠道完成配对
✅ 理解配置文件结构
✅ 发送第一条指令
✅ 了解 Cron / Webhook / 多代理进阶能力

下一步建议：在 Telegram 向 Bot 描述一个你的实际工作流（比如"每天帮我汇总 GitHub 通知"），让 OpenClaw 自动生成并保存对应的 Cron 任务配置——自然语言创建技能是 OpenClaw 最被低估的能力之一。

本文基于 OpenClaw 官方文档（docs.openclaw.ai）及七牛云开发者平台（2026 年 3 月），命令语法建议以 openclaw --version 对应版本文档为准。

延伸资源

OpenClaw 官方文档：https://docs.openclaw.ai
Telegram 渠道配置详解：https://docs.openclaw.ai/channels/telegram
七牛云 AI 推理服务 API Key 申请：https://portal.qiniu.com/ai-inference/api-key
七牛云 OpenClaw 配置指南：https://developer.qiniu.com/aitokenapi/13332/openclaw-installation-cuide

posted @ 2026-03-10 13:35 七牛云行业应用阅读(149) 评论(0) 收藏举报

刷新页面返回顶部

qiniushanghai