功能简介 直接从提供商的使用量端点拉取使用量/配额数据。 不提供估算费用；仅展示提供商报告的时间窗口数据。 展示位置 聊天中的 /status：包含会话 token 数和估算费用的表情符号丰富的状态卡片（仅限 API 密钥）。当可用时，会显示当前模型提供商的使用量。 聊天中的 /usage off|tokens|full：每次响应的使用量页脚（OAuth 仅显示 token 数）。 聊天中的 /usage cost：从 OpenClaw 会话日志汇总的本地费用摘要。 CLI：openclaw status --usage 打印完整的按提供商分类的详细信息。 CLI：openclaw channels list 在提供商配置旁打印相同的使用量快照（使用 --no-usage 跳过）。 macOS 菜单栏：上下文菜单下的"使用量"部分（仅在可用时显示）。 提供商及凭据 Anthropic (Claude)：认证配置中的 OAuth 令牌。 GitHub Copilot：认证配置中的 OAuth 令牌。 Gemini CLI：认证配置中的 OAuth 令牌。 Antigravity：认证配置中的 OAuth 令牌。 OpenAI Codex：认证配置中的 OAuth 令牌（存在时使用 accountId）。 MiniMax：API 密钥（编程计划密钥；MINIMAX_CODE_PLAN_KEY 或 MINIMAX_API_KEY）；使用 5 小时编程计划时间窗口。 z.ai：通过环境变量/配置/认证存储提供的 API 密钥。 如果没有匹配的 OAuth/API 凭据，使用量信息将被隐藏。

OpenClaw.app 使用 SSH 隧道连接到远程 Gateway 网关。本指南向你展示如何设置。 概述 ┌─────────────────────────────────────────────────────────────┐ │ Client Machine │ │ │ │ OpenClaw.app ──► ws://127.0.0.1:18789 (local port) │ │ │ │ │ ▼ │ │ SSH Tunnel ────────────────────────────────────────────────│ │ │ │ └─────────────────────┼──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Remote Machine │ │ │ │ Gateway WebSocket ──► ws://127.0.0.1:18789 ──► │ │ │ └─────────────────────────────────────────────────────────────┘ 快速设置 步骤 1：添加 SSH 配置 编辑 ~/.ssh/config 并添加： Host remote-gateway HostName <REMOTE_IP> # e.g., 172.27.187.184 User <REMOTE_USER> # e.g., jefferson LocalForward 18789 127.0.0.1:18789 IdentityFile ~/.ssh/id_rsa 将 <REMOTE_IP> 和 <REMOTE_USER> 替换为你的值。 ...

OpenClaw 是 Pi 智能体的 WhatsApp + Telegram + Discord + iMessage Gateway 网关。插件可添加 Mattermost。本指南是"个人助手"设置：一个专用的 WhatsApp 号码，表现得像你的常驻智能体。 ⚠️ 安全第一 你正在让智能体处于可以： 在你的机器上运行命令（取决于你的 Pi 工具设置） 在你的工作区读/写文件 通过 WhatsApp/Telegram/Discord/Mattermost（插件）发送消息 从保守开始： 始终设置 channels.whatsapp.allowFrom（永远不要在你的个人 Mac 上对全世界开放）。 为助手使用专用的 WhatsApp 号码。 心跳现在默认每 30 分钟一次。在你信任设置之前，通过设置 agents.defaults.heartbeat.every: "0m" 来禁用。 先决条件 Node 22+ OpenClaw 在 PATH 中可用（推荐：全局安装） 助手的第二个手机号码（SIM/eSIM/预付费） npm install -g openclaw@latest # 或：pnpm add -g openclaw@latest 从源代码（开发）： git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm ui:build # 首次运行时自动安装 UI 依赖 pnpm build pnpm link --global 双手机设置（推荐） 你需要这样： ...

简要概述 location.get 是一个节点命令（通过 node.invoke）。 默认关闭。 设置使用选择器：关闭 / 使用时 / 始终。 单独的开关：精确位置。 为什么用选择器（而不只是开关） 操作系统权限是多级的。我们可以在应用内暴露选择器，但操作系统仍然决定实际授权。 iOS/macOS：用户可以在系统提示/设置中选择使用时或始终。应用可以请求升级，但操作系统可能要求进入设置。 Android：后台位置是单独的权限；在 Android 10+ 上通常需要进入设置流程。 精确位置是单独的授权（iOS 14+ “精确”，Android “精细” vs “粗略”）。 UI 中的选择器驱动我们请求的模式；实际授权存在于操作系统设置中。 设置模型 每个节点设备： location.enabledMode：off | whileUsing | always location.preciseEnabled：bool UI 行为： 选择 whileUsing 请求前台权限。 选择 always 首先确保 whileUsing，然后请求后台（或在需要时将用户引导到设置）。 如果操作系统拒绝请求的级别，回退到已授予的最高级别并显示状态。 权限映射（node.permissions） 可选。macOS 节点通过权限映射报告 location；iOS/Android 可能省略它。 命令：location.get 通过 node.invoke 调用。 参数（建议）： { "timeoutMs": 10000, "maxAgeMs": 15000, "desiredAccuracy": "coarse|balanced|precise" } 响应负载： { "lat": 48.20849, "lon": 16.37208, "accuracyMeters": 12.5, "altitudeMeters": 182.0, "speedMps": 0.0, "headingDeg": 270.0, "timestamp": "2026-01-03T12:34:56.000Z", "isPrecise": true, "source": "gps|wifi|cell|unknown" } 错误（稳定代码）： ...

本文档解释 OpenClaw 如何端到端管理会话： 会话路由（入站消息如何映射到 sessionKey） 会话存储（sessions.json）及其跟踪的内容 记录持久化（*.jsonl）及其结构 记录清理（运行前的提供商特定修复） 上下文限制（上下文窗口 vs 跟踪的 token 数） 压缩（手动 + 自动压缩）以及在何处挂接压缩前工作 静默内务处理（例如不应产生用户可见输出的记忆写入） 如果你想先了解更高层次的概述，请从以下内容开始： /concepts/session /concepts/compaction /concepts/session-pruning /reference/transcript-hygiene 事实来源：Gateway 网关 OpenClaw 围绕一个拥有会话状态的单一 Gateway 网关进程设计。 UI（macOS 应用、web 控制 UI、TUI）应该向 Gateway 网关查询会话列表和 token 计数。 在远程模式下，会话文件在远程主机上；“检查你的本地 Mac 文件"不会反映 Gateway 网关正在使用的内容。 两个持久化层 OpenClaw 在两个层中持久化会话： 会话存储（sessions.json） 键/值映射：sessionKey -> SessionEntry 小型、可变、可安全编辑（或删除条目） 跟踪会话元数据（当前会话 ID、最后活动时间、开关、token 计数器等） 记录（<sessionId>.jsonl） 具有树形结构的仅追加记录（条目有 id + parentId） 存储实际对话 + 工具调用 + 压缩摘要 用于为后续回合重建模型上下文 磁盘上的位置 在 Gateway 网关主机上，每个智能体： 存储：~/.openclaw/agents/<agentId>/sessions/sessions.json 记录：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl Telegram 话题会话：.../<sessionId>-topic-<threadId>.jsonl OpenClaw 通过 src/config/sessions.ts 解析这些位置。 ...

OpenClaw 将每个智能体的一个直接聊天会话视为主会话。直接聊天折叠为 agent:<agentId>:<mainKey>（默认 main），而群组/频道聊天获得各自的键。session.mainKey 会被遵循。 使用 session.dmScope 控制私信如何分组： main（默认）：所有私信共享主会话以保持连续性。 per-peer：跨渠道按发送者 ID 隔离。 per-channel-peer：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 per-account-channel-peer：按账户 + 渠道 + 发送者隔离（推荐用于多账户收件箱）。 使用 session.identityLinks 将带提供商前缀的对等 ID 映射到规范身份，这样在使用 per-peer、per-channel-peer 或 per-account-channel-peer 时，同一个人可以跨渠道共享私信会话。 Gateway 网关是唯一数据源 所有会话状态都由 Gateway 网关拥有（“主” OpenClaw）。UI 客户端（macOS 应用、WebChat 等）必须向 Gateway 网关查询会话列表和令牌计数，而不是读取本地文件。 在远程模式下，你关心的会话存储位于远程 Gateway 网关主机上，而不是你的 Mac 上。 UI 中显示的令牌计数来自 Gateway 网关的存储字段（inputTokens、outputTokens、totalTokens、contextTokens）。客户端不会解析 JSONL 对话记录来"修正"总数。 状态存储位置 在 Gateway 网关主机上： 存储文件：~/.openclaw/agents/<agentId>/sessions/sessions.json（每个智能体）。 对话记录：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl（Telegram 话题会话使用 .../<SessionId>-topic-<threadId>.jsonl）。 存储是一个映射 sessionKey -> { sessionId, updatedAt, ... }。删除条目是安全的；它们会按需重新创建。 群组条目可能包含 displayName、channel、subject、room 和 space 以在 UI 中标记会话。 会话条目包含 origin 元数据（标签 + 路由提示），以便 UI 可以解释会话的来源。 OpenClaw 不读取旧版 Pi/Tau 会话文件夹。 会话修剪 默认情况下，OpenClaw 在 LLM 调用之前从内存上下文中修剪旧的工具结果。 这不会重写 JSONL 历史记录。参见 /concepts/session-pruning。 ...

目标：小型、不易误用的工具集，使智能体能够列出会话、获取历史记录并向另一个会话发送消息。 工具名称 sessions_list sessions_history sessions_send sessions_spawn 键模型 主直接聊天桶始终是字面键 "main"（解析为当前智能体的主键）。 群聊使用 agent:<agentId>:<channel>:group:<id> 或 agent:<agentId>:<channel>:channel:<id>（传递完整键）。 定时任务使用 cron:<job.id>。 Hooks 使用 hook:<uuid>，除非明确设置。 Node 会话使用 node-<nodeId>，除非明确设置。 global 和 unknown 是保留值，永远不会被列出。如果 session.scope = "global"，我们会将其别名为 main 用于所有工具，这样调用者永远不会看到 global。 sessions_list 将会话列为行数组。 参数： kinds?: string[] 过滤器："main" | "group" | "cron" | "hook" | "node" | "other" 中的任意一个 limit?: number 最大行数（默认：服务器默认值，限制如 200） activeMinutes?: number 仅在 N 分钟内更新的会话 messageLimit?: number 0 = 无消息（默认 0）；>0 = 包含最后 N 条消息 行为： messageLimit > 0 获取每个会话的 chat.history 并包含最后 N 条消息。 工具结果在列表输出中被过滤；使用 sessions_history 获取工具消息。 在沙箱隔离的智能体会话中运行时，会话工具默认为仅生成的可见性（见下文）。 行结构（JSON）： ...

会话剪枝在每次 LLM 调用之前从内存上下文中修剪旧的工具结果。它不会重写磁盘上的会话历史（*.jsonl）。 运行时机 当启用 mode: "cache-ttl" 且该会话的最后一次 Anthropic 调用早于 ttl 时。 仅影响该请求发送给模型的消息。 仅对 Anthropic API 调用（和 OpenRouter Anthropic 模型）生效。 为获得最佳效果，请将 ttl 与你的模型 cacheControlTtl 匹配。 剪枝后，TTL 窗口会重置，因此后续请求会保持缓存直到 ttl 再次过期。 智能默认值（Anthropic） OAuth 或 setup-token 配置文件：启用 cache-ttl 剪枝并将心跳设置为 1h。 API 密钥配置文件：启用 cache-ttl 剪枝，将心跳设置为 30m，并将 Anthropic 模型的 cacheControlTtl 默认为 1h。 如果你显式设置了这些值中的任何一个，OpenClaw 不会覆盖它们。 改进内容（成本 + 缓存行为） 为什么要剪枝： Anthropic 提示缓存仅在 TTL 内适用。如果会话空闲超过 TTL，下一个请求会重新缓存完整提示，除非你先修剪它。 什么变得更便宜： 剪枝减少了 TTL 过期后第一个请求的 cacheWrite 大小。 为什么 TTL 重置很重要： 一旦剪枝运行，缓存窗口会重置，因此后续请求可以重用新缓存的提示，而不是再次重新缓存完整历史。 它不做什么： 剪枝不会添加 token 或"双倍"成本；它只改变该 TTL 后第一个请求缓存的内容。 可以剪枝的内容 仅 toolResult 消息。 用户 + 助手消息永远不会被修改。 最后 keepLastAssistants 条助手消息受保护；该截止点之后的工具结果不会被剪枝。 如果没有足够的助手消息来确定截止点，则跳过剪枝。 包含图像块的工具结果会被跳过（永不修剪/清除）。 上下文窗口估算 剪枝使用估算的上下文窗口（字符 ≈ token × 4）。基础窗口按以下顺序解析： ...

Gateway 网关仪表板是默认在 / 提供的浏览器控制 UI （通过 gateway.controlUi.basePath 覆盖）。 快速打开（本地 Gateway 网关）： http://127.0.0.1:18789/（或 http://localhost:18789/） 关键参考： 控制 UI 了解使用方法和 UI 功能。 Tailscale 了解 Serve/Funnel 自动化。 Web 界面 了解绑定模式和安全注意事项。 认证通过 connect.params.auth（token 或密码）在 WebSocket 握手时强制执行。 参见 Gateway 网关配置 中的 gateway.auth。 安全注意事项：控制 UI 是一个管理界面（聊天、配置、执行审批）。 不要公开暴露它。UI 在首次加载后将 token 存储在 localStorage 中。 优先使用 localhost、Tailscale Serve 或 SSH 隧道。 快速路径（推荐） 新手引导后，CLI 现在会自动打开带有你的 token 的仪表板，并打印相同的带 token 链接。 随时重新打开：openclaw dashboard（复制链接，如果可能则打开浏览器，如果是无头环境则显示 SSH 提示）。 token 保持本地（仅查询参数）；UI 在首次加载后移除它并保存到 localStorage。 Token 基础（本地 vs 远程） Localhost：打开 http://127.0.0.1:18789/。如果你看到"unauthorized"，运行 openclaw dashboard 并使用带 token 的链接（?token=...）。 Token 来源：gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）；UI 在首次加载后存储它。 非 localhost：使用 Tailscale Serve（如果 gateway.auth.allowTailscale: true 则无需 token）、带 token 的 tailnet 绑定，或 SSH 隧道。参见 Web 界面。 如果你看到"unauthorized" / 1008 运行 openclaw dashboard 获取新的带 token 链接。 确保 Gateway 网关可达（本地：openclaw status；远程：SSH 隧道 ssh -N -L 18789:127.0.0.1:18789 user@host 然后打开 http://127.0.0.1:18789/?token=...）。 在仪表板设置中，粘贴你在 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）中配置的相同 token。

目标 在所有地方拒绝未知配置键（根级 + 嵌套）。 拒绝没有 schema 的插件配置；不加载该插件。 移除加载时的旧版自动迁移；迁移仅通过 doctor 运行。 启动时自动运行 doctor（dry-run）；如果无效，阻止非诊断命令。 非目标 加载时的向后兼容性（旧版键不会自动迁移）。 静默丢弃无法识别的键。 严格验证规则 配置必须在每个层级精确匹配 schema。 未知键是验证错误（根级或嵌套都不允许透传）。 plugins.entries.<id>.config 必须由插件的 schema 验证。 如果插件缺少 schema，拒绝插件加载并显示清晰的错误。 未知的 channels.<id> 键是错误，除非插件清单声明了该渠道 id。 所有插件都需要插件清单（openclaw.plugin.json）。 插件 schema 强制执行 每个插件为其配置提供严格的 JSON Schema（内联在清单中）。 插件加载流程： 解析插件清单 + schema（openclaw.plugin.json）。 根据 schema 验证配置。 如果缺少 schema 或配置无效：阻止插件加载，记录错误。 错误消息包括： 插件 id 原因（缺少 schema / 配置无效） 验证失败的路径 禁用的插件保留其配置，但 Doctor + 日志会显示警告。 Doctor 流程 每次加载配置时都会运行 Doctor（默认 dry-run）。 如果配置无效： 打印摘要 + 可操作的错误。 指示：openclaw doctor --fix。 openclaw doctor --fix： 应用迁移。 移除未知键。 写入更新后的配置。 命令门控（当配置无效时） 允许的命令（仅诊断）： ...