[OpenClaw 文档]参考--技术参考

本文档汇总了 OpenClaw 官方文档站 参考 > 技术参考 子模块下的全部 5 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 新手引导参考

原文：https://docs.openclaw.ai/zh-CN/reference/wizard

这是 openclaw onboard 的完整参考。
如需高层概览，请参阅 新手引导（CLI）。

流程详情（本地模式）

- 如果 ~/.openclaw/openclaw.json 存在，请选择 保留当前值、查看并更新 或 设置前重置。
- 重新运行新手引导不会清除任何内容，除非你明确选择 重置
（或传入 --reset）。
- CLI --reset 默认使用 config+creds+sessions；使用 --reset-scope full
还会移除工作区。
- 如果配置无效或包含旧版键名，向导会停止并要求
你先运行 openclaw doctor 再继续。
- 重置使用 trash（绝不使用 rm），并提供以下范围：
- 仅配置
- 配置 + 凭证 + 会话
- 完全重置（也会移除工作区）

- Anthropic API key：如果存在则使用 ANTHROPIC_API_KEY，否则提示输入密钥，然后保存供守护进程使用。
- Anthropic API key：新手引导/配置中的首选 Anthropic assistant 选项。
- Anthropic setup-token：仍可在新手引导/配置中使用，不过 OpenClaw 现在会优先复用可用的 Claude CLI。
- OpenAI Code（Codex）订阅（OAuth）：浏览器流程；粘贴 code#state。
- 当模型未设置或已经属于 OpenAI 系列时，通过 Codex runtime 将 agents.defaults.model 设置为 openai/gpt-5.5。
- OpenAI Code（Codex）订阅（设备配对）：浏览器配对流程，使用短期设备代码。
- 当模型未设置或已经属于 OpenAI 系列时，通过 Codex runtime 将 agents.defaults.model 设置为 openai/gpt-5.5。
- OpenAI API key：如果存在则使用 OPENAI_API_KEY，否则提示输入密钥，然后存储到凭证档案中。
- 当模型未设置、为 openai/* 或为 openai-codex/* 时，将 agents.defaults.model 设置为 openai/gpt-5.5。
- xAI（Grok）API key：提示输入 XAI_API_KEY，并将 xAI 配置为模型提供商。
- OpenCode：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，可在 https://opencode.ai/auth 获取），并允许你选择 Zen 或 Go 目录。
- Ollama：首先提供 云端 + 本地、仅云端 或 仅本地。Cloud only 会提示输入 OLLAMA_API_KEY 并使用 https://ollama.com；主机支持的模式会提示输入 Ollama 基础 URL，发现可用模型，并在需要时自动拉取所选的本地模型；Cloud + Local 还会检查该 Ollama 主机是否已登录以获得云端访问权限。
- 更多详情：Ollama
- API key：为你存储该密钥。
- Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
- 更多详情：Vercel AI Gateway
- Cloudflare AI Gateway：提示输入 Account ID、Gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。
- 更多详情：Cloudflare AI Gateway
- MiniMax：配置会自动写入；托管默认值为 MiniMax-M2.7。
API key 设置使用 minimax/...，OAuth 设置使用
minimax-portal/...。
- 更多详情：MiniMax
- StepFun：会为中国或全球端点上的 StepFun 标准版或 Step Plan 自动写入配置。
- 标准版目前包含 step-3.5-flash，Step Plan 还包含 step-3.5-flash-2603。
- 更多详情：StepFun
- Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
- 更多详情：Synthetic
- Moonshot（Kimi K2）：配置会自动写入。
- Kimi Coding：配置会自动写入。
- 更多详情：Moonshot AI（Kimi + Kimi Coding）
- 跳过：暂不配置凭证。
- 从检测到的选项中选择默认模型（或手动输入 provider/model）。为获得最佳质量并降低提示注入风险，请选择你的提供商栈中可用的最强最新一代模型。
- 新手引导会运行模型检查，并在配置的模型未知或缺少凭证时发出警告。
- API key 存储模式默认使用明文凭证档案值。使用 --secret-input-mode ref 可改为存储由环境变量支持的引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
- 凭证档案位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API keys + OAuth）。~/.openclaw/credentials/oauth.json 仅为旧版导入源。
- 更多详情：/concepts/oauth

无头/服务器提示：在带浏览器的机器上完成 OAuth，然后复制
该 agent 的 auth-profiles.json（例如
~/.openclaw/agents/<agentId>/agent/auth-profiles.json，或匹配的
$OPENCLAW_STATE_DIR/... 路径）到 Gateway 网关主机。credentials/oauth.json
仅是旧版导入源。

- 默认 ~/.openclaw/workspace（可配置）。
- 播种 agent 启动仪式所需的工作区文件。
- 完整工作区布局 + 备份指南：Agent 工作区

- 端口、绑定、凭证模式、Tailscale 暴露。
- 凭证建议：即使是 loopback，也保留 Token，这样本地 WS 客户端必须通过身份验证。
- 在 token 模式下，交互式设置提供：
- 生成/存储明文 token（默认）
- 使用 SecretRef（选择启用）
- Quickstart 会复用跨 env、file 和 exec 提供商的现有 gateway.auth.token SecretRefs，用于新手引导探测/仪表板启动。
- 如果该 SecretRef 已配置但无法解析，新手引导会提前失败并显示明确的修复消息，而不是静默降级运行时凭证。
- 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。
- 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
- 要求新手引导进程环境中存在非空环境变量。
- 不能与 --gateway-token 组合使用。
- 仅当你完全信任每个本地进程时才禁用凭证。
- 非 loopback 绑定仍需要凭证。

- WhatsApp：可选 QR 登录。
- Telegram：bot token。
- Discord：bot token。
- Google Chat：服务账号 JSON + webhook audience。
- Mattermost（插件）：bot token + base URL。
- Signal：可选 signal-cli 安装 + 账号配置。
- iMessage：imsg CLI 路径 + Messages DB 访问权限；当 Gateway 网关运行在非 Mac 上时，请使用 SSH 包装器。
- 私信安全：默认是配对。第一条私信会发送一个代码；通过 openclaw pairing approve <channel> <code> 批准，或使用 allowlists。

- 选择受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。
- API 支持的提供商可以使用环境变量或现有配置进行快速设置；无需密钥的提供商则使用其提供商特定的前置条件。
- 使用 --skip-search 跳过。
- 稍后配置：openclaw configure --section web。

- macOS：LaunchAgent
- 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。
- Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
- 新手引导会尝试通过 loginctl enable-linger <user> 启用 lingering，以便 Gateway 网关在注销后仍保持运行。
- 可能提示输入 sudo（写入 /var/lib/systemd/linger）；它会先尝试不使用 sudo。
- 运行时选择： Node（推荐；WhatsApp/Telegram 必需）。Bun 不推荐。
- 如果 token 凭证需要 token，且 gateway.auth.token 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文 token 值持久化到 supervisor 服务环境元数据中。
- 如果 token 凭证需要 token，且配置的 token SecretRef 未解析，守护进程安装会被阻止，并给出可操作的指导。
- 如果同时配置了 gateway.auth.token 和 gateway.auth.password，且 gateway.auth.mode 未设置，守护进程安装会被阻止，直到显式设置模式。

- 启动 Gateway 网关（如需要）并运行 openclaw health。
- 提示：openclaw status --deep 会将实时 Gateway 网关健康探测添加到状态输出中，包括受支持时的渠道探测（需要可访问的 Gateway 网关）。

- 读取可用 Skills 并检查要求。
- 允许你选择节点管理器：npm / pnpm（不推荐 bun）。
- 安装可选依赖（部分在 macOS 上使用 Homebrew）。

- 摘要 + 后续步骤，包括 你想如何孵化你的 agent？ 提示，可选择 Terminal、Browser 或稍后。

如果未检测到 GUI，新手引导会打印 Control UI 的 SSH 端口转发说明，而不是打开浏览器。
如果缺少 Control UI 资产，新手引导会尝试构建它们；回退方案是 pnpm ui:build（自动安装 UI 依赖）。

非交互式模式

使用 --non-interactive 自动化或编写新手引导脚本：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

添加 --json 可获取机器可读摘要。

非交互式模式下的 Gateway 网关 token SecretRef：

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

--gateway-token 和 --gateway-token-ref-env 互斥。

--json 并不意味着非交互式模式。脚本请使用 --non-interactive（以及 --workspace）。

提供商特定命令示例位于 CLI 自动化。
使用此参考页了解标志语义和步骤顺序。

添加 agent（非交互式）

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.5 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway 网关向导 RPC

Gateway 网关通过 RPC（wizard.start、wizard.next、wizard.cancel、wizard.status）暴露新手引导流程。
客户端（macOS app、Control UI）可以渲染步骤，而无需重新实现新手引导逻辑。

Signal 设置（signal-cli）

新手引导可以从 GitHub releases 安装 signal-cli：

• 下载适当的 release 资产。
• 将其存储在 ~/.openclaw/tools/signal-cli/<version>/ 下。
• 将 channels.signal.cliPath 写入你的配置。

注意：

• JVM 构建需要 Java 21。
• 可用时会使用原生构建。
• Windows 使用 WSL2；signal-cli 安装遵循 WSL 内部的 Linux 流程。

向导写入的内容

~/.openclaw/openclaw.json 中的典型字段：

• agents.defaults.workspace
• agents.defaults.model / models.providers（如果选择了 Minimax）
• tools.profile（未设置时，本地新手引导默认使用 "coding"；现有显式值会保留）
• gateway.*（mode, bind, auth, tailscale）
• session.dmScope（行为详情：CLI 设置参考）
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• 当你在提示中选择加入时的渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（可行时名称会解析为 ID）。
• skills.install.nodeManager
• setup --node-manager 接受 npm、pnpm 或 bun。
• 手动配置仍可通过直接设置 skills.install.nodeManager 来使用 yarn。
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add 会写入 agents.list[] 和可选的 bindings。

WhatsApp 凭证位于 ~/.openclaw/credentials/whatsapp/<accountId>/ 下。
会话存储在 ~/.openclaw/agents/<agentId>/sessions/ 下。

某些渠道以插件形式交付。当你在设置期间选择其中一个时，新手引导
会在配置它之前提示安装它（npm 或本地路径）。

相关文档

• 新手引导概览：新手引导（CLI）
• macOS 应用新手引导：新手引导
• 配置参考：Gateway 网关配置
• 提供商：WhatsApp, Telegram, Discord, Google Chat, Signal, iMessage
• Skills：Skills, Skills 配置

📄 Token 用量和费用

原文：https://docs.openclaw.ai/zh-CN/reference/token-use

OpenClaw 跟踪的是词元，不是字符。词元因模型而异，但大多数 OpenAI 风格模型在英文文本中平均约为每个词元 4 个字符。

系统提示词是如何构建的

OpenClaw 会在每次运行时组装自己的系统提示词。它包括：

• 工具列表 + 简短描述
• Skills 列表（仅元数据；指令会按需通过 read 加载）。
  紧凑 Skills 块受 skills.limits.maxSkillsPromptChars 限制，
  可在 agents.list[].skillsLimits.maxSkillsPromptChars 处按智能体覆盖。
• 自更新指令
• 工作区 + 引导文件（新建时包括 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md，存在时还包括 MEMORY.md）。小写的根目录 memory.md 不会被注入；当它与 MEMORY.md 配对时，它是 openclaw doctor --fix 的旧版修复输入。大文件会按 agents.defaults.bootstrapMaxChars 截断（默认值：12000），总引导注入量受 agents.defaults.bootstrapTotalMaxChars 限制（默认值：60000）。memory/*.md 每日文件不是常规引导提示词的一部分；在普通轮次中它们仍通过记忆工具按需使用，但重置/启动模型运行可以为第一轮预置一个一次性的启动上下文块，其中包含最近的每日记忆。裸聊天 /new 和 /reset 命令会被确认，但不会调用模型。启动前导由 agents.defaults.startupContext 控制。
• 时间（UTC + 用户时区）
• 回复标签 + Heartbeat 行为
• 运行时元数据（主机/OS/模型/thinking）

完整拆解见系统提示词。

上下文窗口中会计入什么

模型收到的所有内容都会计入上下文限制：

• 系统提示词（上面列出的所有部分）
• 对话历史（用户 + 助手消息）
• 工具调用和工具结果
• 附件/转录内容（图像、音频、文件）
• 压缩摘要和剪枝产物
• 提供商包装器或安全标头（不可见，但仍会计入）

一些运行时较重的表面有自己的显式上限：

• agents.defaults.contextLimits.memoryGetMaxChars
• agents.defaults.contextLimits.memoryGetDefaultLines
• agents.defaults.contextLimits.toolResultMaxChars
• agents.defaults.contextLimits.postCompactionMaxChars

按智能体覆盖项位于 agents.list[].contextLimits 下。这些旋钮用于有界运行时摘录和运行时拥有的注入块。它们独立于引导限制、启动上下文限制和 Skills 提示词限制。

对于图像，OpenClaw 会在调用提供商前下采样转录/工具图像载荷。
使用 agents.defaults.imageMaxDimensionPx（默认值：1200）进行调优：

• 较低的值通常会减少视觉词元用量和载荷大小。
• 较高的值会为 OCR/UI 密集型截图保留更多视觉细节。

如需实用拆解（按注入文件、工具、Skills 和系统提示词大小），使用 /context list 或 /context detail。见上下文。

如何查看当前词元用量

在聊天中使用这些命令：

• /status → 带有丰富 emoji 的状态卡片，显示会话模型、上下文用量、上次响应的输入/输出词元，以及估算成本（仅 API key）。
• /usage off|tokens|full → 为每条回复附加逐响应用量页脚。
• 按会话持久化（存储为 responseUsage）。
• OAuth 凭证隐藏成本（仅显示词元）。
• /usage cost → 从 OpenClaw 会话日志显示本地成本摘要。

其他表面：

• TUI/Web TUI：支持 /status + /usage。
• CLI：openclaw status --usage 和 openclaw channels list 会显示
  规范化的提供商配额窗口（X% left，不是逐响应成本）。
  当前用量窗口提供商：Anthropic、GitHub Copilot、Gemini CLI、
  OpenAI Codex、MiniMax、Xiaomi 和 z.ai。

用量表面会在显示前规范化常见的提供商原生字段别名。
对于 OpenAI 系列 Responses 流量，这包括 input_tokens /
output_tokens 和 prompt_tokens / completion_tokens，因此传输特定的字段名不会改变 /status、/usage 或会话摘要。
Gemini CLI JSON 用量也会被规范化：回复文本来自 response，并且
stats.cached 映射到 cacheRead；当 CLI 省略显式的 stats.input 字段时，会使用 stats.input_tokens - stats.cached。
对于原生 OpenAI 系列 Responses 流量，WebSocket/SSE 用量别名会以相同方式规范化；当 total_tokens 缺失或为 0 时，总量会回退到规范化输入 + 输出。
当当前会话快照较稀疏时，/status 和 session_status 还可以从最近的转录用量日志中恢复词元/缓存计数器和当前活动运行时模型标签。现有的非零实时值仍优先于转录回退值；当存储总量缺失或更小时，较大的面向提示词的转录总量可以胜出。
提供商配额窗口的用量凭证在可用时来自提供商特定钩子；否则 OpenClaw 会回退到从 auth profiles、环境变量或配置中匹配 OAuth/API-key 凭证。
助手转录条目会持久化相同的规范化用量形状，包括当活动模型已配置价格且提供商返回用量元数据时的 usage.cost。这让 /usage cost 和基于转录的会话状态在实时运行时状态消失后仍有稳定来源。

OpenClaw 将提供商用量计量与当前上下文快照分开。提供商 usage.total 可以包含缓存输入、输出和多次工具循环模型调用，因此它适合成本和遥测，但可能会高估实时上下文窗口。上下文显示和诊断使用最新提示词快照（promptTokens，或没有提示词快照时的最后一次模型调用）作为 context.used。

成本估算（显示时）

成本根据你的模型价格配置估算：

models.providers.<provider>.models[].cost

这些是 input、output、cacheRead 和 cacheWrite 的每 100 万词元美元价格。如果缺少价格，OpenClaw 只显示词元。OAuth 词元从不显示美元成本。

当 sidecar 和渠道到达 Gateway 网关就绪路径后，OpenClaw 会为尚无本地价格的已配置模型引用启动可选后台价格引导。该引导会获取远程 OpenRouter 和 LiteLLM 价格目录。在离线或受限网络上，将 models.pricing.enabled: false 设为跳过这些目录获取；显式的 models.providers.*.models[].cost 条目会继续驱动本地成本估算。

缓存 TTL 和剪枝影响

提供商提示词缓存只在缓存 TTL 窗口内生效。OpenClaw 可以选择运行缓存 TTL 剪枝：它会在缓存 TTL 过期后剪枝会话，然后重置缓存窗口，使后续请求可以复用新缓存的上下文，而不是重新缓存完整历史记录。当会话空闲超过 TTL 时，这可以降低缓存写入成本。

在 Gateway 网关配置 中配置它，并在会话剪枝中查看行为详情。

Heartbeat 可以在空闲间隔期间让缓存保持温热。如果你的模型缓存 TTL 是 1h，将 Heartbeat 间隔设置为略低于该值（例如 55m）可以避免重新缓存完整提示词，从而减少缓存写入成本。

在多智能体设置中，你可以保留一个共享模型配置，并用 agents.list[].params.cacheRetention 按智能体调优缓存行为。

如需完整的逐旋钮指南，见提示词缓存。

对于 Anthropic API 价格，缓存读取明显便宜于输入词元，而缓存写入会按更高倍数计费。最新费率和 TTL 倍数见 Anthropic 的提示词缓存价格：
https://docs.anthropic.com/docs/build-with-claude/prompt-caching

示例：用 Heartbeat 保持 1h 缓存温热

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
    heartbeat:
      every: "55m"

示例：按智能体缓存策略混合流量

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long" # default baseline for most agents
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m" # keep long cache warm for deep sessions
    - id: "alerts"
      params:
        cacheRetention: "none" # avoid cache writes for bursty notifications

agents.list[].params 会合并到所选模型的 params 之上，因此你可以只覆盖 cacheRetention，并继承其他模型默认值且保持不变。

示例：启用 Anthropic 1M 上下文 beta 标头

Anthropic 的 1M 上下文窗口目前受 beta 门控。OpenClaw 可以在受支持的 Opus 或 Sonnet 模型上启用 context1m 时，注入所需的 anthropic-beta 值。

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          context1m: true

这会映射到 Anthropic 的 context-1m-2025-08-07 beta 标头。

这仅在该模型条目上设置 context1m: true 时适用。

要求：凭证必须有资格使用长上下文。否则，Anthropic 会为该请求返回提供商侧速率限制错误。

如果你使用 OAuth/订阅词元（sk-ant-oat-*）向 Anthropic 认证，OpenClaw 会跳过 context-1m-* beta 标头，因为 Anthropic 目前会以 HTTP 401 拒绝该组合。

减少词元压力的提示

• 使用 /compact 汇总长会话。
• 在你的工作流中裁剪大型工具输出。
• 对截图密集型会话降低 agents.defaults.imageMaxDimensionPx。
• 保持技能描述简短（技能列表会被注入提示词）。
• 对冗长的探索性工作优先使用较小模型。

准确的技能列表开销公式见 Skills。

相关

• API 用量和成本
• 提示词缓存
• 用量跟踪

📄 API 使用量和费用

原文：https://docs.openclaw.ai/zh-CN/reference/api-usage-costs

本文档列出可能调用 API key 的功能以及其费用显示位置。它重点说明可能产生提供商用量或付费 API 调用的 OpenClaw 功能。

费用显示位置（聊天 + CLI）

每个会话的费用快照

• /status 会显示当前会话模型、上下文用量以及上一次响应的 token。
• 如果模型使用 API-key 认证，/status 还会显示上一次回复的预估费用。
• 如果实时会话元数据较少，/status 可以从最新的 transcript 用量条目中恢复 token/cache 计数器以及活动运行时模型标签。现有的非零实时值仍然优先；当已存储总量缺失或更小时，prompt 大小的 transcript 总量可能胜出。

每条消息的费用页脚

• /usage full 会在每条回复后附加用量页脚，包括预估费用（仅限 API-key）。
• /usage tokens 仅显示 token；订阅式 OAuth/token 和 CLI 流程会隐藏美元费用。
• Gemini CLI 注意事项：当 CLI 返回 JSON 输出时，OpenClaw 会从 stats 读取用量，将 stats.cached 标准化为 cacheRead，并在需要时根据 stats.input_tokens - stats.cached 推导输入 token。

Anthropic 注意事项：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用量已再次允许，因此 OpenClaw 将 Claude CLI 复用和 claude -p 用量视为此集成中已获认可的用法，除非 Anthropic 发布新策略。Anthropic 仍未公开 OpenClaw 可在 /usage full 中显示的逐消息美元预估。

CLI 用量窗口（提供商配额）

• openclaw status --usage 和 openclaw channels list 会显示提供商用量窗口（配额快照，不是逐消息费用）。
• 人类可读输出会在各提供商间统一为 X% left。
• 当前用量窗口提供商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi 和 z.ai。
• MiniMax 注意事项：其原始 usage_percent / usagePercent 字段表示剩余配额，因此 OpenClaw 会在显示前将其反转。存在基于数量的字段时，它们仍然优先。如果提供商返回 model_remains，OpenClaw 会优先使用聊天模型条目，在需要时从时间戳推导窗口标签，并在计划标签中包含模型名称。
• 这些配额窗口的用量认证会在可用时来自提供商特定钩子；否则 OpenClaw 会回退到从认证配置文件、环境变量或配置中匹配 OAuth/API-key 凭证。

详情和示例见 Token use & costs。

key 的发现方式

OpenClaw 可以从以下位置获取凭证：

• 认证配置文件（每个智能体，存储在 auth-profiles.json 中）。
• 环境变量（例如 OPENAI_API_KEY、BRAVE_API_KEY、FIRECRAWL_API_KEY）。
• 配置（models.providers.*.apiKey、plugins.entries.*.config.webSearch.apiKey、plugins.entries.firecrawl.config.webFetch.apiKey、memorySearch.*、talk.providers.*.apiKey）。
• Skills（skills.entries.<name>.apiKey），可将 key 导出到 skill 进程环境中。

可能消耗 key 的功能

1) 核心模型响应（聊天 + 工具）

每次回复或工具调用都会使用当前模型提供商（OpenAI、Anthropic 等）。这是用量和费用的主要来源。

这也包括订阅式托管提供商，它们仍会在 OpenClaw 本地 UI 之外计费，例如 OpenAI Codex、Alibaba Cloud Model Studio Coding Plan、MiniMax Coding Plan、Z.AI / GLM Coding Plan，以及启用 Extra Usage 的 Anthropic OpenClaw Claude 登录路径。

价格配置见 Models，显示方式见 Token use & costs。

2) 媒体理解（音频/图像/视频）

入站媒体可以在回复运行前被总结/转录。这会使用模型/提供商 API。

• 音频：OpenAI / Groq / Deepgram / DeepInfra / Google / Mistral。
• 图像：OpenAI / OpenRouter / Anthropic / DeepInfra / Google / MiniMax / Moonshot / Qwen / Z.AI。
• 视频：Google / Qwen / Moonshot。

见 媒体理解。

3) 图像和视频生成

共享生成能力也可能消耗提供商 key：

• 图像生成：OpenAI / Google / DeepInfra / fal / MiniMax
• 视频生成：DeepInfra / Qwen

当 agents.defaults.imageGenerationModel 未设置时，图像生成可以推断一个由认证支持的默认提供商。视频生成目前需要显式设置 agents.defaults.videoGenerationModel，例如 qwen/wan2.6-t2v。

见 图像生成、Qwen Cloud 和 Models。

4) 记忆嵌入 + 语义搜索

当配置为远程提供商时，语义记忆搜索会使用嵌入 API：

• memorySearch.provider = "openai" → OpenAI embeddings
• memorySearch.provider = "gemini" → Gemini embeddings
• memorySearch.provider = "voyage" → Voyage embeddings
• memorySearch.provider = "mistral" → Mistral embeddings
• memorySearch.provider = "deepinfra" → DeepInfra embeddings
• memorySearch.provider = "lmstudio" → LM Studio embeddings（本地/自托管）
• memorySearch.provider = "ollama" → Ollama embeddings（本地/自托管；通常没有托管 API 计费）
• 如果本地嵌入失败，可选择回退到远程提供商

你可以使用 memorySearch.provider = "local" 让它保持本地运行（无 API 用量）。

见 Memory。

5) Web 搜索工具

web_search 可能会根据你的提供商产生用量费用：

• Brave Search API：BRAVE_API_KEY 或 plugins.entries.brave.config.webSearch.apiKey
• Exa：EXA_API_KEY 或 plugins.entries.exa.config.webSearch.apiKey
• Firecrawl：FIRECRAWL_API_KEY 或 plugins.entries.firecrawl.config.webSearch.apiKey
• Gemini (Google Search)：GEMINI_API_KEY 或 plugins.entries.google.config.webSearch.apiKey
• Grok (xAI)：XAI_API_KEY 或 plugins.entries.xai.config.webSearch.apiKey
• Kimi (Moonshot)：KIMI_API_KEY、MOONSHOT_API_KEY 或 plugins.entries.moonshot.config.webSearch.apiKey
• MiniMax Search：MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY、MINIMAX_API_KEY 或 plugins.entries.minimax.config.webSearch.apiKey
• Ollama Web 搜索：对于可访问且已登录的本地 Ollama 主机无需 key；直接搜索 https://ollama.com 使用 OLLAMA_API_KEY，受认证保护的主机可复用普通 Ollama 提供商 bearer 认证
• Perplexity Search API：PERPLEXITY_API_KEY、OPENROUTER_API_KEY 或 plugins.entries.perplexity.config.webSearch.apiKey
• Tavily：TAVILY_API_KEY 或 plugins.entries.tavily.config.webSearch.apiKey
• DuckDuckGo：无需 key 的回退方案（无 API 计费，但非官方且基于 HTML）
• SearXNG：SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（无需 key/自托管；无托管 API 计费）

旧版 tools.web.search.* 提供商路径仍会通过临时兼容 shim 加载，但它们不再是推荐的配置表面。

Brave Search 免费额度： 每个 Brave 计划都包含每月续期的 \$5 免费额度。Search 计划每 1,000 次请求收费 \$5，因此该额度可免费覆盖每月 1,000 次请求。请在 Brave 仪表板中设置你的用量限制，以避免意外收费。

见 Web 工具。

5) Web 获取工具（Firecrawl）

当存在 API key 时，web_fetch 可以调用 Firecrawl：

• FIRECRAWL_API_KEY 或 plugins.entries.firecrawl.config.webFetch.apiKey

如果未配置 Firecrawl，该工具会回退到直接获取并使用内置 web-readability 插件（无付费 API）。禁用 plugins.entries.web-readability.enabled 可跳过本地 Readability 提取。

见 Web 工具。

6) 提供商用量快照（状态/健康检查）

某些状态命令会调用提供商用量端点来显示配额窗口或认证健康状态。这些调用通常频率较低，但仍会命中提供商 API：

• openclaw status --usage
• openclaw models status --json

见 Models CLI。

7) 压缩保护总结

压缩保护可以使用当前模型总结会话历史，它运行时会调用提供商 API。

见 会话管理 + 压缩。

8) 模型扫描 / 探测

openclaw models scan 可以探测 OpenRouter 模型，并在启用探测时使用 OPENROUTER_API_KEY。

见 Models CLI。

9) Talk（语音）

配置后，Talk 模式可以调用 ElevenLabs：

• ELEVENLABS_API_KEY 或 talk.providers.elevenlabs.apiKey

见 Talk 模式。

10) Skills（第三方 API）

Skills 可以在 skills.entries.<name>.apiKey 中存储 apiKey。如果某个 skill 使用该 key 调用外部 API，它可能会按该 skill 的提供商产生费用。

见 Skills。

相关内容

• Token 使用和费用
• Prompt caching
• 用量跟踪

📄 会话记录整理

原文：https://docs.openclaw.ai/zh-CN/reference/transcript-hygiene

OpenClaw 会在运行前（构建模型上下文时）对转录记录应用提供商特定修复。其中大多数是为满足严格提供商要求而使用的内存中调整。单独的会话文件修复流程也可能在加载会话前重写已存储的 JSONL，但只针对格式错误的行或作为持久记录无效的已持久化轮次。已交付的助手回复会保留在磁盘上；提供商特定的助手预填充剥离只会在构造出站载荷时发生。发生修复时，原始文件会在会话文件旁边备份。

范围包括：

• 仅运行时提示词上下文不进入用户可见的转录记录轮次
• 工具调用 ID 清理
• 工具调用输入校验
• 工具结果配对修复
• 轮次校验 / 排序
• 思维签名清理
• Thinking 签名清理
• 图像载荷清理
• 提供商重放前清理空白文本块
• 用户输入来源标记（用于跨会话路由提示词）
• Bedrock Converse 重放的空助手错误轮次修复

如果你需要转录记录存储细节，请参阅：

• 会话管理深度解析

全局规则：运行时上下文不是用户转录记录

运行时/系统上下文可以添加到某个轮次的模型提示词中，但它不是
最终用户撰写的内容。OpenClaw 会为 Gateway 网关回复、排队的后续消息、ACP、CLI 和嵌入式 Pi
运行保留单独面向转录记录的提示词正文。已存储的可见用户轮次使用该转录记录正文，而不是
经过运行时增强的提示词。

对于已经持久化运行时包装器的旧版会话，Gateway 网关历史
界面会在向 WebChat、TUI、REST 或 SSE 客户端返回消息前应用显示投影。

运行位置

所有转录记录卫生处理都集中在嵌入式运行器中：

• 策略选择：src/agents/transcript-policy.ts
• 清理/修复应用：src/agents/pi-embedded-runner/replay-history.ts 中的 sanitizeSessionHistory

该策略使用 provider、modelApi 和 modelId 来决定应用哪些处理。

独立于转录记录卫生处理，会话文件会在加载前（如有需要）被修复：

• src/agents/session-file-repair.ts 中的 repairSessionFileIfNeeded
• 从 run/attempt.ts 和 compact.ts（嵌入式运行器）调用

全局规则：图像清理

图像载荷始终会被清理，以防因大小限制而被提供商端拒绝
（缩小/重新压缩过大的 base64 图像）。

这也有助于控制支持视觉的模型由图像驱动的 token 压力。
较低的最大尺寸通常会减少 token 用量；较高的尺寸会保留细节。

实现：

• src/agents/pi-embedded-helpers/images.ts 中的 sanitizeSessionMessagesImages
• src/agents/tool-images.ts 中的 sanitizeContentBlocksImages
• 最大图像边长可通过 agents.defaults.imageMaxDimensionPx 配置（默认值：1200）。
• 此流程遍历重放内容时会移除空白文本块。变为空的助手
  轮次会从重放副本中删除；变为空的用户和工具结果
  轮次会收到非空的省略内容占位符。

全局规则：格式错误的工具调用

在构建模型上下文前，会丢弃同时缺少 input 和 arguments 的助手工具调用块。
这可防止提供商因部分持久化的工具调用而拒绝请求（例如，在速率限制失败后）。

实现：

• src/agents/session-transcript-repair.ts 中的 sanitizeToolCallInputs
• 应用于 src/agents/pi-embedded-runner/replay-history.ts 中的 sanitizeSessionHistory

全局规则：跨会话输入来源

当一个智能体通过 sessions_send（包括智能体到智能体的回复/公告步骤）向另一个会话发送提示词时，OpenClaw 会持久化创建的用户轮次，并带有：

• message.provenance.kind = "inter_session"

OpenClaw 还会在路由后的提示词文本前添加同轮次的 [Inter-session message ... isUser=false]
标记，以便活动模型调用能够区分外部会话输出和外部最终用户指令。此标记在可用时会包括
源会话、渠道和工具。为保持提供商兼容性，转录记录仍使用
role: "user"，但可见文本和来源元数据都会将该轮次标记为跨会话数据。

在上下文重建期间，OpenClaw 会对较早持久化的、只有来源元数据的
跨会话用户轮次应用相同标记。

提供商矩阵（当前行为）

OpenAI / OpenAI Codex

• 仅进行图像清理。
• 对 OpenAI Responses/Codex 转录记录，丢弃孤立的推理签名（后面没有内容块的独立推理项），并在模型路由切换后丢弃可重放的 OpenAI 推理。
• 保留可重放的 OpenAI Responses 推理项载荷，包括加密的空摘要项，以便手动/WebSocket 重放保持所需的 rs_* 状态与助手输出项配对。
• Native ChatGPT Codex Responses 遵循 Codex 传输一致性，在不带先前项 ID 的情况下重放先前的 Responses 推理/消息/函数载荷，同时保留会话 prompt_cache_key。
• 不进行工具调用 ID 清理。
• 工具结果配对修复可能移动真实匹配的输出，并为缺失的工具调用合成 Codex 风格的 aborted 输出。
• 不进行轮次校验或重新排序。
• 会将缺失的 OpenAI Responses 系列工具输出合成为 aborted，以匹配 Codex 重放规范化。
• 不剥离思维签名。

OpenAI 兼容的 Chat Completions

• 历史助手 thinking/reasoning 块会在重放前被剥离，使
  本地和代理风格的 OpenAI 兼容服务器不会收到先前轮次的
  reasoning 或 reasoning_content 等推理字段。
• 当前同轮次工具调用延续会保留附加到工具调用上的助手推理块，
  直到工具结果已被重放。
• 提供商拥有的例外可以在其传输协议要求
  重放推理元数据时选择退出。

Google（Generative AI / Gemini CLI / Antigravity）

• 工具调用 ID 清理：严格字母数字。
• 工具结果配对修复和合成工具结果。
• 轮次校验（Gemini 风格的轮次交替）。
• Google 轮次排序修正（如果历史以助手开头，则前置一个很小的用户引导）。
• Antigravity Claude：规范化 thinking 签名；丢弃未签名的 thinking 块。

Anthropic / Minimax（Anthropic 兼容）

• 工具结果配对修复和合成工具结果。
• 轮次校验（合并连续用户轮次以满足严格交替）。
• 启用 thinking 时，会从出站 Anthropic Messages
  载荷中剥离尾随助手预填充轮次，包括 Cloudflare AI Gateway 网关路由。
• 在提供商转换前，会剥离缺失、为空或空白重放签名的 Thinking 块。
  如果这会清空一个助手轮次，OpenClaw 会用非空的省略推理文本
  保持轮次形状。
• 必须被剥离的较旧纯 thinking 助手轮次会替换为
  非空的省略推理文本，使提供商适配器不会丢弃该重放
  轮次。

Amazon Bedrock（Converse API）

• 空助手流错误轮次会在重放前修复为非空回退文本块。
  Bedrock Converse 会拒绝带有 content: [] 的助手消息，因此
  带有 stopReason: "error" 且内容为空的已持久化助手轮次也会
  在加载前在磁盘上修复。
• 只包含空白文本块的助手流错误轮次会从内存中的重放副本中
  丢弃，而不是重放无效的空白块。
• 在 Converse 重放前，会剥离缺失、为空或空白重放签名的
  Claude thinking 块。如果这会清空一个助手轮次，OpenClaw
  会用非空的省略推理文本保持轮次形状。
• 必须被剥离的较旧纯 thinking 助手轮次会替换为
  非空的省略推理文本，使 Converse 重放保持严格的轮次形状。
• 重放会过滤 OpenClaw 交付镜像和 Gateway 网关注入的助手轮次。
• 图像清理通过全局规则应用。

Mistral（包括基于模型 ID 的检测）

• 工具调用 ID 清理：strict9（长度为 9 的字母数字）。

OpenRouter Gemini

• 思维签名清理：剥离非 base64 的 thought_signature 值（保留 base64）。

OpenRouter Anthropic

• 启用 reasoning 时，会从已验证的 OpenRouter
  OpenAI 兼容 Anthropic 模型载荷中剥离尾随助手预填充轮次，匹配
  直接 Anthropic 和 Cloudflare Anthropic 重放行为。

其他所有情况

• 仅进行图像清理。

历史行为（2026.1.22 之前）

在 2026.1.22 版本之前，OpenClaw 应用了多层转录记录卫生处理：

• 一个转录记录清理插件会在每次上下文构建时运行，并且可以：
• 修复工具使用/结果配对。
• 清理工具调用 ID（包括保留 _/- 的非严格模式）。
• 运行器还执行提供商特定的清理，这会重复处理。
• 提供商策略之外还会发生额外变更，包括：
• 在持久化前从助手文本中剥离 <final> 标签。
• 丢弃空助手错误轮次。
• 在工具调用后截断助手内容。

这种复杂性导致了跨提供商回归（尤其是 openai-responses
call_id|fc_id 配对）。2026.1.22 清理移除了该插件，将
逻辑集中到运行器中，并使 OpenAI 除图像清理外保持不触碰。

相关

• 会话管理
• 会话修剪

📄 日期和时间

原文：https://docs.openclaw.ai/zh-CN/date-time

OpenClaw 默认对 传输时间戳使用主机本地时间，并且 仅在系统提示词中使用用户时区。
会保留提供商时间戳，以便工具保持其原生语义（当前时间可通过 session_status 获取）。

消息封套（默认本地）

入站消息会包装一个时间戳（精确到分钟）：

[Provider ... 2026-01-05 16:26 PST] message text

无论提供商时区是什么，此封套时间戳 默认使用主机本地时间。

你可以覆盖此行为：

{
  agents: {
    defaults: {
      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
      envelopeTimestamp: "on", // "on" | "off"
      envelopeElapsed: "on", // "on" | "off"
    },
  },
}

• envelopeTimezone: "utc" 使用 UTC。
• envelopeTimezone: "local" 使用主机时区。
• envelopeTimezone: "user" 使用 agents.defaults.userTimezone（回退到主机时区）。
• 使用显式 IANA 时区（例如 "America/Chicago"）来指定固定时区。
• envelopeTimestamp: "off" 会从封套标头中移除绝对时间戳。
• envelopeElapsed: "off" 会移除已用时间后缀（+2m 样式）。

示例

本地（默认）：

[WhatsApp +1555 2026-01-18 00:19 PST] hello

用户时区：

[WhatsApp +1555 2026-01-18 00:19 CST] hello

启用已用时间：

[WhatsApp +1555 +30s 2026-01-18T05:19Z] follow-up

系统提示词：当前日期和时间

如果已知用户时区，系统提示词会包含一个专用的
当前日期和时间 部分，其中 仅包含时区（不包含时钟/时间格式），
以保持提示词缓存稳定：

Time zone: America/Chicago

当智能体需要当前时间时，请使用 session_status 工具；Status
卡片包含一行时间戳。

系统事件行（默认本地）

插入到智能体上下文中的排队系统事件会带有时间戳前缀，并使用与消息封套相同的
时区选择（默认：主机本地）。

System: [2026-01-12 12:19:17 PST] Model switched.

配置用户时区 + 格式

{
  agents: {
    defaults: {
      userTimezone: "America/Chicago",
      timeFormat: "auto", // auto | 12 | 24
    },
  },
}

• userTimezone 设置提示词上下文中的 用户本地时区。
• timeFormat 控制提示词中的 12 小时制/24 小时制显示。auto 跟随操作系统偏好设置。

时间格式检测（auto）

当 timeFormat: "auto" 时，OpenClaw 会检查操作系统偏好设置（macOS/Windows），
并回退到区域设置格式。检测到的值会 按进程缓存，
以避免重复系统调用。

工具载荷 + 连接器（原始提供商时间 + 规范化字段）

渠道工具会返回 提供商原生时间戳，并添加规范化字段以保持一致性：

• timestampMs：纪元毫秒数（UTC）
• timestampUtc：ISO 8601 UTC 字符串

会保留原始提供商字段，确保不会丢失任何信息。

• Slack：来自 API 的类纪元字符串
• Discord：UTC ISO 时间戳
• Telegram/WhatsApp：提供商特定的数字/ISO 时间戳

如果你需要本地时间，请在下游使用已知时区进行转换。

相关文档

• 系统提示词
• 时区
• 消息