01-入门 · 从零跑通 OpenClaw

预计时间：30-60 分钟（取决于网络 + 飞书账号准备状态） 适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09 目标：让 gateway 跑起来，能从飞书机器人收到第一条回复

本章你会经历

1. 环境准备（Node 22.10+、git、飞书企业账号）
2. 安装 OpenClaw CLI
3. 初始化工作目录 ~/.openclaw/
4. 配置 AI 模型 provider
5. 配置飞书机器人（含 secrets 独立文件）
6. 启动 gateway
7. 运行 doctor 自检
8. 发飞书消息验证

---

1. 环境准备

1.1 系统要求

• macOS 12+：正式支持
• Linux：正式支持核心功能，关键自动化已提供 systemd / cron 对等方案
• Windows 原生：暂不支持
• Windows 用户请先在 WSL2 或测试环境验证
• Node.js 22.10+
• Git 2.30+
• 飞书企业版账号（不是个人版）+ 管理员权限

验证命令：

node -v    # 应 >= v22.10
npm -v     # 应 >= 10
git --version

1.2 至少准备一家 AI provider 账号

Provider	注册入口	说明
GPT 包月套餐	api.aigpt.club	⭐ 强烈推荐，多并发、推荐龙虾使用，联系作者有额外优惠
MiniMax	www.minimaxi.com	国内访问快，推荐入门使用
Anthropic	console.anthropic.com	Claude 系列
OpenAI	platform.openai.com	GPT 系列
SiliconFlow	cloud.siliconflow.cn	记忆系统 embedding 服务用，国内访问快、嵌入便宜

注册完成后在平台的「API Keys」页生成一个 Key，先不要填到任何地方，后面会用。

1.3 飞书开放平台准备

1. 访问 https://open.feishu.cn/
2. 用企业管理员账号登录（不是个人账号）
3. 进入「开发者后台」→「企业自建应用」→「创建应用」
4. 应用名称随意（如”小龙虾管家”）
5. 创建完成后记录 App ID 和 App Secret
6. 在「权限与功能」中开启：
   • im:message 发送消息
   • im:message:send_as_bot 以机器人身份发送
   • im:message.group_at_msg 群组 @ 消息
7. 「事件订阅」页先空着，gateway 启动后再填 URL

---

2. 安装 OpenClaw CLI

npm install -g openclaw@2026.5.2

💡 想隔离 node 版本用 nvm 或 volta。 想不装到系统目录，在安装前运行 npm config set prefix ~/.local 然后把 ~/.local/bin 加到 PATH。 本教程和付费模板当前公开稳定包以 2026.5.2 为基线；作者端已验证 2026.5.7，但不要把 openclaw@latest 当作默认目标，除非你已经按升级章节完成兼容性评估。

验证：

openclaw --version
# 输出形如：OpenClaw 2026.5.2 (...)

---

3. 初始化工作目录

openclaw setup
# 交互式：openclaw setup --wizard
# 非交互：openclaw setup --non-interactive

💡 另外有 openclaw onboard / openclaw configure 用于首次引导配置，都会写入 ~/.openclaw/openclaw.json。

setup 完成后会出现 ~/.openclaw/ 目录，核心子目录：

路径	作用
~/.openclaw/openclaw.json	主配置文件（绝不放密钥）
~/.openclaw/credentials/	独立密钥目录（appSecret / apiKey 等）
~/.openclaw/agents/	每个 agent 的工作空间
~/.openclaw/shared/	所有 agent 共享的 SOUL / AGENTS / TOOLS 规范
~/.openclaw/workspace/	主（main）agent 的工作空间 + 记忆
~/.openclaw/scripts/	运维脚本（launchd plist 等）
~/.openclaw/logs/	gateway + cron 任务日志
~/.openclaw/memory/lancedb-pro/	语义记忆数据库（LanceDB）

---

4. 配置 AI provider

推荐做法：用 CLI 命令登录，不要手写 auth 段。

# 示例：注册一个 minimax provider profile
openclaw models auth login --provider minimax-portal --method oauth --set-default

# 或 anthropic + claude CLI 托管
openclaw models auth login --provider anthropic --method cli --set-default

登录后 ~/.openclaw/openclaw.json 的 auth.profiles 会被自动填充：

{
  "auth": {
    "profiles": {
      "minimax-portal:default": {
        "provider": "minimax-portal",
        "mode": "oauth"
      }
    }
  }
}

安全建议：apiKey / token 永远不 inline 写进 openclaw.json。用 secrets.providers.* 引用外部文件（格式见下一节）。详见 02-配置/02-Skills选择 的 secrets 章节。

---

5. 配置飞书

5.1 创建独立的 secrets 文件

这一步的核心原则：appSecret 绝对不放主配置。主配置会被备份 / 版本化 / 分享，secrets 单独放便于隔离。

mkdir -p ~/.openclaw/credentials
cat > ~/.openclaw/credentials/lark.secrets.json <<'EOF'
{
  "lark": {
    "appSecret": "<你的 App Secret>"
  }
}
EOF
chmod 600 ~/.openclaw/credentials/lark.secrets.json

5.2 在 openclaw.json 里声明飞书频道 + secrets 引用

追加这两块到 ~/.openclaw/openclaw.json：

{
  "secrets": {
    "providers": {
      "lark-secrets": {
        "source": "file",
        "path": "~/.openclaw/credentials/lark.secrets.json"
      }
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "<你的 App ID>",
      "appSecret": {
        "source": "file",
        "provider": "lark-secrets",
        "id": "/lark/appSecret"
      },
      "domain": "feishu",
      "connectionMode": "websocket",
      "webhookPath": "/feishu/events",
      "dmPolicy": "allowlist",
      "groupPolicy": "allowlist",
      "accounts": {
        "default": {
          "allowFrom": ["<你的飞书 open_id>"],
          "replyMode": { "default": "streaming" }
        }
      }
    }
  }
}

字段速记：

• connectionMode: websocket —— 走长连接，不需要公网回调 URL（本章第 8 节的内网穿透仅在 websocket 不可用时才需要）
• appSecret.source=file + provider=lark-secrets + id=/lark/appSecret —— 把 lark.secrets.json 里的 lark.appSecret 字段引用进来
• dmPolicy=allowlist + accounts.default.allowFrom —— 只让白名单里的 open_id 私聊机器人（防止陌生人调 agent 刷 token）
• 完整字段清单（18 项）见 02-配置/03-飞书深度配置

---

6. 启动 gateway

gateway 有两种启动方式：

场景	命令	说明
调试 / 临时跑	openclaw gateway run	前台运行，Ctrl+C 退出
日常使用	openclaw gateway install + start	托管给 launchd / systemd，开机自启、崩溃自动拉起

6.1 前台跑一遍（首次验证）

openclaw gateway run --port 18789

正常启动后会输出 gateway 监听信息。另开一个终端验证：

18789/health

openclaw gateway health

6.2 托管为系统服务（推荐用于日常）

# 首次装服务（macOS 写 launchd plist / Linux 写 systemd unit）
openclaw gateway install

# 启动 + 开机自启
openclaw gateway start

# 管理命令
openclaw gateway status    # 服务状态 + health 探测
openclaw gateway restart   # 重启
openclaw gateway stop      # 停服务
openclaw gateway uninstall # 卸载服务（不删配置）

6.3 端口冲突处理

如果 18789 被占：

lsof -iTCP:18789 -sTCP:LISTEN
# 看看是谁占了，换端口或停掉占用者
openclaw gateway run --force --port 18789   # 强杀占用者后启动
# 或换端口：
openclaw gateway run --port 18790

端口改了记得同步改 openclaw.json 里的 gateway.port，否则 start / status 会用配置里的旧端口。

---

7. 运行 doctor 自检

openclaw doctor

doctor 会检查：

• Node 版本、目录权限
• gateway 连通性
• API Key 是否可用
• 飞书配置完整性
• 敏感文件权限（credentials/ 应为 600）

有 ❌ 按提示修，全 ✅ 再继续。 不要跳过 doctor 直接发消息验证，90% 的”飞书不回复”是这一步没做干净。

---

8. 飞书回调配置（最后一步）

8.1 两种接入模式

模式	配置字段	是否需要公网	推荐场景
长连接（websocket）	connectionMode: "websocket"	否	个人 / 小团队 / 内网机器
HTTP 回调	connectionMode: "http" + webhookPath: "/feishu/events"	是	有公网域名 + HTTPS

默认走 websocket（第 5 节配置已经是 websocket），飞书 SDK 主动连飞书长链路，本机 gateway 不用暴露到公网，省掉内网穿透这步。如果你走 websocket，可以跳过 8.2。

8.2 仅 HTTP 模式：把 gateway 暴露到公网

把 connectionMode 改成 "http" 才需要这步。三种暴露方式：

方案	适用	优缺点
有公网服务器	长期使用	最稳，需域名 + HTTPS
内网穿透（cpolar / frp / ngrok）	本机开发	免费方案够用，url 可能变动
云服务器 + ssh 反向代理	临时	灵活

得到公网地址后（形如 https://your-domain.com），把 webhookPath（默认 /feishu/events）拼在后面作为飞书事件订阅 URL。

8.3 飞书事件订阅（两种模式都要做）

回飞书开放平台 →「事件订阅」：

1. HTTP 模式：填回调 URL；websocket 模式：选「长连接」模式
2. 记录飞书给的 Verification Token 和 Encrypt Key
3. 追加到 ~/.openclaw/credentials/lark.secrets.json：

{
  "lark": {
    "appSecret": "<你的 App Secret>",
    "verificationToken": "<飞书给的>",
    "encryptKey": "<飞书给的>"
  }
}

4. 重启 gateway 让新 secrets 生效：

   openclaw gateway restart

8.4 订阅消息事件

在飞书开放平台「事件订阅」的事件列表里添加：

• im.message.receive_v1 —— 接收消息（必选）
• im.message.reaction.created_v1 —— 消息表情反应（可选）

---

9. 验证

在飞书中搜索你的机器人名称，添加为好友，发条私聊消息（如”你好”）。

• ✅ 成功：机器人在 5-10 秒内回复

• ❌ 无回复：按顺序查：

  # 1. gateway 还活着吗
  curl http://127.0.0.1:18789/health
  
  # 2. 公网穿透还连着吗
  curl https://<你的公网地址>/health
  
  # 3. 日志里有什么错
  tail -100 ~/.openclaw/logs/gateway.err.log

  更多排障：05-排障/00-常见问题

---

10. 下一步

到这里你已经有了一个单 agent OpenClaw，它能收发飞书消息但没有记忆。继续：

• 02-配置/01-记忆系统 —— 搭建五层记忆架构（跳过这步，agent 每次对话都像金鱼）
• 03-多Agent/00-协作拓扑 —— 为什么要多 agent + 怎么设计分工
• 04-运维/00-健康检查 —— 日常怎么确认系统没挂

---

验证清单

检查项	命令	期望
gateway 健康	curl http://127.0.0.1:18789/health	{"ok":true}
doctor 通过	openclaw doctor	无 ❌
飞书连通	向机器人发消息	5-10 秒内回复
credentials 权限	ls -l ~/.openclaw/credentials/lark.secrets.json	-rw-------

四项都 ✅，你完成了第 1 章。

---

这篇教程的准确性保证 本章所有命令 / 路径 / 端口都对着真实生产环境的 ~/.openclaw/scripts/start-gateway.sh、~/.openclaw/shared/TOOLS.md、~/.openclaw/openclaw.json 交叉验证。后续如 OpenClaw 官方调整字段或命令，会在新版本发版时同步更新。

---

导航：← 概述 · 📖 目录 · → 基础配置