◉ DECK/ MISSION LOG/ OPENCLAW

OpenClaw 龙虾

STARDATE 2026.088 · ◷ 8 min read ·
#AI Coding

OpenClaw 架构

~/.openclaw/ 是 OpenClaw 的“神经中枢”，里面存放着所有配置和状态。

~/.openclaw/
├── openclaw.json        # 全局配置文件
├── gateway/             # Gateway 相关
│   ├── config.json      # Gateway 配置
│   ├── logs/            # 日志目录
│   └── pid              # 进程 ID 文件
├── plugins/             # 插件目录
│   ├── @openclaw/       # 官方插件
│   └── @wecom/          # 第三方插件
├── workspaces/          # Agent 工作区
│   ├── default/         # 默认 Agent
│   └── paigit/          # 自定义 Agent
├── skills/              # 技能包
├── cache/               # 缓存目录
└── .env                 # 环境变量

Gateway

  1. 接收消息

    飞书把消息推送到Gateway。Gatwway收到后，解析消息内容，识别是哪个agent、哪个会话。

  2. 分发任务

    Gateway 把消息路由给对应的 Agent 处理。如果你配置了多个 Agent（比如一个负责代码审核，一个负责会员审批），Gateway 会根据消息来源判断该交给谁。

  3. 返回结果

    Agent 处理完任务后，把结果交给 Gateway，Gateway 再通过 IM 通道发回飞书。

Gateway 负责 IM 通信，Agent 负责任务执行。这样可以一个 Gateway 挂多个 Agent，每个 Agent 用不同的模型、跑不同的任务，互不干扰。

插件

核心只提供最基础的能力——消息收发、任务调度、工具调用。其他功能全部通过插件扩展。

OpenClaw 实操

成员加入Github仓库，开通访问权限。

以前的流程：会员申请加入 -> 我收到通知 -> 手动打开 gitcode 后台 -> 搜索用户昵称 -> 添加到对应的项目组 -> 发消息通知会员审核通过

把任务交给OpenClaw

  1. 创建一个专属 Agent

    openclaw agents add PaiGit --workspace ~/openclaw-workspaces/paigit

  2. 配置 BOOT.md 告诉 Agent 它的职责

    # PaiGit 职责
你是技术派的 gitcode 账号审核助手。

当收到飞书消息包含用户昵称时：

1. 登录 gitcode 后台
2. 搜索用户
3. 添加到技术派-会员组
4. 回复审核结果

  3. 绑定飞书通道

    在飞书群，直接发消息，让OpenClaw开始流程。

    配置Webhook实现飞书群消息同步

    每个飞书群都有一个 Webhook 地址，可以在群设置里找到。

    把这些 Webhook 地址告诉 OpenClaw

    发送同步指令

    OpenClaw 支持用自然语言创建定时任务。

    定时任务的底层实现是 cron。OpenClaw 会把自然语言转成 cron 表达式，然后在后台调度执行。

OpenClaw 优化

Token优化

  • prompt 压缩：去除冗余信息，只传必要上下文
  • 上下文裁剪：只保留最近 N 轮对话
  • 结果缓存：相同问题直接返回缓存结果

响应慢

  • 流式输出：边生成边返回，减少用户等待
  • 异步处理：复杂任务后台执行，先返回 ACK
  • 模型选择：简单任务用 Lite 模型，复杂任务用 Pro 模型

费用控制

  • 配额管理：每天/每月设置 token 上限
  • 成本追踪：记录每个任务的 token 消耗
  • 自动降级：额度用完时切换到便宜模型

踩坑

排查Gateway启动收不到消息

第一步：检查日志

cat ~/.openclaw/gateway/logs/error.log

看有没有报错信息。常见错误有：飞书 App ID 填错、权限没开通、事件订阅没配置。

第二步：检查通道状态

openclaw channels status

看飞书/企微通道是不是正常连接。

第三步：检查飞书配置

去飞书开放平台，确认：

  • 事件订阅已开启
  • im.message.receive_v1 事件已添加
  • 长链接模式已启用

多Agent路由机制

真正决定多 Agent 路由的，就是 dmPolicy 和 bindings 这两个点。

dmPolicy

dmPolicy 全称 Direct Message Policy，控制机器人如何处理私信。有三种策略可选：

{
  "dmPolicy": {
    "app1": "allow",      // 允许所有私信
    "app2": "deny",       // 拒绝所有私信
    "app3": "pairing"     // 只允许配对过的用户私信
  }
}

bindings

bindings 是 OpenClaw 多 Agent 路由的核心机制。它定义了消息应该如何分配给不同的 Agent。

{
  "bindings": [
    {
      "agentId": "CodeReview",
      "match": {
        "channel": "feishu",
        "accountId": "cli_xxx1",
        "peer": {
          "type": "group",
          "id": "oc_xxx"
        }
      }
    },
    {
      "agentId": "DevOps",
      "match": {
        "channel": "feishu",
        "accountId": "cli_xxx2"
      }
    }
  ]
}

channel是消息来源，比如 feishu、wecom；accountId是飞书应用的 App ID；peer是发送者信息，type可以是 user 或 group，id是对应的 ID。

groupPolicy

{
  "groupPolicy": {
    "requireMention": true,    // 群组中是否需要@机器人
    "allowAnonymous": false    // 是否允许匿名消息
  }
}

Gateway 网关架构

链路

飞书消息 → Gateway → Agent → 大模型 → Agent → Gateway → 飞书回复

Gateway 和飞书之间如何通信

WebSocket 长连接。飞书开放平台提供了事件订阅机制，Gateway 启动时会向飞书注册一个 WebSocket 连接。之后飞书有消息就会主动推过来。

认证方式用的是 Token 机制。在openclaw.json里配置的verificationToken和encryptKey，就是用来验证消息来源和解密消息内容的。

{
  "gateway": {
    "port": 18789,
    "auth": "token",
    "host": "0.0.0.0"
  }
}

高可用架构

Gateway 集群+负载均衡

部署多个 Gateway 实例，前面挂一个负载均衡器（如 Nginx）。飞书的 WebSocket 连接可以分发到不同实例。

会话状态下沉

把会话状态从本地磁盘迁移到 Redis，这样 Gateway 实例就变成无状态的了。任何一个实例挂掉，其他实例可以接管会话。

任务队列化

对于耗时任务，用消息队列（如 RabbitMQ）做缓冲，避免 Gateway 被阻塞。

会话管理与压缩

会话数据默认存在~/.openclaw/workspaces/<agent>/memory/目录下。每次对话会序列化保存，用 session_id 标识。Gateway 重启后可以恢复会话状态。

会话数据会越积越多，尤其是长对话场景。OpenClaw 提供了压缩机制：

{
  "memory": {
    "compression": true,
    "maxHistory": 20,      // 保留最近20轮对话
    "summarizeThreshold": 10   // 超过10轮后自动摘要
  }
}

上下文窗口

分层记忆设计

把记忆分成三层：

  • 短期记忆：最近 5 轮对话，完整保留
  • 中期记忆：6-20 轮对话，压缩存储
  • 长期记忆：超过 20 轮，只保留关键摘要

关键信息提取

在 BOOT.md 里告诉 Agent，哪些信息必须记住，哪些可以丢弃。

定期清理机制

设置定时任务，自动清理过期的会话数据。

OpenClaw 组件

**LLM：**这是 Agent 的大脑，负责理解指令、规划任务、生成回复。OpenClaw 支持多种模型，Claude、GPT、GLM 都可以接。

任务规划：把用户的自然语言需求，拆解成可执行的任务步骤。比如“帮我查天气”，会拆解成：调用天气 API → 解析返回数据 → 生成回复。

工具执行器：负责调用外部工具，比如搜索、文件操作、数据库查询等。每个工具都有明确的输入输出定义。

记忆管理器：管理 Agent 的短期记忆（Session）和长期记忆（Memory）。这是 Agent 能持续对话的关键。

技能加载器：动态加载 Skills，扩展 Agent 的能力。Skills 本质上是封装好的 Prompt 和工具组合。

组件之间通信

每个组件都是独立的，通过消息总线交换数据。

消息总线本质上是一个事件队列。

当组件 A 需要调用组件 B 时，不是直接调用，而是发送一个消息到总线。

Agent是常驻进程吗？

不是，Agent 是 per-session 的瞬态实例。

每个对话都是一次完整的加载-执行-销毁循环。

Session如何加载

Session 的加载是懒加载机制。当消息到达，路由到 SessionKey 之后，OpenClaw 会查找 sessions.json 获取当前 SessionId，然后把 SessionId 对应的.jsonl 文件加载到 Agent 中。

Memory

短期记忆（Session）：当前对话的上下文，存储在内存中。包括用户输入、Agent 回复、工具调用结果等。

长期记忆（Memory）：跨对话的持久化记忆，存储在磁盘上。包括用户偏好、历史事实、重要结论等。

← PREV MISSION
Claude Code 使用技巧