← 返回导航页

OpenClaw 文档速读：接口导航与数据结构

OpenClaw 文档速读：接口导航与数据结构

面向“我想用 OpenClaw 把工具, 自动化, 多端接入跑起来”的快速笔记版说明。内容基于官方文档 https://docs.openclaw.ai/ ，并按接口与数据结构重新编排。

目录

1. OpenClaw 是什么

OpenClaw 把“聊天式智能体”落到工程层面，核心在于：

2. 文档导航

建议按“先能跑, 再精调”的顺序读：

进阶导航（按需求挑）：

提示：官方提供了全站索引文件 llms.txt，适合用脚本或检索工具直接拉列表。

3. 核心概念速记

4. 工具接口总览（Tool API）

来源: https://docs.openclaw.ai/tools

OpenClaw 的工具可以理解成一套“受控 RPC”，每个工具都有明确 action 和参数结构。下面按常用度整理。

4.1 工具策略与分组（tools.allow, tools.deny, tools.profile）

核心字段（位于 ~/.openclaw/openclaw.json）：

示例：只允许文件工具和 browser。

{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

4.2 exec 与 process（运行命令与后台会话）

你会经常用到的参数：

4.3 web_search 与 web_fetch（联网检索与抓取）

web_fetch 常用：

4.4 browser（可控浏览器）

适合 JS 重站点, 登录态页面, 或需要交互式点击填表的场景。

关键动作：

一个经验：优先用 snapshot(refs="aria") 拿到稳定引用，再做 act。

4.5 nodes 与 canvas（节点能力, 相机与屏幕）

4.6 message（跨渠道消息）

message 负责发送文本, 媒体, 以及对渠道做操作（编辑, 删除, react, poll）。

注意点：当 message 工具调用绑定在当前会话时，发送目标会受限，避免跨上下文泄露。

4.7 cron（网关定时器）

cron 是 Gateway 的调度器。

详细见第 5 节。

4.8 gateway（网关控制与配置变更）

提示：配置严格校验，未知字段可能导致 Gateway 起不来，所以改动要有计划。

4.9 sessions_*（会话工具）

来源: https://docs.openclaw.ai/concepts/session-tool

工具集合：

重要约定：主会话 key 始终是字面量 main。

4.10 pdf（PDF 分析）

pdf 工具用于读 PDF 并做抽取或分析，适合和 SummarizerX 类似的工作流结合。

5. 自动化：Cron jobs 深入

来源: https://docs.openclaw.ai/automation/cron-jobs

Cron 的价值是把“准时发生的事”交给 Gateway，智能体只负责生成和执行逻辑。

5.1 两种执行方式

  1. Main session job
  1. Isolated job

5.2 schedule 三种形态

5.3 delivery 交付方式

5.4 cron.add 例子（工具调用形态）

一次性提醒，走 main session：

{
  "name": "Reminder",
  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "Reminder text" },
  "deleteAfterRun": true
}

周期任务，走 isolated 并投递：

{
  "name": "Morning brief",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "Summarize overnight updates.",
    "lightContext": true
  },
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "channel:C1234567890",
    "bestEffort": true
  }
}

6. 配置：openclaw.json 的关键字段

来源: https://docs.openclaw.ai/gateway/configuration

6.1 配置文件与格式

6.2 常见配置任务

6.3 热加载

配置文件变化通常可热应用，部分 gateway 级别字段可能需要重启。文档里提供了 reload mode：hybrid, hot, restart, off。

7. 数据结构速查（JSON Shape Cheatsheet）

下面把文档里最实用的“结构体”整理成便于复制的形态。

7.1 Tool policy（工具策略）

{
  tools: {
    profile: "coding",
    allow: ["group:fs", "group:web"],
    deny: ["browser"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

7.2 sessions_list 返回行（Row shape）

{
  "key": "main",
  "kind": "main",
  "channel": "telegram",
  "displayName": "...",
  "updatedAt": 1710000000000,
  "sessionId": "...",
  "model": "...",
  "contextTokens": 0,
  "totalTokens": 0,
  "thinkingLevel": "low",
  "sendPolicy": "allow",
  "lastChannel": "telegram",
  "lastTo": "884672457",
  "deliveryContext": { "channel": "telegram", "to": "884672457", "accountId": "default" }
}

7.3 sessions_send 参数

{
  "sessionKey": "main",
  "message": "...",
  "timeoutSeconds": 30
}

7.4 cron job 核心结构

{
  "name": "...",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": { "kind": "agentTurn", "message": "...", "model": "opus", "thinking": "low" },
  "delivery": { "mode": "announce", "channel": "telegram", "to": "<chatId>" },
  "enabled": true
}

结语

如果你想把这篇笔记升级成“团队可用的 OpenClaw 接入手册”，我建议下一步按你实际要用的能力切两条线写：

  1. 作为个人助理，重点写 channels, cron, sessions, message。
  2. 作为工程平台，重点写 tools policy, sandbox, hooks, 以及可观测性与故障排查。