Language

Copyright © 2026 Eugene Hsuan

Powered by Hexo

Modified based on Magnetic theme

Mainly maintained using AI

OpenClaw 使用笔记

OpenClaw 使用笔记

简介

OpenClaw 是一个本地 AI 助手框架，可以集成多种模型和工具，支持会话管理、技能扩展、定时任务等功能。

我当前使用GLM的编程Pro套餐来使用它，并部署在一台7*24开机的Mac Mini上。

核心特性

  • 本地运行，数据隐私保护
  • 多模型支持（GLM、Claude 等）
  • 灵活的技能扩展机制
  • 定时任务和提醒功能
  • 跨平台消息集成

核心概念

会话类型

  • 主会话（Main Session）: 直接与用户对话的会话，可以访问完整上下文和记忆
  • 子会话（Sub-agent）: 隔离的工作会话，用于执行特定任务。

工作空间

默认工作目录：~/clawd

包含以下重要文件：

  • SOUL.md: 助手的性格和行为准则
  • USER.md: 用户信息和偏好
  • MEMORY.md: 长期记忆（仅在主会话加载）
  • memory/YYYY-MM-DD.md: 每日记忆日志
  • TOOLS.md: 环境特定的工具配置
  • HEARTBEAT.md: 定期检查任务列表

Skills 机制

什么是 Skills

Skills 是可重用的功能模块，提供特定的工具和能力。

当前可用 Skills

1. bluebubbles

  • 用途: 通过 BlueBubbles 发送和管理 iMessage
  • 使用: message 工具，设置 channel="bluebubbles"
  • 功能: 发送消息、回复、编辑、反应等

2. coding-agent

  • 用途: 委托编码任务给专门的 AI 代理
  • 适用场景:
    • 创建新功能或应用
    • 代码审查
    • 大型代码库重构
    • 需要文件探索的迭代编码
  • 不适场景: 简单的一行修改、读取代码（用 read 工具）、在 ~/clawd 工作
  • 注意: 需要支持 pty:true 的 bash 工具

3. healthcheck

  • 用途: OpenClaw 部署的安全加固和风险容忍度配置
  • 适用场景:
    • 安全审计
    • 防火墙/SSH/更新加固
    • 风险评估
    • OpenClaw 定期安全检查
    • 版本状态检查

4. skill-creator

  • 用途: 创建或更新 AgentSkills
  • 适用场景:
    • 设计技能
    • 构建技能结构
    • 打包带脚本、引用和资源的技能

5. weather

  • 用途: 通过 wttr.in 或 Open-Meteo 获取当前天气和预报
  • 适用场景: 用户询问任何地点的天气、温度或预报
  • 不适场景: 历史天气数据、恶劣天气警报、详细气象分析
  • 优势: 无需 API 密钥

使用 Skills

当一个技能明显适用时，工具会自动加载其 SKILL.md 文件并遵循其说明。

会话管理

子会话

用于执行隔离的任务，可以：

  • 一次性运行（mode=”run”）: 执行单个任务后自动清理
  • 持久会话（mode=”session”）: 保持会话活跃，可以多次交互

使用场景:

  • 需要独立上下文的任务
  • 后台长时间运行的任务
  • 多个独立任务并发执行

会话通信

  • sessions_send: 向其他会话发送消息
  • subagents: 管理子代理（列表、终止、引导）

消息处理

消息路由

  • 当前会话回复: 自动路由到源渠道（Signal、Telegram 等）
  • 跨会话: 使用 sessions_send(sessionKey, message)
  • 子代理协调: 使用 subagents 工具

消息工具

message 工具支持的操作：

  • send: 发送消息
  • react: 添加表情反应
  • edit: 编辑消息
  • unsend: 撤回消息
  • reply: 回复消息
  • sendWithEffect: 发送带效果的消息
  • sendAttachment: 发送附件

平台格式化

  • Discord/WhatsApp: 不使用 Markdown 表格，用项目符号代替
  • Discord 链接: 使用 <> 抑制嵌入：<https://example.com>
  • WhatsApp: 不使用标题，用粗体或大写强调

工具使用

文件操作

  • read: 读取文件内容
  • write: 创建或覆盖文件
  • edit: 精确编辑文件

命令执行

  • exec: 运行 Shell 命令（支持 pty 用于需要 TTY 的 CLI）
  • process: 管理后台执行会话

网络操作

  • web_search: 使用 Brave Search API 搜索网页
  • web_fetch: 获取并提取 URL 的可读内容

浏览器控制

  • browser: 通过 OpenClaw 浏览器控制服务器控制浏览器
    • 支持配置文件：chrome（Chrome 扩展中继）或 openclaw（隔离浏览器）
    • 用于 UI 自动化、截图、导航等

常用命令

Gateway 管理

1
2
3
4
5
openclaw gateway status    # 查看状态
openclaw gateway start     # 启动
openclaw gateway stop      # 停止
openclaw gateway restart   # 重启
openclaw help              # 查看帮助

状态检查

1
openclaw status            # 系统状态

定时任务和提醒

Cron Jobs

使用场景:

  • 精确时间安排（”每周一上午 9 点”）
  • 需要与主会话历史隔离的任务
  • 需要不同模型或思考级别的任务
  • 一次性提醒（”20 分钟后提醒我”）
  • 输出应直接投递到渠道的任务

Heartbeats

使用场景:

  • 多个检查可以批量一起（收件箱 + 日历 + 通知）
  • 需要最近消息的对话上下文
  • 时间可以稍微漂移（每 ~30 分钟一次可以，不需要精确）
  • 希望通过组合定期检查来减少 API 调用

定期检查内容（每天 2-4 次）:

  • 邮件 - 未读紧急消息？
  • 日历 - 未来 24-48 小时的事件？
  • 提及 - Twitter/社交通知？
  • 天气 - 如果用户可能会出门

追踪检查状态（memory/heartbeat-state.json）:

1
2
3
4
5
6
7
{
  "lastChecks": {
    "email": 1703275200,
    "calendar": 1703260800,
    "weather": null
  }
}

配置文件说明

AGENTS.md

工作空间的根目录，定义会话启动的引导规则。

SOUL.md

助手的灵魂，定义性格、边界、语气。

USER.md

用户信息，包括称呼、时区、偏好等。

MEMORY.md

长期记忆，仅在主会话加载。包含决策、上下文、需要记住的事情。

TOOLS.md

环境特定的工具笔记（相机名称、SSH 主机、TTS 偏好等）。

IDENTITY.md

助手身份信息（名称、生物、表情符号等）。

实用技巧和最佳实践

记忆管理

每日记忆（memory/YYYY-MM-DD.md）:

  • 原始日志，记录当天发生的事情
  • 创建 memory/ 目录（如果不存在）

长期记忆（MEMORY.md）:

  • 定期（每隔几天）通过心跳回顾每日文件
  • 识别值得长期保留的重要事件、教训或见解
  • 用提炼的学习内容更新 MEMORY.md
  • 删除 MEMORY.md 中不再相关的过时信息

组合检查

  • 将类似的定期检查合并到 HEARTBEAT.md 中，而不是创建多个 cron 任务
  • 使用 cron 进行精确调度和独立任务

文件操作

  • 优先顺序: 垃圾箱 > 删除（恢复胜过永久丢失）
  • 不确定时，先问

外部操作

以下操作需要先询问：

  • 发送邮件、推文、公开帖子
  • 任何离开本机的事情
  • 任何不确定的操作

群组聊天

  • 不要将用户的资料共享给他人
  • 在群组中，你是参与者，不是他们的声音或代理
  • 说话前先思考

路径安全问题

  • 我在部署的时候一直担心我的数据安全被泄露，尝试设置指定路径，但实际上小龙虾的fs设置只支持 fs: { workspaceOnly: false }，即只有工作区安全策略。

故障排除

问题：工具不可用

检查 openclaw status 确认系统状态。

问题：找不到某个功能

  • 检查可用的 Skills
  • 阅读 Skills 文档
  • 检查工具权限

问题：会话不响应

  • 检查 Gateway 状态
  • 尝试重启：openclaw gateway restart

问题：记忆丢失

  • 确认 MEMORY.md 和 memory/ 目录存在
  • 检查文件权限
  • 回顾最近的 memory/YYYY-MM-DD.md 文件

资源链接

AI OpenClaw Assistant