跳转至

个人助理设置

OpenClaw 是一个自托管网关,可将 Discord、Google Chat、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等连接到 AI 代理。本指南介绍“个人助理”设置:一个专用的 WhatsApp 号码,像你的常驻 AI 助理一样工作。如果想为多人设置共享网关?请参阅团队设置。

良好的默认设置优先

已连接的代理是功能强大的代理:根据你的工具策略,它可以运行命令、处理其工作区中的文件,并代表你向他人发送消息。默认设置会将这种能力限制在你自己范围内;有几个设置值得提前确认:

  • 始终设置 channels.whatsapp.allowFrom(绝不在你的个人 Mac 上运行对全世界开放的服务)。
  • 为助理使用专用的 WhatsApp 号码。
  • 心跳默认每 30 分钟一次。在评估该设置时,将 agents.defaults.heartbeat.every: "0m" 设置为可禁用定期轮询。针对性的事件驱动后续任务仍然可以运行,因此在信任该设置之前,请对工具策略和沙箱保持保守。

前提条件

  • 已安装并完成 OpenClaw 的入门引导——如果你还没有完成,请参阅入门指南。
  • 已安装 WhatsApp 插件,或在入门引导期间选择了 WhatsApp。WhatsApp 是一个按需安装的官方插件。请参阅 WhatsApp。
  • 为助理准备第二个电话号码(SIM/eSIM/预付费)

你希望的是这样的:

flowchart TB
    A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>AI agent"]

如果你将个人 WhatsApp 关联到 OpenClaw,那么发给你的每条消息都会变成“代理输入”。这通常不是你想要的。

5 分钟快速开始

  1. 配对 WhatsApp Web(会显示二维码;用助理手机扫描):
openclaw channels login
  1. 启动网关(保持其运行):
openclaw gateway --port 18789
  1. 在 ~/.openclaw/openclaw.json 中放入一个最小配置:
{
  gateway: { mode: "local" },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

现在,从你的白名单手机向助理号码发送消息。

入门引导完成后,OpenClaw 会自动打开仪表盘并打印一个干净(非 token 化)的链接。如果仪表盘提示进行身份验证,请将配置的共享密钥粘贴到 Control UI 设置中。入门引导默认使用一个 token(gateway.auth.token),但如果你已将 gateway.auth.mode 切换为 password,密码身份验证同样可用。之后若要重新打开:openclaw dashboard。

为代理提供工作区(AGENTS)

OpenClaw 从其工作区目录中读取操作说明和“记忆”。

默认情况下,OpenClaw 使用 ~/.openclaw/workspace 作为代理工作区,并在入门引导或首次运行代理时自动创建该目录(以及初始的 AGENTS.md、SOUL.md、IDENTITY.md、USER.md)。将特定于环境的工具说明放在 AGENTS.md 的 ## Tools 部分。BOOTSTRAP.md 仅为全新工作区创建,删除后不应再次出现。MEMORY.md 是可选的,从不自动创建;当它存在时,会在正常会话中加载。子代理会话只注入 AGENTS.md。

Tip

把这个文件夹当作 OpenClaw 的记忆,并将其设为 git 仓库(最好是私有仓库),这样你的 AGENTS.md 和记忆文件就能得到备份。如果安装了 git,全新工作区会自动使用 git init 初始化。

要在不运行完整入门引导向导的情况下创建工作区和配置文件夹:

openclaw setup --baseline

(单独的 openclaw setup 是 openclaw onboard 的别名,会运行完整的交互式向导。)

完整的工作区布局 + 备份指南:代理工作区 记忆工作流:记忆

可选:使用 agents.defaults.workspace 选择不同的工作区(支持 ~)。

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

如果你已经通过仓库提供自己的工作区文件,则可以完全禁用引导文件创建:

{
  agents: {
    defaults: {
      skipBootstrap: true,
    },
  },
}

将其变成“助手”的配置

OpenClaw 默认就是一个不错的助理设置,但你通常需要调整:

  • SOUL.md 中的个性/指令
  • 思考默认值(如果需要)
  • 心跳(一旦你信任它)

示例:

{
  logging: { level: "info" },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      thinkingDefault: "high",
      timeoutSeconds: 1800,
      // Start with 0; enable later.
      heartbeat: { every: "0m" },
    },
    entries: {
      main: {
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080,
    },
  },
}

会话与记忆

  • 会话行、对话记录行和元数据(token 使用量、最后路由等):~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
  • 旧版/归档对话记录产物:~/.openclaw/agents/<agentId>/sessions/
  • 旧版行迁移来源:~/.openclaw/agents/<agentId>/sessions/sessions.json
  • /new 或 /reset 会为该聊天开启一个全新会话(可通过 session.resetTriggers 配置)。如果单独发送,OpenClaw 会确认重置,而不会调用模型。
  • /compact [instructions] 会压缩会话上下文,并报告剩余上下文预算。

心跳(主动模式)

默认情况下,OpenClaw 每 30 分钟运行一次心跳——当配置了 Anthropic OAuth/token 身份验证(包括 Claude CLI 复用)时,则为每小时一次。有关完整默认设置,请参阅心跳。prompt 为: Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply NO_REPLY. 将 agents.defaults.heartbeat.every: "0m" 设置为可禁用定期节奏。针对性的事件驱动唤醒(例如后台执行完成后的后续任务)仍然可用,并且不会创建定期计划。心跳检查清单位于 monitor 的 cron scratch 中(请参阅心跳);openclaw doctor --fix 会将旧版工作区的 HEARTBEAT.md 迁移到其中。

  • 如果监控草稿存在但实际为空(仅包含空行、Markdown/HTML 注释、类似 # Heading 的 Markdown 标题、围栏标记或空检查清单存根),OpenClaw 会跳过本次心跳运行以节省 API 调用。
  • 如果不存在草稿,心跳仍会运行,并由模型决定要做什么。
  • 如果代理回复 NO_REPLY,OpenClaw 会抑制该心跳的出站投递。旧版 HEARTBEAT_OK 回复仍受支持,并带有固定的 300 字符确认预算。
  • 默认情况下,允许向 DM 风格的 user:<id> 目标进行心跳投递。设置 agents.defaults.heartbeat.directPolicy: "block" 可抑制直接目标投递,同时保持心跳运行处于活动状态。
  • 心跳会运行完整的代理轮次 - 更短的间隔会消耗更多 Token。
{
  agents: {
    defaults: {
      heartbeat: { every: "30m" },
    },
  },
}

媒体输入与输出

传入附件(图像/音频/文档)可以通过模板呈现给你的命令:

  • {{AttachmentPath}}(本地临时文件路径)
  • {{AttachmentUrl}}(原始 URL 或提供商引用)
  • {{AttachmentContentType}}(MIME 内容类型)
  • {{AttachmentDir}}(包含本地路径的目录)
  • {{AttachmentIndex}}(从零开始的源事实索引)
  • {{Transcript}}(如果启用了音频转录)

旧的 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 名称仍可作为已弃用的兼容性别名使用。

代理发出的出站附件使用消息工具或回复负载中的结构化媒体字段,例如 media、mediaUrl、mediaUrls、path 或 filePath。消息工具参数示例:

{
  "message": "Here's the screenshot.",
  "mediaUrl": "https://example.com/screenshot.png"
}

OpenClaw 会随文本一起发送结构化媒体。旧版最终助手回复可能仍会为了兼容性进行规范化,但工具输出、浏览器输出、流式块和消息操作不会将文本解析为附件命令。

如果必须使用旧版最终回复中的 MEDIA: 行,请将其保留为独立的纯 文本。Markdown 包装器、代码围栏以及内联文本,例如 **MEDIA:/path.png**、`MEDIA:/path.png` 或 Here is the image: MEDIA:/path.png,仍会保持为文本,并且不会附加媒体。参见 富输出协议。

本地路径行为遵循与代理相同的文件读取信任模型:

  • 如果 tools.fs.workspaceOnly 为 true,出站本地媒体路径仍限制在 OpenClaw 临时根目录、媒体缓存、代理工作区路径以及活动会话沙箱中生成的文件。同级沙箱中的文件仍不可访问。
  • 如果 tools.fs.workspaceOnly 为 false,出站本地媒体可以使用代理已获准读取的主机本地文件。
  • 本地路径可以是绝对路径、工作区相对路径,或使用 ~/ 的主目录相对路径。
  • 主机本地发送仍只允许媒体和支持的文档类型(图像、音频、视频、PDF、Office 文档,包括启用宏的 Excel .xlsm,以及经过验证的文本文档,例如 Markdown/MD、TXT、JSON、YAML 和 YML)。这是现有主机读取信任边界的扩展,而不是秘密扫描器:如果代理可以读取主机本地的 secret.txt 或 config.json,并且扩展名和内容验证匹配,它就可以附加该文件。文件类型验证并不能证明所附加工作簿中的宏可以安全运行。

请将敏感文件放在代理可读文件系统之外,或保持 tools.fs.workspaceOnly: true 以获得更严格的本地路径发送。

当消息工具无法为当前会话暂存附件时, 其错误会标识该文件以及报告的原因,例如文件缺失或 不支持的本地格式。位于工作区内并不意味着所有 文件类型都符合主机本地附件读取条件。

运维检查清单

openclaw status          # local status (creds, sessions, queued events)
openclaw status --all    # full diagnosis (read-only, pasteable)
openclaw status --deep   # check channels (WhatsApp Web + Telegram + Discord + Slack + Signal)
openclaw health --json   # gateway health snapshot over the WS connection

日志位于 /tmp/openclaw/ 下:默认 配置文件使用 openclaw-YYYY-MM-DD.log,命名配置文件使用 openclaw-<profile>-YYYY-MM-DD.log。

后续步骤

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw