OpenClaw

OpenClaw 是一个本地运行、可自托管的开源AI助手，它的核心是通过模块化协作，让AI从“回答问题”升级为“自主完成任务”。

运行环境：Node.js 22+（跨平台：Windows/macOS/Linux/ 树莓派）
模型层：对接外部 LLM（Claude 3.5/4、GPT-4o、Gemini、通义千问、Ollama 本地模型），自身不内置模型
通信协议：WebSocket（持久连接）、MCP（Model Context Protocol，Anthropic 标准）
存储：本地文件系统（Markdown 记忆）+ 向量数据库（语义检索）+ JSONL 日志

工作机理：

整体流程
在这里插入图片描述

1. Gateway：所有请求的第一站

Gateway 是系统的“总调度中心”，所有用户请求都从这里进入。

  • 核心职责：
    • 身份验证：确认用户身份，确保安全访问。
    • 连接管理：统一管理来自网页、手机、聊天软件等多渠道的连接。
    • 多用户隔离：为不同用户创建独立的会话沙箱，防止数据泄露。
    • 请求路由：将标准化后的指令准确分发给 Agent 处理。
  • 作用：没有 Gateway，系统就无法识别和响应用户指令，它就像你家门口的门卫，负责接待和引导。
内部实现细节

  1. 技术选型

    • 开发框架：FastAPI/Go Gin（轻量、高性能的 HTTP 框架）
    • 通讯协议：HTTP/JSON（对外） + gRPC（对内和 Agent 通信）
    • 存储依赖：Redis（会话管理、令牌存储）

  2. 核心功能实现

    • 身份验证：
      • 实现方式：基于 JWT（JSON Web Token）的无状态认证
      • 流程：
        1. 用户首次登录（如网页端），Gateway 验证账号密码后生成 JWT（包含用户 ID、过期时间）
        2. 后续请求携带 JWT，Gateway 解密验证签名和有效期，提取用户 ID
      • 关键代码思路： 
        # 伪代码：JWT 验证逻辑
def authenticate(token: str) -> str:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        user_id = payload.get("user_id")
        if not user_id:
            raise AuthenticationError("无效的用户ID")
        return user_id
    except jwt.ExpiredSignatureError:
        raise AuthenticationError("令牌已过期")
    • 多用户隔离：
      • 实现方式：基于“用户 ID + 会话 ID”的双层沙箱
      • 具体逻辑：
        1. 每个用户有唯一 user_id，每个对话生成唯一 session_id
        2. 所有请求都会带上这两个 ID，Gateway 把请求路由到对应用户的 Agent 会话
        3. Redis 中以 user:{user_id}:session:{session_id} 为 key 存储会话上下文，不同用户数据完全隔离
    • 请求路由：
      • 实现方式：基于“模块路由表”的动态转发
      • 核心逻辑：
        1. 维护一个路由表（JSON/配置文件），映射“指令类型”到“目标模块”
        2. 例如：{"type": "file_operation", "target": "nodes_service"}
        3. Gateway 解析请求的指令类型，自动转发到对应模块的 API 地址

  3. 关键特性

    • 限流：基于用户 ID 做接口限流（如 100 次/分钟），防止恶意请求
    • 日志：记录所有请求的入参、出参、耗时，方便问题排查
    • 重试：对转发失败的请求（如 Agent 暂时不可用）做 2 次自动重试

2. Channels：沟通热线

Channels 是 Gateway 的“前端接口”，负责连接各种通讯工具。

  • 支持平台：网页、WhatsApp、Telegram、飞书等。
  • 工作方式：将不同平台的消息格式统一转换成系统能理解的标准格式，再传递给 Gateway。
  • 优势：让你可以在任何熟悉的聊天工具里下达指令，换通信方式不换助理。
内部实现细节

  1. 技术选型

    • 开发框架：Python/Node.js（易对接第三方 SDK）
    • 消息队列：RabbitMQ/Kafka（异步处理消息，避免阻塞）
    • 核心依赖：各平台官方 SDK（如 Telegram Bot API、飞书开放平台 SDK）

  2. 核心功能实现

    • 多平台适配：
      • 每个平台对应一个独立的 Adapter 类，例如 TelegramAdapter、FeishuAdapter
      • 统一输出格式：不管输入是哪种平台的消息，最终都转换成如下标准格式： 
        {
  "user_id": "u123456",
  "session_id": "s789012",
  "platform": "telegram",
  "content": "帮我打开电脑上的文档",
  "timestamp": 1710000000,
  "message_id": "msg_987654"
}
    • 消息接收：
      • 被动模式：对接平台的 WebHook（如飞书），平台推送消息到 Channels 的 WebHook 地址
      • 主动模式：对不支持 WebHook 的平台（如 WhatsApp），用定时轮询（10 秒/次）拉取新消息
    • 消息发送：
      • 反向适配：把 Gateway 返回的结果，再转换成对应平台的消息格式
      • 例如：把纯文本结果转换成 Telegram 的 Markdown 消息，或飞书的卡片消息

  3. 关键特性

    • 断线重连：轮询模式下如果网络中断，自动记录最后拉取的消息 ID，恢复后从断点继续
    • 消息去重：基于 message_id 做去重，避免重复处理同一消息
    • 错误处理：平台发送失败时（如用户拉黑机器人），记录错误并通知管理员

3. Agent：OpenClaw 的大脑

Agent 是整个系统的“决策中心”，负责理解意图并制定计划。

  • 核心人设：
    • 理解用户意图：解析自然语言指令，明确任务目标。
    • 制定分步计划：将复杂任务拆解为可执行的步骤。
    • 判断工具调用：根据任务需求，决定调用哪些 Nodes 或 Skills。
  • 技术架构：基于 LLM 的“观察-思考-执行-反思”推理循环系统。
    • 观察：获取当前环境和任务信息。
    • 思考：分析并制定下一步计划。
    • 执行：调用工具完成具体操作。
    • 反思：根据执行结果调整策略，直到任务完成。
内部实现细节

  1. 技术选型

    • 核心依赖：LLM API（如 OpenAI GPT-4、本地部署的 Llama 3）
    • 提示词框架：LangChain/LLaMA Index（简化提示词管理和工具调用）
    • 内存存储：Redis（临时上下文） + SQLite（任务计划）

  2. 核心功能实现

    • 观察（Observe）：
      • 输入数据：Gateway 传递的标准化消息 + Memory 加载的用户记忆 + Nodes 返回的设备状态
      • 数据整合：把所有信息拼接成 LLM 能理解的上下文： 
        上下文：用户历史习惯：不吃辣；当前设备状态：电脑已开机；用户当前指令：帮我点外卖
    • 思考（Think）：
      • 核心：通过结构化提示词引导 LLM 拆解任务、选择工具
      • 提示词模板示例： 
        你是 OpenClaw 的决策助手，需要完成以下步骤：
1. 解析用户指令的核心意图：{content}
2. 拆解为可执行的子任务（最多 5 步）
3. 选择需要调用的工具（可选：Nodes/Memory/Cron）
4. 输出格式为 JSON：{"intent": "", "sub_tasks": [], "tools": []}
      • LLM 输出示例： 
        {
  "intent": "点不辣的外卖",
  "sub_tasks": ["获取用户定位", "筛选不辣的商家", "生成订单"],
  "tools": ["Nodes（获取定位）", "Memory（读取不吃辣偏好）"]
}
    • 执行（Act）：
      • 工具调用：基于 LLM 输出的工具列表，调用对应模块的 API
      • 例如：调用 Nodes 的 get_device_location 接口获取用户电脑的定位
      • 任务调度：用简单的状态机管理子任务进度（如“待执行→执行中→已完成”）
    • 反思（Reflect）：
      • 实现方式：对比“任务目标”和“执行结果”，让 LLM 评估是否完成
      • 反思提示词示例： 
        任务目标：{intent}
执行结果：{execution_result}
请评估：1. 是否完成任务？2. 未完成的话，下一步该怎么做？
      • 闭环逻辑：如果未完成，自动回到“思考”阶段，调整子任务和工具选择

  3. 关键特性

    • 上下文窗口管理：当对话过长时，自动总结历史上下文，避免超出 LLM 的 token 限制
    • 工具调用容错：调用工具失败时（如 Nodes 离线），自动切换备选方案（如提示用户手动输入定位）
    • 任务中断/恢复：支持保存任务状态，用户下次可继续执行未完成的任务

4. Nodes：助理的眼和手

Nodes 是部署在你设备上的轻量客户端代理，是 AI 与现实世界交互的“手脚”。

  • 部署位置：安装在你的手机、电脑等设备上。
  • 核心能力：
    • 远程操作：打开文件、修改文档、调用摄像头、获取系统通知等。
    • 自动重连和心跳机制：确保与 Agent 的稳定通讯。
  • 工作流程：接收 Agent 的指令，在本地设备上执行操作，并将结果反馈回去。
内部实现细节

  1. 技术选型

    • 开发框架：Python（跨平台）/Electron（带 GUI）
    • 通讯方式：WebSocket（双向实时通信） + 长轮询（备用）
    • 系统交互：
      • Windows：调用 pywin32 库操作系统（如打开文件、模拟键鼠）
      • macOS：调用 appscript/osascript 执行系统命令
      • 手机：Android 用 AccessibilityService，iOS 用快捷指令（Shortcuts）

  2. 核心功能实现

    • 设备注册：
      • 首次启动 Nodes 时，自动生成设备 ID，向 Gateway 注册（需用户授权）
      • Gateway 记录“用户 ID-设备 ID”绑定关系，Agent 只能调用该用户绑定的设备
    • 指令执行：
      • 接收 Agent 的指令（JSON 格式），例如： 
        {
  "command": "open_file",
  "params": {"path": "C:/Users/xxx/Documents/笔记.md"},
  "task_id": "t123456"
}
      • 每个指令对应一个 Handler 函数，例如 handle_open_file(params)
      • 执行结果返回格式： 
        {
  "task_id": "t123456",
  "status": "success",
  "result": "文件已打开，路径：C:/Users/xxx/Documents/笔记.md",
  "error": ""
}
    • 心跳机制：
      • Nodes 每 30 秒向 Gateway 发送一次心跳包（包含设备状态：在线/忙碌/离线）
      • Gateway 若 5 分钟未收到心跳，标记设备为离线，并通知 Agent
      • 恢复在线时，Nodes 自动重连，并同步离线期间未执行的指令

  3. 关键特性

    • 本地权限控制：所有操作都需要用户提前授权（如文件访问权限、摄像头权限）
    • 操作日志：本地记录所有执行的指令，方便用户追溯
    • 离线缓存：离线时将指令缓存到本地文件，恢复在线后自动执行

5. Memory：助理的记忆系统

Memory 让 OpenClaw 能够“记住”你，越用越懂你。

  • 核心功能：
    • 用户偏好：记住你的习惯，比如“不吃辣”。
    • 习惯提醒：记住你的日程，比如“晚上十点提醒我”。
  • 技术架构：
    • 短期记忆：维护当前对话的上下文。
    • 长期记忆：使用 Markdown 文件和向量数据库存储用户偏好和历史信息。
    • 语义检索：通过智能理解，将用户需求转化为记忆，并在需要时快速检索。
内部实现细节

  1. 技术选型

    • 短期记忆：Redis（键值对，过期时间 24 小时）
    • 长期记忆：
      • 存储：Markdown 文件（结构化数据） + Chroma/DashScope（轻量向量数据库）
      • 嵌入模型：text-embedding-ada-002（OpenAI）/BGE（开源）
    • 检索框架：LangChain 的 VectorStoreRetriever

  2. 核心功能实现

    • 短期记忆：
      • 存储内容：当前对话的上下文（用户提问 + AI 回答）
      • 存储格式：Redis Hash，key = session:{session_id}，field = turn_1/turn_2
      • 过期策略：会话结束后 24 小时自动删除
    • 长期记忆：
      1. 记忆提取：
        • Agent 调用 Memory API，传入用户指令（如“帮我点外卖”）
        • Memory 将指令转换成向量，在向量数据库中检索相似记忆（如“不吃辣”）
      2. 记忆存储：
        • 当用户表达新偏好（如“我喜欢吃川菜”），Agent 调用 Memory 的 save_memory 接口
        • Memory 先提取关键信息（用户 ID、偏好类型、内容、时间戳）
        • 生成向量并存储到向量数据库，同时生成 Markdown 文件（方便人工查看）： 
          # 用户 u123456 的记忆
- 类型：饮食偏好
- 内容：喜欢吃川菜，不吃辣
- 更新时间：2026-03-03
    • 语义检索：
      • 核心逻辑：计算用户指令向量与记忆向量的余弦相似度，返回 Top3 最相似的记忆
      • 阈值控制：相似度 > 0.7 才返回，避免无关记忆干扰

  3. 关键特性

    • 记忆更新：当用户修改偏好（如“我现在能吃微辣了”），自动覆盖旧记忆
    • 记忆清理：用户可手动删除不需要的记忆，或设置记忆有效期（如“临时偏好，7 天后删除”）
    • 多维度分类：按“饮食/日程/工作/生活”等维度分类记忆，检索时可指定维度

6. Cron：助理的定时任务

Cron 是 OpenClaw 的“时间调度系统”，让 AI 能主动、守时地完成任务。

  • 支持任务：
    • 每天早上叫醒你。
    • 每周整理工作周报。
    • 每月提醒缴纳账单。
  • 技术实现：使用标准的 Cron 时间表达式，支持一次性或周期性任务。
内部实现细节

  1. 技术选型

    • 核心依赖：Python 的 APScheduler/Go 的 robfig/cron（成熟的 Cron 调度库）
    • 存储：SQLite/PostgreSQL（存储任务配置）
    • 通讯：gRPC（调用 Agent 执行定时任务）

  2. 核心功能实现

    • 任务创建：
      • Agent 调用 Cron 的 create_task 接口，传入任务参数： 
        {
  "user_id": "u123456",
  "task_name": "每天早上 8 点提醒我起床",
  "cron_expr": "0 8 * * *",  // 标准 Cron 表达式：分 时 日 月 周
  "command": "send_message",
  "params": {"content": "该起床啦！"},
  "type": "recurring"  // recurring（重复）/once（一次性）
}
      • Cron 验证 Cron 表达式合法性，存储任务到数据库，并加入调度队列
    • 任务执行：
      • 调度器按 Cron 表达式触发任务，调用 Agent 的 execute_task 接口
      • Agent 接收到定时任务后，按正常流程执行（如调用 Channels 发送提醒消息）
      • 执行结果记录到数据库（成功/失败、执行时间）
    • 任务管理：
      • 支持增删改查：用户可通过指令（如“取消每天 8 点的起床提醒”）修改任务
      • 支持暂停/恢复：临时暂停任务（如“这周不用提醒我起床”），恢复后继续执行

  3. 关键特性

    • 时区适配：支持用户自定义时区（如 UTC+8、UTC-5），避免跨时区任务执行错误
    • 任务重试：定时任务执行失败（如 Channels 暂时不可用），自动重试 3 次，间隔 1 分钟
    • 日志记录：记录所有定时任务的触发时间、执行结果，方便排查问题

7. Heartbeat：助理的主动巡逻

Heartbeat 是 OpenClaw 的“后台守护进程”，让 AI 从“被动响应”升级为“主动监控”。

  • 主动巡逻：定期检查邮箱、日历、任务状态等。
  • 触发机制：当发现重要变化（如收到新邮件、日历有会议）时，自动触发 Agent 进行处理。
  • 价值：即便你没开口，它也能确保你不错过重要事件。
内部实现细节

  1. 技术选型

    • 开发框架：Python（轻量守护进程）
    • 调度：APScheduler（定时触发巡逻任务）
    • 数据对接：各平台开放 API（如邮箱 IMAP、日历 CalDAV）

  2. 核心功能实现

    • 巡逻任务配置：
      • 每个巡逻项对应一个独立的 Checker 类，例如 EmailChecker、CalendarChecker
      • 用户可配置巡逻频率（如“每 10 分钟检查一次邮箱”）、触发条件（如“收到新邮件且发件人是老板”）
    • 主动巡逻流程：
      1. 调度器按频率触发 Checker（如每 10 分钟执行 EmailChecker.check()）
      2. Checker 调用对应平台 API 获取数据（如获取未读邮件列表）
      3. 对比上次巡逻的结果，判断是否有新事件（如新增未读邮件）
      4. 若满足触发条件，调用 Agent 的 trigger_task 接口，传入事件信息： 
        {
  "user_id": "u123456",
  "event_type": "new_email",
  "event_data": {
    "sender": "boss@company.com",
    "subject": "紧急会议通知",
    "time": 1710000000
  }
}
      5. Agent 接收事件后，自动执行预设逻辑（如通过 Channels 发送邮件提醒）
    • 触发条件引擎：
      • 支持简单的条件表达式，例如： 
        event_type == "new_email" AND sender == "boss@company.com" AND subject contains "紧急"
      • 解析表达式并判断是否触发任务

  3. 关键特性

    • 资源控制：巡逻频率可配置，避免频繁调用 API 导致账号受限
    • 静默期：触发一次任务后，设置 5 分钟静默期，避免同一事件重复触发
    • 异常处理：巡逻失败（如邮箱登录失败）时，记录错误并通知用户

我帮你把 OpenClaw 的命令行按功能模块重新整理、分类和补充说明，方便你直接作为速查手册使用：

OpenClaw相关指令

聊天命令（在对话中使用）

命令 功能说明
/new 开启新会话，清空上下文
/reset 重置对话，与 /new 功能一致
/status 查看当前会话状态：使用的模型、用量统计、费用信息
/reasoning 切换深度推理模式（开启/关闭）
/model <名称> 切换大模型，如 /model gpt-4、/model llama3
/help 查看帮助信息与命令列表
/skills 列出当前已安装的所有技能（Skills）
/agents 查看可用的 Agent 列表

CLI 命令（终端中使用）

1. Gateway 控制
命令 功能说明
openclaw gateway 前台方式启动 Gateway 服务
openclaw gateway status 查看 Gateway 当前运行状态
openclaw gateway start 后台方式启动 Gateway 服务
openclaw gateway stop 停止 Gateway 服务
openclaw gateway restart 重启 Gateway 服务
openclaw gateway install 将 Gateway 安装为系统服务（开机自启）
openclaw gateway uninstall 卸载 Gateway 系统服务
2. 常用工具
命令 功能说明
openclaw setup 初始化 OpenClaw 环境配置（首次安装后执行）
openclaw configure 交互式配置向导，修改系统参数
openclaw doctor 健康检查 + 自动修复常见问题（如依赖缺失、端口占用）
openclaw status 查看所有通道（Channels）的健康状态
openclaw logs 查看 Gateway 运行日志
openclaw dashboard 打开 Web 控制面板（可视化监控）
3. 消息发送
命令 功能说明
openclaw message send --target <号码> --message <内容> 向指定号码发送消息
openclaw message send --channel telegram --target @用户 --message <内容> 通过指定通道（如 Telegram）向用户发送消息
4. 通道管理
命令 功能说明
openclaw channels login 登录第三方通道（如 WhatsApp、飞书、Telegram）
openclaw channels 查看已配置的通道列表及状态
5. 其他实用命令
命令 功能说明
openclaw --dev gateway 开发模式启动 Gateway（热重载、详细日志）
openclaw gateway --force 强制杀掉占用端口的进程并启动 Gateway
openclaw skills 技能管理（安装/卸载/启用/禁用技能）
openclaw agents Agent 管理（切换/配置/查看 Agent 状态）
openclaw browser 浏览器管理（启动/关闭/配置自动化浏览器）
6. 常用启动参数
参数 功能说明
openclaw gateway --port 18789 指定 Gateway 监听端口（默认 18789）
openclaw gateway --force 强制启动，忽略端口占用等警告
openclaw gateway --verbose 启用详细日志输出，便于调试
openclaw --dev gateway 开发模式启动，支持热重载
# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

AI 龙虾 | 对学习工作的影响和未来前瞻

AI 龙虾（OpenClaw）是能自主操控设备、完成全流程任务的 AI 智能体，核心是 “动口即执行”，正从工具升级为数字生产力单元，深刻重塑学习与工作模式。

avatar 龙虾开发者社区

Kubernetes集群的搭建与DevOps实践（下）- 部署实践篇

(谨慎操作，相当于AI直接操作你的电脑)(可选)安装后PowerShell（终端管理员）开启文件权限openclaw config set tools.profile "coding" # 启用文件操作（read/write/edit）+ 执行命令?权限管理，配置应用权限飞书机器人 | OpenClaw 中文社区 - 开源免费 AI 助手 | WhatsApp/Telegram/微信自动化?飞书开

avatar 龙虾开发者社区

你的焦虑不是 AI 给的，是你的工作本来就不值得保留

从 OpenAI 到豆包，从 DeepSeek 到 OpenClaw，工具以月为单位迭代。你刷到每条新闻，心里都咯噔一下。但我想说句难听的：AI 的普及不是在制造焦虑，而是在暴露焦虑。那些关于"被替代"的恐惧，其实是对自己工作价值的诚实拷问。

avatar 龙虾开发者社区