OpenClaw 技能库 | 最大的 OpenClaw 扩展库

OpenClaw treats ''one direct-chat session per agent'' as primary. Direct chats collapse to ''agent:<agentId>:<mainKey>'' (default ''main''), while group/channel chats get their own keys. ''session.mainKey'' is honored.

Use ''session.dmScope'' to control how ''direct messages'' are grouped:

- ''main'' (default): all DMs share the main session for continuity.

- ''per-peer''：发送者 ID 在分钟離（渠道間在分钟享）。

- ''per-channel-peer'': isolate by channel + sender (recommended for multi-user inboxes).

- ''per-account-channel-peer'': isolate by account + channel + sender (recommended for multi-account inboxes).

Use ''session.identityLinks'' to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using ''per-peer'', ''per-channel-peer'', or ''per-account-channel-peer''.

Tutorial.step

Gateway 是唯一的真実的源

所有会话状态都由网关拥有（"主" OpenClaw）。UI 客户端（macOS 应用、WebChat 等）必须查询网关以获取会话列表和令牌计数，而不是读取本地文件。

- In remote mode, the session store you care about lives on the remote gateway host, not your Mac.

- Token counts shown in UIs come from the gateway's store fields (''inputTokens'', ''outputTokens'', ''totalTokens'', ''contextTokens''). Clients do not parse JSONL transcripts to "fix up" totals.

Tutorial.step

状态的保存場所

- gateway 主机上：

- 存储文件（代理每个 1 次）：''~/.openclaw/agents/<agentId>/sessions/sessions.json''

- openclaw gateway call sessions.list --params {}' — fetch sessions from the running gateway (use --url/--token for remote gateway access).

- Send ''/status'' as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).

- Send ''/context list'' or ''/context detail'' to see what's in the system prompt and injected workspace files (and the biggest context contributors).

- Send ''/stop'' as a standalone message to abort the current run, clear queued followups for that session, and stop any sub-agent runs spawned from it (the reply includes the stopped count).

- Send ''/compact'' (optional instructions) as a standalone message to summarize older context and free up window space. See [/concepts/compaction](/concepts/compaction).

Tutorial.step

会话修剪

每个会话条目在 ''origin'' 中记录其来源（尽力而为）：

- ''label'': human label (resolved from conversation label + group subject/channel)

Tutorial.step

Pre-compaction memory flush

当会话接近自动压缩时，OpenClaw 可以运行一个''静默内存刷新''轮次，提醒模型将持久笔记写入磁盘。这仅在可写工作区时运行。参见 ''Memory'' 和 ''Compaction''。

Tutorial.step

Mapping transports → session keys

- Direct chats follow ''session.dmScope'' (default ''main'').

- ''main''：''agent:<agentId>:<mainKey>''（设备間/渠道間的連続性）。

- Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.

- ''per-peer''：''agent:<agentId>:dm:<peerId>''。

- ''per-channel-peer''：''agent:<agentId>:<channel>:dm:<peerId>''。

- ''per-account-channel-peer''：''agent:<agentId>:<channel>:<accountId>:dm:<peerId>''（''accountId'' 默认 ''default''）。

If ''session.identityLinks'' matches a provider-prefixed peer id (for example ''telegram:123''), the canonical key replaces ''<peerId>'' so the same person shares a session across channels.

- Group chats isolate state: ''agent:<agentId>:<channel>:group:<id>'' (rooms/channels use ''agent:<agentId>:<channel>:channel:<id>'').

- Telegram forum topics append '':topic:<threadId>'' to the group id for isolation.

- Legacy ''group:<id>'' keys are still recognized for migration.

- Inbound contexts may still use ''group:<id>''; the channel is inferred from ''Provider'' and normalized to the canonical ''agent:<agentId>:<channel>:group:<id>'' form.

- 那个他的源：

- Cron 任务：''cron:<job.id>''

Tutorial.step

Lifecycle

- Reset policy: sessions are reused until they expire, and expiry is evaluated on the next inbound message.

- Daily reset: defaults to 4:00 AM local time on the gateway host. A session is stale once its last update is earlier than the most recent daily reset time.

- Idle reset (optional): ''idleMinutes'' adds a sliding idle window. When both daily and idle resets are configured, ''whichever expires first'' forces a new session.

- Legacy idle-only: if you set ''session.idleMinutes'' without any ''session.reset''/''resetByType'' config, OpenClaw stays in idle-only mode for backward compatibility.

- Per-type overrides (optional): ''resetByType'' lets you override the policy for ''dm'', ''group'', and ''thread'' sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).

- Per-channel overrides (optional): ''resetByChannel'' overrides the reset policy for a channel (applies to all session types for that channel and takes precedence over ''reset''/''resetByType'').

- Reset triggers: exact ''/new'' or ''/reset'' (plus any extras in ''resetTriggers'') start a fresh session id and pass the remainder of the message through. ''/new <model>'' accepts a model alias, ''provider/model'', or provider name (fuzzy match) to set the new session model. If ''/new'' or ''/reset'' is sent alone, OpenClaw runs a short "hello" greeting turn to confirm the reset.

- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.

- Isolated cron jobs always mint a fresh ''sessionId'' per run (no idle reuse).

Tutorial.step

发送策略（选项）

阻止特定会话类型的传递，而无需列出单个ID：

Json5

{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } }
      ],
      default: "allow"
    }
  }
}

运行时覆盖（所有者仅）：

- ''/send on'' → 这个会话的配信允许

- ''/send off'' → 这个会话的配信块

- ''/send inherit'' → 清除覆盖并使用配置规则

将这些作为独立消息发送以便它们被注册。

Tutorial.step

设置示示例（名称更改付机）

Json5

// ~/.openclaw/openclaw.json
{
  session: {
    scope: "per-sender",
    dmScope: "main",
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"]
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      dm: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 }
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 }
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    mainKey: "main"
  }
}

Tutorial.step

提示

- Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.

- When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.

- openclaw gateway call sessions.list --params {}' — 运行中的 gateway 从会话获取执行（远程在是 --url/--token 使用）。

- Send ''/context list'' or ''/context detail'' to see what's in the system prompt and injected workspace files (and the biggest context contributors).

- Send ''/stop'' as a standalone message to abort the current run, clear queued followups for that session, and stop any sub-agent runs spawned from it (the reply includes the stopped count).

- Send ''/compact'' (optional instructions) as a standalone message to summarize older context and free up window space. See [/concepts/compaction](/concepts/compaction).

- JSONL transcripts can be opened directly to review full turns.

Tutorial.step

提示

每个会话条目在 ''origin'' 中记录其来源（尽力而为）：

- ''label'': human label (resolved from conversation label + group subject/channel)

Tutorial.step

Session origin metadata

每个会话条目是 ''origin'' 在那个源記録执行（尽力而为）：

- ''label'': human label (resolved from conversation label + group subject/channel)

- ''provider'': normalized channel id (including extensions)

- ''from''/''to'': raw routing ids from the inbound envelope

- ''accountId''：提供商账户 ID（多账户時）

- ''threadId'': thread/topic id when the channel supports it

会话管理

Gateway 是唯一的真実的源

状态的保存場所

会话修剪

Pre-compaction memory flush

Mapping transports → session keys

Lifecycle

发送策略（选项）

设置示示例（名称更改付机）

提示

提示

Session origin metadata