[OpenClaw 文档]代理--基础

2026年 5月 13日 OpenClaw SE_You

本文档汇总了 OpenClaw 官方文档站代理 > 基础子模块下的全部 7 篇内容，源自 docs.openclaw.ai/zh-CN。

📑 本文目录（7 篇）

📄 Gateway 网关架构

原文：https://docs.openclaw.ai/zh-CN/concepts/architecture

概览

单个长期运行的 Gateway 网关 拥有所有消息表面（通过
Baileys 的 WhatsApp、通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
控制平面客户端（macOS 应用、CLI、Web UI、自动化）通过配置的绑定主机上的 WebSocket
连接到 Gateway 网关（默认 127.0.0.1:18789）。
节点（macOS/iOS/Android/headless）也通过 WebSocket 连接，但会声明带有显式能力/命令的 role: node。
每台主机一个 Gateway 网关；它是唯一打开 WhatsApp 会话的位置。
canvas host 由 Gateway 网关 HTTP 服务器在以下路径提供：
/__openclaw__/canvas/（智能体可编辑的 HTML/CSS/JS）
/__openclaw__/a2ui/（A2UI host）
它使用与 Gateway 网关相同的端口（默认 18789）。

组件和流程

Gateway 网关（守护进程）

维护提供商连接。
暴露类型化的 WS API（请求、响应、服务器推送事件）。
根据 JSON Schema 验证入站帧。
发出 agent、chat、presence、health、heartbeat、cron 等事件。

客户端（Mac 应用 / CLI / Web 管理）

每个客户端一个 WS 连接。
发送请求（health、status、send、agent、system-presence）。
订阅事件（tick、agent、presence、shutdown）。

节点（macOS / iOS / Android / headless）

使用 role: node 连接到同一个 WS 服务器。
在 connect 中提供设备身份；配对是基于设备的（角色 node），批准信息存储在设备配对存储中。
暴露 canvas.*、camera.*、screen.record、location.get 等命令。

协议详情：

Gateway 网关协议

WebChat

使用 Gateway 网关 WS API 获取聊天历史并发送消息的静态 UI。
在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接。

连接生命周期（单个客户端）

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>final {runId, status, summary}

线缆协议（摘要）

传输：WebSocket，带有 JSON 载荷的文本帧。
第一帧必须是 connect。
握手之后：
请求：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
事件：{type:"event", event, payload, seq?, stateVersion?}
hello-ok.features.methods / events 是设备发现元数据，而不是每个可调用辅助路由的生成式转储。
共享密钥认证使用 connect.params.auth.token 或
connect.params.auth.password，具体取决于配置的 Gateway 网关认证模式。
携带身份的模式，例如 Tailscale Serve
(gateway.auth.allowTailscale: true) 或非回环
gateway.auth.mode: "trusted-proxy"，会从请求标头满足认证，而不是使用 connect.params.auth.*。
私有入口 gateway.auth.mode: "none" 会完全禁用共享密钥认证；不要在公共/不受信任的入口上启用该模式。
对有副作用的方法（send、agent），需要幂等键才能安全重试；服务器会保留一个短生命周期的去重缓存。
节点必须在 connect 中包含 role: "node" 以及能力/命令/权限。

配对 + 本地信任

所有 WS 客户端（操作员 + 节点）都会在 connect 中包含设备身份。
新设备 ID 需要配对批准；Gateway 网关会为后续连接签发设备令牌。
直接 local loopback 连接可以自动批准，以保持同主机用户体验顺畅。
OpenClaw 还有一个狭窄的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。
Tailnet 和 LAN 连接（包括同主机 tailnet 绑定）仍然需要显式配对批准。
所有连接都必须签名 connect.challenge nonce。
签名载荷 v3 还会绑定 platform + deviceFamily；Gateway 网关会在重新连接时固定已配对的元数据，并在元数据变更时要求修复配对。
非本地连接仍然需要显式批准。
Gateway 网关认证（gateway.auth.*）仍然适用于所有连接，无论本地还是远程。

详情：Gateway 网关协议、配对、
安全。

协议类型和代码生成

TypeBox schema 定义协议。
JSON Schema 从这些 schema 生成。
Swift 模型从 JSON Schema 生成。

远程访问

首选：Tailscale 或 VPN。
替代方案：SSH 隧道

bash ssh -N -L 18789:127.0.0.1:18789 user@host

同样的握手 + 认证令牌适用于隧道连接。
在远程设置中，可以为 WS 启用 TLS + 可选固定。

运维快照

启动：openclaw gateway（前台运行，日志输出到 stdout）。
健康：通过 WS 的 health（也包含在 hello-ok 中）。
监控：使用 launchd/systemd 自动重启。

不变量

每台主机只有一个 Gateway 网关控制单个 Baileys 会话。
握手是强制性的；任何非 JSON 或首帧非 connect 的情况都会强制关闭。
事件不会重放；客户端必须在出现间隙时刷新。

📄 智能体运行时

原文：https://docs.openclaw.ai/zh-CN/concepts/agent

OpenClaw 运行一个单一嵌入式智能体运行时 - 每个 Gateway 网关一个智能体进程，拥有自己的工作区、引导文件和会话存储。本页介绍该运行时契约：工作区必须包含什么、哪些文件会被注入，以及会话如何基于它进行引导。

工作区（必需）

OpenClaw 使用单一智能体工作区目录（agents.defaults.workspace）作为智能体用于工具和上下文的唯一工作目录（cwd）。

推荐：如果缺少 ~/.openclaw/openclaw.json，请使用 openclaw setup 创建它并初始化工作区文件。

完整工作区布局 + 备份指南：Agent 工作区

如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的按会话工作区来覆盖此设置（参见 Gateway 网关配置）。

引导文件（已注入）

在 agents.defaults.workspace 内，OpenClaw 需要这些用户可编辑文件：

AGENTS.md - 操作说明 + “记忆”
SOUL.md - 人设、边界、语气
TOOLS.md - 用户维护的工具说明（例如 imsg、sag、约定）
BOOTSTRAP.md - 一次性的首次运行仪式（完成后删除）
IDENTITY.md - 智能体名称/气质/emoji
USER.md - 用户档案 + 首选称呼

在新会话的第一轮中，OpenClaw 会将这些文件的内容注入到系统提示词的项目上下文中。

空白文件会被跳过。大文件会被裁剪并用标记截断，使提示词保持精简（阅读文件可查看完整内容）。

如果某个文件缺失，OpenClaw 会注入一行“缺失文件”标记（并且 openclaw setup 会创建一个安全的默认模板）。

BOOTSTRAP.md 仅会为全新工作区创建（不存在其他引导文件）。当它待处理时，OpenClaw 会将其保留在项目上下文中，并为初始仪式添加系统提示词引导，而不是把它复制到用户消息中。如果你在完成仪式后删除它，后续重启时不应重新创建。

要完全禁用引导文件创建（用于预置工作区），请设置：

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

内置工具

核心工具（读取/执行/编辑/写入及相关系统工具）始终可用，但受工具策略约束。apply_patch 是可选的，并由 tools.exec.applyPatch 控制。TOOLS.md 不控制哪些工具存在；它只是说明你希望如何使用它们。

Skills

OpenClaw 会从以下位置加载 Skills（优先级从高到低）：

工作区：<workspace>/skills
项目智能体 Skills：<workspace>/.agents/skills
个人智能体 Skills：~/.agents/skills
托管/本地：~/.openclaw/skills
内置（随安装包提供）
额外 Skills 文件夹：skills.load.extraDirs

Skills 可以由配置/环境变量控制（参见 Gateway 网关配置中的 skills）。

运行时边界

嵌入式智能体运行时基于 Pi 智能体核心构建（模型、工具和提示词管线）。会话管理、设备发现、工具接线和渠道投递是在该核心之上的 OpenClaw 自有层。

会话

会话转录以 JSONL 形式存储在：

~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

会话 ID 是稳定的，并由 OpenClaw 选择。
不会读取来自其他工具的旧版会话文件夹。

流式传输期间 Steering

当队列模式为 steer 时，入站消息会被注入当前运行中。排队的 Steering 会在当前助手轮次完成执行其工具调用后、下一次 LLM 调用前送达。Pi 会为 steer 一起排空所有待处理的 Steering 消息；旧版 queue 会在每个模型边界排空一条消息。Steering 不再跳过当前助手消息中剩余的工具调用。

当队列模式为 followup 或 collect 时，入站消息会保留到当前轮次结束，然后用排队的载荷启动新的智能体轮次。有关模式和边界行为，请参见队列和 Steering queue。

分块流式传输会在已完成的助手块结束后立即发送；它默认关闭（agents.defaults.blockStreamingDefault: "off"）。
通过 agents.defaults.blockStreamingBreak 调整边界（text_end 与 message_end；默认为 text_end）。
用 agents.defaults.blockStreamingChunk 控制软性块分块（默认为 800-1200 个字符；优先段落断点，其次换行，最后句子）。
用 agents.defaults.blockStreamingCoalesce 合并流式分块以减少单行刷屏（发送前基于空闲时间合并）。非 Telegram 渠道需要显式设置 *.blockStreaming: true 才能启用分块回复。
详细工具摘要会在工具开始时发出（无防抖）；Control UI 会在可用时通过智能体事件流式传输工具输出。
更多详情：流式传输 + 分块。

模型引用

配置中的模型引用（例如 agents.defaults.model 和 agents.defaults.models）通过按第一个 / 分割来解析。

配置模型时使用 provider/model。
如果模型 ID 本身包含 /（OpenRouter 风格），请包含提供商前缀（示例：openrouter/moonshotai/kimi-k2）。
如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 匹配的唯一已配置提供商，最后才回退到已配置的默认提供商。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个已移除提供商的过期默认值。

配置（最小）

至少设置：

agents.defaults.workspace
channels.whatsapp.allowFrom（强烈推荐）

下一步：群聊 🦞

📄 Agent loop

原文：https://docs.openclaw.ai/zh-CN/concepts/agent-loop

智能体式循环是智能体完整的“真实”运行：接收 → 上下文组装 → 模型推理 →
工具执行 → 流式回复 → 持久化。它是把消息转化为操作和最终回复的权威路径，
同时保持会话状态一致。

在 OpenClaw 中，一个循环是每个会话一次串行化运行，会在模型思考、调用工具和流式输出时
发出生命周期事件和流事件。本文档说明这个真实循环如何端到端地接线。

入口点

Gateway 网关 RPC：agent 和 agent.wait。
CLI：agent 命令。

工作原理（高层）

agent RPC 校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，并立即返回 { runId, acceptedAt }。
agentCommand 运行智能体：
- 解析模型 + thinking/verbose/trace 默认值
- 加载 Skills 快照
- 调用 runEmbeddedPiAgent（pi-agent-core 运行时）
- 如果嵌入式循环未发出生命周期 end/error，则发出 生命周期 end/error
runEmbeddedPiAgent：
- 通过每会话 + 全局队列串行化运行
- 解析模型 + auth profile，并构建 pi 会话
- 订阅 pi 事件并流式传输 assistant/tool 增量
- 强制执行超时 -> 超时后中止运行
- 对于 Codex app-server 轮次，如果已接受的轮次在终端事件前停止产生 app-server 进度，则中止该轮次
- 返回载荷 + 使用量元数据
subscribeEmbeddedPiSession 将 pi-agent-core 事件桥接到 OpenClaw agent 流：
- 工具事件 => stream: "tool"
- assistant 增量 => stream: "assistant"
- 生命周期事件 => stream: "lifecycle"（phase: "start" | "end" | "error"）
agent.wait 使用 waitForAgentRun：
- 等待 runId 的 生命周期 end/error
- 返回 { status: ok|error|timeout, startedAt, endedAt, error? }

排队 + 并发

运行按会话键（会话通道）串行化，并可选择经过全局通道。
这会防止工具/会话竞争，并保持会话历史一致。
消息渠道可以选择队列模式（collect/steer/followup），并把它们送入这个通道系统。
参见命令队列。
转录写入也受会话文件上的会话写入锁保护。该锁感知进程并基于文件，因此能捕获绕过进程内队列或来自其他进程的写入者。会话转录写入者最多等待 session.writeLock.acquireTimeoutMs，之后才会报告会话忙；默认值为 60000 ms。
会话写入锁默认不可重入。如果某个 helper 有意在保留同一个逻辑写入者的同时嵌套获取同一把锁，它必须用 allowReentrant: true 显式选择加入。

会话 + 工作区准备

解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。
加载 Skills（或从快照复用），并注入到环境和提示词中。
解析 bootstrap/context 文件，并注入到系统提示词报告中。
获取会话写入锁；在流式传输前打开并准备 SessionManager。任何后续转录重写、压缩或截断路径，都必须在打开或修改转录文件前获取同一把锁。

提示词组装 + 系统提示词

系统提示词由 OpenClaw 的基础提示词、Skills 提示词、bootstrap 上下文和每次运行覆盖项构建。
强制执行模型特定限制和压缩预留 token。
参见系统提示词，了解模型会看到什么。

钩子点（你可以拦截的位置）

OpenClaw 有两个钩子系统：

内部钩子（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。
插件钩子：智能体/工具生命周期和 Gateway 网关流水线中的扩展点。

内部钩子（Gateway 网关钩子）

agent:bootstrap：在系统提示词最终确定前构建 bootstrap 文件时运行。
用它来添加/移除 bootstrap 上下文文件。
命令钩子：/new、/reset、/stop 以及其他命令事件（参见 Hooks 文档）。

参见 Hooks 获取设置和示例。

插件钩子（智能体 + Gateway 网关生命周期）

这些钩子在智能体循环或 Gateway 网关流水线内运行：

before_model_resolve：在会话前运行（没有 messages），用于在模型解析前确定性地覆盖提供商/模型。
before_prompt_build：在会话加载后运行（带有 messages），用于在提交提示词前注入 prependContext、systemPrompt、prependSystemContext 或 appendSystemContext。将 prependContext 用于每轮动态文本，将 system-context 字段用于应位于系统提示词空间中的稳定指导。
before_agent_start：旧版兼容钩子，可能在任一阶段运行；优先使用上面的显式钩子。
before_agent_reply：在内联操作之后、LLM 调用之前运行，让插件接管该轮并返回合成回复，或完全静默该轮。
agent_end：完成后检查最终消息列表和运行元数据。
before_compaction / after_compaction：观察或注释压缩周期。
before_tool_call / after_tool_call：拦截工具参数/结果。
before_install：检查内置扫描发现，并可选择阻止 Skills 或插件安装。
tool_result_persist：在工具结果写入 OpenClaw 拥有的会话转录前，同步转换工具结果。
message_received / message_sending / message_sent：入站 + 出站消息钩子。
session_start / session_end：会话生命周期边界。
gateway_start / gateway_stop：Gateway 网关生命周期事件。

出站/工具守卫的钩子决策规则：

before_tool_call：{ block: true } 是终端结果，并会停止低优先级处理器。
before_tool_call：{ block: false } 是空操作，不会清除之前的阻止。
before_install：{ block: true } 是终端结果，并会停止低优先级处理器。
before_install：{ block: false } 是空操作，不会清除之前的阻止。
message_sending：{ cancel: true } 是终端结果，并会停止低优先级处理器。
message_sending：{ cancel: false } 是空操作，不会清除之前的取消。

参见插件钩子，了解钩子 API 和注册详情。

Harness 可能会以不同方式适配这些钩子。Codex app-server harness 将
OpenClaw 插件钩子作为已记录镜像表面的兼容性契约，而 Codex 原生钩子仍是独立的更低层 Codex 机制。

流式传输 + 部分回复

assistant 增量从 pi-agent-core 流式传输，并作为 assistant 事件发出。
分块流式传输可以在 text_end 或 message_end 上发出部分回复。
推理流式传输可以作为单独流发出，也可以作为分块回复发出。
参见流式传输，了解分块和分块回复行为。

工具执行 + 消息工具

工具 start/update/end 事件会在 tool 流上发出。
工具结果在记录/发出前会针对大小和图像载荷进行清理。
会跟踪消息工具发送，以抑制重复的 assistant 确认。

回复塑形 + 抑制

最终载荷由以下内容组装：
assistant 文本（以及可选推理）
内联工具摘要（当 verbose + 允许时）
模型出错时的 assistant 错误文本
精确静默 token NO_REPLY / no_reply 会从出站载荷中过滤。
消息工具重复项会从最终载荷列表中移除。
如果没有剩余可渲染载荷且工具出错，则会发出 fallback 工具错误回复
（除非消息工具已经发送了用户可见回复）。

压缩 + 重试

自动压缩会发出 compaction 流事件，并可能触发重试。
重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。
参见压缩，了解压缩流水线。

事件流（当前）

lifecycle：由 subscribeEmbeddedPiSession 发出（并由 agentCommand 作为 fallback 发出）
assistant：来自 pi-agent-core 的流式增量
tool：来自 pi-agent-core 的流式工具事件

聊天渠道处理

assistant 增量会缓冲到聊天 delta 消息中。
聊天 final 会在 生命周期 end/error 上发出。

超时

agent.wait 默认值：30 秒（仅等待）。timeoutMs 参数可覆盖。
智能体运行时：agents.defaults.timeoutSeconds 默认值为 172800 秒（48 小时）；在 runEmbeddedPiAgent 中通过中止计时器强制执行。
Cron 运行时：隔离的智能体轮次 timeoutSeconds 由 cron 拥有。调度器会在执行开始时启动该计时器，在配置的截止时间中止底层运行，然后在记录超时前运行有界清理，这样陈旧的子会话就不能让通道卡住。
会话活跃性诊断：启用诊断后，diagnostics.stuckSessionWarnMs 会分类长时间处于 processing 且没有观察到回复、工具、Status、block 或 ACP 进度的会话。活动的嵌入式运行、模型调用和工具调用会报告为 session.long_running；没有近期进度的活动工作会报告为 session.stalled；session.stuck 保留用于没有活动工作的陈旧会话账本。陈旧会话账本会立即释放受影响的会话通道；停滞的嵌入式运行只有在 diagnostics.stuckSessionAbortMs 之后才会中止并排空（默认：至少 10 分钟且为警告阈值的 5 倍），这样排队工作可以恢复，而不会切断只是较慢的运行。恢复会发出结构化的 requested/completed 结果，并且只有在同一个处理 generation 仍是当前状态时，诊断状态才会标记为空闲。重复的 session.stuck 诊断会在会话保持不变时退避。
模型空闲超时：如果在空闲窗口前没有响应块到达，OpenClaw 会中止模型请求。models.providers.<id>.timeoutSeconds 会为较慢的本地/自托管提供商延长这个空闲看门狗；否则 OpenClaw 会在配置了 agents.defaults.timeoutSeconds 时使用它，默认上限为 120 秒。没有显式模型或智能体超时的 cron 触发运行会禁用空闲看门狗，并依赖 cron 外层超时。
提供商 HTTP 请求超时：models.providers.<id>.timeoutSeconds 适用于该提供商的模型 HTTP 获取，包括连接、headers、body、SDK 请求超时、总 guarded-fetch 中止处理以及模型流空闲看门狗。对于 Ollama 等较慢的本地/自托管提供商，请先使用此项，再提高整个智能体运行时超时。

可能提前结束的位置

智能体超时（中止）
AbortSignal（取消）
Gateway 网关断开连接或 RPC 超时
agent.wait 超时（仅等待，不会停止智能体）

📄 系统提示词

原文：https://docs.openclaw.ai/zh-CN/concepts/system-prompt

OpenClaw 会为每次智能体运行构建自定义系统提示词。该提示词由 OpenClaw 所有，不会使用 pi-coding-agent 默认提示词。

提示词由 OpenClaw 组装，并注入到每次智能体运行中。

提示词组装有三层：

buildAgentSystemPrompt 根据显式输入渲染提示词。它应该
保持为纯渲染器，不应直接读取全局配置。
resolveAgentSystemPromptConfig 为特定智能体解析由配置支持的提示词开关，例如
所有者显示、TTS 提示、模型别名、记忆引用模式，以及子智能体
委派模式。
运行时适配器（嵌入式、CLI、命令/导出预览、压缩）收集
实时事实，例如工具、沙箱状态、渠道能力、上下文文件，
以及提供商提示词贡献，然后调用已配置的提示词门面。

这样可以让导出/调试提示词表面与实时运行保持一致，而不会
把每个运行时特定细节都塞进一个单体构建器。

提供商插件可以贡献感知缓存的提示词指导，而无需替换
完整的 OpenClaw 所有提示词。提供商运行时可以：

替换少量具名核心章节（interaction_style、
tool_call_style、execution_bias）
在提示词缓存边界上方注入一个稳定前缀
在提示词缓存边界下方注入一个动态后缀

将提供商所有的贡献用于模型家族特定调优。保留旧版
before_prompt_build 提示词变更用于兼容性或真正全局的提示词
变更，而不是普通提供商行为。

OpenAI GPT-5 家族叠加层会让核心执行规则保持较小，并添加
模型特定指导，覆盖人格锁定、简洁输出、工具纪律、
并行查找、交付物覆盖、验证、缺失上下文，以及
终端工具卫生。

结构

该提示词有意保持紧凑，并使用固定章节：

工具：结构化工具事实来源提醒，以及运行时工具使用指导。
执行倾向：紧凑的跟进指导：对可执行请求在当前轮次中行动，
持续推进直到完成或受阻，从较弱的工具结果中恢复，
实时检查可变状态，并在最终回复前验证。
安全：简短的护栏提醒，避免寻求权力的行为或绕过监督。
Skills（可用时）：告诉模型如何按需加载技能说明。
OpenClaw 控制：告诉模型在配置/重启工作中优先使用 gateway 工具，
并避免编造 CLI 命令。
OpenClaw 自更新：如何用 config.schema.lookup 安全检查配置，
用 config.patch 修补配置，使用 config.apply 替换完整配置，
并且仅在用户明确请求时运行 update.run。仅所有者可用的
gateway 工具也会拒绝重写 tools.exec.ask / tools.exec.security，
包括会规范化到这些受保护执行路径的旧版 tools.bash.*
别名。
工作区：工作目录（agents.defaults.workspace）。
文档：OpenClaw 文档/source 的本地路径，以及何时读取它们。
工作区文件（已注入）：表示启动文件已包含在下方。
沙箱（启用时）：表示沙箱隔离运行时、沙箱路径，以及是否可用提权执行。
当前日期和时间：仅时区（缓存稳定；实时钟来自 session_status）。
助手输出指令：紧凑的附件、语音备注和回复标签语法。
Heartbeat：当默认智能体启用 Heartbeat 时的 Heartbeat 提示词和确认行为。
运行时：主机、操作系统、Node、模型、仓库根目录（检测到时）、思考等级（一行）。
推理：当前可见性等级 + /reasoning 切换提示。

OpenClaw 会把大型稳定内容（包括项目上下文）放在
内部提示词缓存边界上方。易变的渠道/会话章节，例如
控制 UI 嵌入指导、消息、语音、群聊上下文、
回应、Heartbeat 和运行时，会追加到该边界下方，
这样带前缀缓存的本地后端可以在不同渠道轮次之间复用稳定的工作区前缀。
同样，当接受的 schema 已经携带该运行时细节时，工具描述也应避免嵌入当前
渠道名称。

工具章节还包含面向长时间运行工作的运行时指导：

对未来跟进（check back later、提醒、周期性工作）使用 cron，
而不是 exec 睡眠循环、yieldMs 延迟技巧，或重复的 process
轮询
exec / process 仅用于现在启动并继续在后台运行的命令
当启用自动完成唤醒时，只启动一次命令，并在它输出内容或失败时依赖
基于推送的唤醒路径
当你需要检查正在运行的命令时，使用 process 查看日志、状态、输入或干预
如果任务更大，优先使用 sessions_spawn；子智能体完成是
基于推送的，并会自动向请求者回报
不要为了等待完成而循环轮询 subagents list / sessions_list

agents.defaults.subagents.delegationMode 可以增强此指导。
默认的 suggest 模式保留基线提示。prefer 会添加一个专门的
子智能体委派章节，告诉主智能体充当响应迅速的
协调者，并将任何比直接回复更复杂的事项通过 sessions_spawn
推送出去。这只是提示词层面的；工具策略仍控制
sessions_spawn 是否可用。

当启用实验性的 update_plan 工具时，工具章节还会告诉
模型只在非平凡的多步骤工作中使用它，始终保持恰好一个
in_progress 步骤，并避免在每次更新后重复整个计划。

系统提示词中的安全护栏是建议性的。它们指导模型行为，但不强制执行策略。使用工具策略、执行审批、沙箱隔离和渠道 allowlist 进行硬性强制；运营者可以按设计禁用这些机制。

在带原生审批卡片/按钮的渠道上，运行时提示词现在会告诉
智能体优先依赖该原生审批 UI。只有当工具结果表示聊天审批不可用，
或手动审批是唯一路径时，才应包含手动 /approve 命令。

提示词模式

OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为每次运行设置
promptMode（不是面向用户的配置）：

full（默认）：包含上面的所有章节。
minimal：用于子智能体；省略记忆召回、OpenClaw
自更新、模型别名、用户身份、助手输出指令、
消息、静默回复和 Heartbeat。工具、安全、
提供时的 Skills、工作区、沙箱、当前日期和时间（已知时）、
运行时，以及注入的上下文仍可用。
none：仅返回基础身份行。

当 promptMode=minimal 时，额外注入的提示词会标记为子智能体
上下文，而不是群聊上下文。

对于渠道自动回复运行，当直接/群聊上下文已经包含解析后的
会话特定 NO_REPLY 行为时，OpenClaw 可以省略通用的静默回复
章节。这样可以避免在全局系统提示词和渠道上下文中重复 token 机制。

提示词快照

OpenClaw 将 Codex runtime 正常路径的已提交提示词快照保存在
test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/ 下。它们会渲染
选定的应用服务器线程/轮次参数，以及为 Telegram 私信、Discord 群组和 Heartbeat 轮次
重建的模型绑定提示词层栈。该栈包含一个固定的 Codex gpt-5.5
模型提示词夹具，它由 Codex 的模型目录/缓存形状生成，还包含
Codex 正常路径权限开发者文本、OpenClaw 开发者说明、
当 OpenClaw 提供时的轮次范围协作模式说明、用户轮次输入，
以及对动态工具规格的引用。

使用 pnpm prompt:snapshots:sync-codex-model 刷新固定的 Codex 模型提示词夹具。
默认情况下，该脚本会先查找 $CODEX_HOME/models_cache.json 中的
Codex 运行时缓存，然后查找 ~/.codex/models_cache.json，
最后才回退到维护者 Codex checkout 约定路径
~/code/codex/codex-rs/models-manager/models.json。如果这些来源都不存在，
命令会退出且不更改已提交夹具。传入 --catalog <path> 可从特定的
models_cache.json 或 models.json 文件刷新。

这些快照仍然不是逐字节的原始 OpenAI 请求捕获。Codex
可以在 OpenClaw 发送线程和轮次参数后，在 Codex runtime 内添加
运行时所有的工作区上下文，例如 AGENTS.md、环境上下文、
记忆、应用/插件说明，以及内置的 Default
协作模式说明。

用 pnpm prompt:snapshots:gen 重新生成它们，并用
pnpm prompt:snapshots:check 验证漂移。CI 会在额外的
边界分片中运行漂移检查，以便提示词变更和快照更新保持附着在同一个
PR 上。

工作区启动注入

启动文件会被裁剪并追加到项目上下文下方，这样模型无需显式读取也能看到身份和画像上下文：

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
USER.md
HEARTBEAT.md
BOOTSTRAP.md（仅在全新工作区中）
MEMORY.md（存在时）

除非某个文件有特定门控，否则这些文件都会在每个轮次中注入到上下文窗口。
当默认智能体禁用 Heartbeat，或
agents.defaults.heartbeat.includeSystemPromptSection 为 false 时，
HEARTBEAT.md 会在普通运行中省略。保持注入文件简洁，
尤其是 MEMORY.md。MEMORY.md 旨在保持为一份
经过整理的长期摘要；详细日常笔记应放在 memory/*.md 中，
由 memory_search 和 memory_get 按需检索。过大的
MEMORY.md 文件会增加提示词用量，并且由于下面的启动文件限制，
可能只会被部分注入。

当会话运行在原生 Codex harness 上时，Codex 会通过自己的项目文档发现
加载 AGENTS.md。OpenClaw 仍会解析剩余启动文件，并将它们作为 Codex
配置说明转发，因此 SOUL.md、TOOLS.md、IDENTITY.md、USER.md、
HEARTBEAT.md、BOOTSTRAP.md 和 MEMORY.md 会继续保持相同的工作区上下文
角色，而不会重复 AGENTS.md。

memory/*.md 日常文件不是普通启动项目上下文的一部分。在常规轮次中，它们会通过 memory_search 和 memory_get 工具按需访问，因此除非模型显式读取它们，否则不会占用上下文窗口。裸 /new 和 /reset 轮次是例外：运行时可以为第一个轮次把最近的日常记忆作为一次性启动上下文块前置。

大文件会带标记截断。每个文件的最大大小由
agents.defaults.bootstrapMaxChars 控制（默认：12000）。跨文件注入的启动
内容总量受 agents.defaults.bootstrapTotalMaxChars 限制
（默认：60000）。缺失文件会注入简短的缺失文件标记。发生截断时，
OpenClaw 可以注入一条简洁的系统提示词警告通知；通过
agents.defaults.bootstrapPromptTruncationWarning 控制它（off、once、always；
默认：once）。详细的原始/注入计数会保留在诊断中，例如
/context、/status、Doctor 和日志。

对于记忆文件，截断并不是数据丢失：文件在磁盘上保持完整，
但在模型直接读取或搜索记忆之前，只能看到缩短后的注入副本。
如果 MEMORY.md 反复被截断，请将其提炼为更短的持久摘要，
并把详细历史移入 memory/*.md，或有意提高启动限制。

子智能体会话只注入 AGENTS.md 和 TOOLS.md（其他启动文件
会被过滤掉，以保持子智能体上下文较小）。

内部钩子可以通过 agent:bootstrap 拦截这一步，以变更或替换
注入的启动文件（例如将 SOUL.md 换成备用人格）。

如果你想让智能体听起来不那么泛泛，先阅读
SOUL.md 人格指南。

要检查每个注入文件的贡献量（原始与注入、截断，以及工具 schema 开销），请使用 /context list 或 /context detail。请参阅上下文。

时间处理

当已知用户时区时，系统提示词会包含一个专用的 Current Date & Time 部分。为了保持提示词缓存稳定，它现在只包含时区（不包含动态时钟或时间格式）。

当智能体需要当前时间时，使用 session_status；状态卡片包含时间戳行。同一个工具还可以选择设置按会话生效的模型覆盖（model=default 会清除它）。

配置项：

agents.defaults.userTimezone
agents.defaults.timeFormat (auto | 12 | 24)

完整行为详情请参阅日期和时间。

Skills

当存在符合条件的 Skills 时，OpenClaw 会注入一个紧凑的可用 Skills 列表
（formatSkillsForPrompt），其中包含每个 Skill 的文件路径。提示词会指示模型使用 read 加载列出位置中的 SKILL.md（工作区、托管或内置）。如果没有符合条件的 Skills，则省略 Skills 部分。

符合条件包括 Skill 元数据门控、运行时环境/配置检查，以及在配置了 agents.defaults.skills 或 agents.list[].skills 时生效的智能体 Skill 允许列表。

插件内置的 Skills 只有在其所属插件启用时才符合条件。这允许工具插件公开更深入的操作指南，而无需把所有这些指南直接嵌入每个工具描述中。

<available_skills>
  <skill>
    <name>...</name>
    <description>...</description>
    <location>...</location>
  </skill>
</available_skills>

这样可以保持基础提示词较小，同时仍然支持有针对性的 Skill 使用。

Skills 列表预算由 Skills 子系统负责：

全局默认值：skills.limits.maxSkillsPromptChars
按智能体覆盖：agents.list[].skillsLimits.maxSkillsPromptChars

通用有界运行时摘录使用另一个配置面：

agents.defaults.contextLimits.*
agents.list[].contextLimits.*

这种拆分让 Skills 大小控制与运行时读取/注入大小控制分离，例如 memory_get、实时工具结果和压缩后的 AGENTS.md 刷新。

文档

系统提示词包含一个文档部分。当本地文档可用时，它会指向本地 OpenClaw 文档目录（Git checkout 中的 docs/，或内置 npm 包文档）。如果本地文档不可用，它会回退到
https://docs.openclaw.ai。

同一部分还包含 OpenClaw 源码位置。Git checkout 会公开本地源码根目录，使智能体可以直接检查代码。包安装会包含 GitHub 源码 URL，并告诉智能体在文档不完整或过期时去那里查看源码。提示词还会提到公共文档镜像、社区 Discord 和用于发现 Skills 的 ClawHub
(https://clawhub.ai)。它会告诉模型，对于 OpenClaw 行为、命令、配置或架构，优先查阅文档，并在可行时自行运行 openclaw status（只有在缺少访问权限时才询问用户）。对于配置，它会专门指引智能体使用 gateway 工具操作
config.schema.lookup 获取精确到字段级别的文档和约束，然后再查阅
docs/gateway/configuration.md 和 docs/gateway/configuration-reference.md
获取更广泛的指南。

📄 上下文

原文：https://docs.openclaw.ai/zh-CN/concepts/context

“上下文”是 OpenClaw 在一次运行中发送给模型的所有内容。它受模型的 上下文窗口（token 限制）约束。

初学者心智模型：

系统提示词（由 OpenClaw 构建）：规则、工具、Skills 列表、时间/运行时，以及注入的工作区文件。
对话历史：你在此会话中的消息 + 助手的消息。
工具调用/结果 + 附件：命令输出、文件读取、图片/音频等。

上下文与“记忆”不是一回事：记忆可以存储在磁盘上并稍后重新加载；上下文是当前模型窗口内的内容。

快速开始（检查上下文）

/status → 快速查看“我的窗口有多满？”视图 + 会话设置。
/context list → 已注入的内容 + 粗略大小（按文件 + 总计）。
/context detail → 更深入的拆分：按文件、按工具 schema 大小、按 Skills 条目大小，以及系统提示词大小。
/context map → 当前会话中已跟踪上下文贡献项的 WinDirStat 风格树状图图片。
/usage tokens → 在普通回复后附加逐条回复的用量页脚。
/compact → 将较早历史总结为一个紧凑条目，以释放窗口空间。

另请参阅：斜杠命令、Token 使用与费用、压缩。

示例输出

值会因模型、提供商、工具策略以及你的工作区内容而异。

`/context list`

🧠 Context breakdown
Workspace: <workspaceDir>
Bootstrap max/file: 12,000 chars
Sandbox: mode=non-main sandboxed=false
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))

Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
- HEARTBEAT.md: MISSING | raw 0 | injected 0
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)

Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
Tool list (system prompt text): 1,032 chars (~258 tok)
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
Tools: (same as above)

Session tokens (cached): 14,250 total / ctx=32,000

`/context detail`

🧠 Context breakdown (detailed)
…
Top skills (prompt entry size):
- frontend-design: 412 chars (~103 tok)
- oracle: 401 chars (~101 tok)
… (+10 more skills)

Top tools (schema size):
- browser: 9,812 chars (~2,453 tok)
- exec: 6,240 chars (~1,560 tok)
… (+N more tools)

`/context map`

发送一张从最新缓存运行报告生成的图片。在会话中有普通消息生成运行报告之前，/context map 会返回一条不可用消息，而不是渲染估算图。矩形面积与已跟踪的提示词字符数成正比：

注入的工作区文件
基础系统提示词文本
Skills 提示词条目
工具 JSON schema

当没有缓存运行报告时，/context list、/context detail 和 /context json 仍可检查按需估算结果。

哪些内容会计入上下文窗口

模型接收的所有内容都会计入，包括：

系统提示词（所有部分）。
对话历史。
工具调用 + 工具结果。
附件/转写（图片/音频/文件）。
压缩摘要和裁剪产物。
提供商“包装器”或隐藏头部（不可见，但仍会计入）。

OpenClaw 如何构建系统提示词

系统提示词归 OpenClaw 所有，并在每次运行时重新构建。它包括：

工具列表 + 简短说明。
Skills 列表（仅元数据；见下文）。
工作区位置。
时间（UTC + 如已配置则转换后的用户时间）。
运行时元数据（主机/OS/模型/thinking）。
在 项目上下文 下注入的工作区启动文件。

完整拆分：系统提示词。

注入的工作区文件（项目上下文）

默认情况下，OpenClaw 会注入一组固定的工作区文件（如果存在）：

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
USER.md
HEARTBEAT.md
BOOTSTRAP.md（仅首次运行）

大文件会按文件使用 agents.defaults.bootstrapMaxChars 截断（默认 12000 字符）。OpenClaw 还会使用 agents.defaults.bootstrapTotalMaxChars 对所有文件实施总启动注入上限（默认 60000 字符）。/context 会显示 原始大小与注入大小，以及是否发生截断。

发生截断时，运行时可以在项目上下文下方注入提示词内警告块。使用 agents.defaults.bootstrapPromptTruncationWarning 配置此行为（off、once、always；默认 once）。

Skills：已注入与按需加载

系统提示词包含紧凑的 Skills 列表（名称 + 描述 + 位置）。此列表有实际开销。

Skills 指令默认_不会_包含在内。模型预期只在需要时 read 该 Skill 的 SKILL.md。

工具：有两类成本

工具以两种方式影响上下文：

系统提示词中的 工具列表文本（你看到的“Tooling”）。
工具 schema（JSON）。这些会发送给模型，以便模型调用工具。它们会计入上下文，即使你不会以纯文本形式看到它们。

/context detail 会拆分最大的工具 schema，方便你查看主要占用来自哪里。

命令、指令和“内联快捷方式”

斜杠命令由 Gateway 网关处理。有几种不同的行为：

独立命令：只包含 /... 的消息会作为命令运行。
指令：/think、/verbose、/trace、/reasoning、/elevated、/model、/queue 会在模型看到消息前被剥离。
仅包含指令的消息会持久化会话设置。
普通消息中的内联指令会作为逐消息提示。
内联快捷方式（仅限允许列表中的发送者）：普通消息中的某些 /... token 可以立即运行（示例：“hey /status”），并会在模型看到剩余文本前被剥离。

详情：斜杠命令。

会话、压缩和裁剪（哪些内容会持久化）

跨消息持久化的内容取决于机制：

普通历史 会持久保存在会话转写中，直到按策略压缩/裁剪。
压缩会将摘要持久化到转写中，并保留最近消息不变。
裁剪会从_内存中_的提示词里丢弃旧工具结果，以释放上下文窗口空间，但不会重写会话转写 - 完整历史仍可在磁盘上检查。

文档：会话、压缩、会话裁剪。

默认情况下，OpenClaw 使用内置的 legacy 上下文引擎进行组装和压缩。如果你安装了一个提供 kind: "context-engine" 的插件，并通过 plugins.slots.contextEngine 选择它，OpenClaw 会改为将上下文组装、/compact 以及相关 subagent 上下文生命周期钩子委托给该引擎。ownsCompaction: false 不会自动回退到旧版引擎；活动引擎仍必须正确实现 compact()。有关完整可插拔接口、生命周期钩子和配置，请参阅上下文引擎。

`/context` 实际报告什么

/context 会优先使用最新的 运行构建 系统提示词报告（如果可用）：

System prompt (run) = 从上一次嵌入式（可使用工具）运行中捕获，并持久化在会话存储中。
System prompt (estimate) = 当不存在运行报告时（或通过不会生成报告的 CLI 后端运行时）即时计算。

无论哪种方式，它都会报告大小和主要贡献项；它不会转储完整系统提示词或工具 schema。

📄 Agent 工作区

原文：https://docs.openclaw.ai/zh-CN/concepts/agent-workspace

工作区是智能体的家。它是文件工具和工作区上下文使用的唯一工作目录。请保持其私密，并将其视为记忆。

这不同于 ~/.openclaw/，后者存储配置、凭证和会话。

工作区是默认 cwd，不是严格沙箱。工具会基于工作区解析相对路径，但除非启用沙箱隔离，否则绝对路径仍然可以访问主机上的其他位置。如果你需要隔离，请使用 agents.defaults.sandbox（和/或按智能体配置沙箱）。

启用沙箱隔离且 workspaceAccess 不是 "rw" 时，工具会在 ~/.openclaw/sandboxes 下的沙箱工作区内运行，而不是在你的主机工作区内运行。

默认位置

默认：~/.openclaw/workspace
如果设置了 OPENCLAW_PROFILE 且它不是 "default"，默认位置会变为 ~/.openclaw/workspace-<profile>。
在 ~/.openclaw/openclaw.json 中覆盖：

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

如果缺少工作区和引导文件，openclaw onboard、openclaw configure 或 openclaw setup 会创建它们并写入初始内容。

沙箱种子复制只接受工作区内的常规文件；解析到源工作区之外的符号链接/硬链接别名会被忽略。

如果你已经自己管理工作区文件，可以禁用引导文件创建：

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

额外工作区文件夹

较旧的安装可能创建了 ~/openclaw。保留多个工作区目录可能导致令人困惑的身份验证或状态漂移，因为同一时间只有一个工作区处于活动状态。

建议：保留单个活动工作区。如果你不再使用额外文件夹，请将它们归档或移到废纸篓（例如 trash ~/openclaw）。如果你有意保留多个工作区，请确保 agents.defaults.workspace 指向活动的那个。

openclaw doctor 在检测到额外工作区目录时会发出警告。

工作区文件映射

这些是 OpenClaw 期望在工作区内存在的标准文件：

智能体的操作指令，以及它应如何使用记忆。每个会话开始时加载。适合放置规则、优先级和“如何表现”的细节。

人设、语气和边界。每个会话都会加载。指南：SOUL.md 人格指南。

用户是谁，以及如何称呼他们。每个会话都会加载。

智能体的名称、气质和 emoji。在引导仪式期间创建/更新。

关于你的本地工具和约定的说明。它不控制工具可用性；仅提供指导。

用于 heartbeat 运行的可选微型检查清单。保持简短以避免 token 消耗。

在 Gateway 网关重启时自动运行的可选启动检查清单（当启用内部钩子时）。保持简短；使用消息工具发送外发消息。

一次性首次运行仪式。只会为全新的工作区创建。仪式完成后删除它。

每日记忆日志（每天一个文件）。建议在会话开始时读取今天 + 昨天。

精选长期记忆：持久事实、偏好、决策和简短摘要。将详细日志保存在 memory/YYYY-MM-DD.md 中，这样记忆工具可以按需检索，而不会把它们注入到每个提示中。只在主私有会话中加载 MEMORY.md（不要在共享/群组上下文中加载）。有关工作流和自动记忆刷新，请参阅记忆。

工作区专属 Skills。该工作区中优先级最高的 Skills 位置。名称冲突时会覆盖项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills 和 skills.load.extraDirs。

用于节点显示的 Canvas UI 文件（例如 canvas/index.html）。

如果缺少任何引导文件，OpenClaw 会向会话中注入“缺失文件”标记并继续。大型引导文件在注入时会被截断；可使用 agents.defaults.bootstrapMaxChars（默认：12000）和 agents.defaults.bootstrapTotalMaxChars（默认：60000）调整限制。openclaw setup 可以重新创建缺失的默认文件，而不会覆盖已有文件。

工作区中不包含什么

以下内容位于 ~/.openclaw/ 下，不应提交到工作区仓库：

~/.openclaw/openclaw.json（配置）
~/.openclaw/agents/<agentId>/agent/auth-profiles.json（模型身份验证配置：OAuth + API 密钥）
~/.openclaw/agents/<agentId>/agent/codex-home/（每智能体的 Codex runtime 账户、配置、Skills、插件和原生线程状态）
~/.openclaw/credentials/（渠道/提供商状态以及旧版 OAuth 导入数据）
~/.openclaw/agents/<agentId>/sessions/（会话转录 + 元数据）
~/.openclaw/skills/（托管 Skills）

如果你需要迁移会话或配置，请单独复制它们，并将它们排除在版本控制之外。

Git 备份（建议，私有）

将工作区视为私有记忆。将它放入私有 git 仓库，以便备份和恢复。

在运行 Gateway 网关的机器上执行这些步骤（工作区就在那台机器上）。

如果安装了 git，全新的工作区会自动初始化。如果此工作区还不是仓库，请运行：

```bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```

1. 在 GitHub 上创建新的私有仓库。
2. 不要用 README 初始化（避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程仓库并推送：

    ```bash
    git branch -M main
    git remote add origin <https-url>
    git push -u origin main
    ```
  </Tab>
  <Tab title="GitHub CLI (gh)">
    ```bash
    gh auth login
    gh repo create openclaw-workspace --private --source . --remote origin --push
    ```
  </Tab>
  <Tab title="GitLab Web UI">
    1. 在 GitLab 上创建新的**私有**仓库。
    2. 不要用 README 初始化（避免合并冲突）。
    3. 复制 HTTPS 远程 URL。
    4. 添加远程仓库并推送：

    ```bash
    git branch -M main
    git remote add origin <https-url>
    git push -u origin main
    ```
  </Tab>
</Tabs>

bash git status git add . git commit -m "Update memory" git push

不要提交密钥

即使在私有仓库中，也应避免在工作区中存储密钥：

API 密钥、OAuth token、密码或私有凭证。
~/.openclaw/ 下的任何内容。
聊天或敏感附件的原始转储。

如果你必须存储敏感引用，请使用占位符，并将真实密钥保存在其他位置（密码管理器、环境变量或 ~/.openclaw/）。

建议的 .gitignore 起始内容：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

将工作区迁移到新机器

将仓库克隆到所需路径（默认 ~/.openclaw/workspace）。

在 ~/.openclaw/openclaw.json 中将 agents.defaults.workspace 设置为该路径。

运行 openclaw setup --workspace <path> 以填充任何缺失文件。

如果你需要会话，请从旧机器单独复制 ~/.openclaw/agents/<agentId>/sessions/。

高级说明

多智能体路由可以为每个智能体使用不同工作区。有关路由配置，请参阅频道路由。
如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的按会话沙箱工作区。

📄 OAuth

原文：https://docs.openclaw.ai/zh-CN/concepts/oauth

OpenClaw 支持通过 OAuth 为提供该能力的提供商使用“订阅式认证”
（尤其是 OpenAI Codex（ChatGPT OAuth））。对于 Anthropic，实际划分
现在是：

Anthropic API key：常规 Anthropic API 计费
Anthropic Claude CLI / OpenClaw 内的订阅式认证：Anthropic 员工
告诉我们这种用法已再次允许

OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具。本页说明：

对于生产环境中的 Anthropic，API key 认证是更安全的推荐路径。

OAuth 令牌交换的工作方式（PKCE）
令牌存储在哪里（以及原因）
如何处理多个账号（配置文件 + 按会话覆盖）

OpenClaw 还支持提供商插件，它们会自带 OAuth 或 API key
流程。通过以下命令运行：

openclaw models auth login --provider <id>

令牌接收端（为什么存在）

OAuth 提供商通常会在登录/刷新流程中签发一个新的刷新令牌。某些提供商（或 OAuth 客户端）可能会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。

实际症状：

你通过 OpenClaw 并且通过 Claude Code / Codex CLI 登录 → 之后其中一个会随机“退出登录”

为减少这种情况，OpenClaw 将 auth-profiles.json 视为令牌接收端：

运行时从一个位置读取凭证
我们可以保留多个配置文件，并以确定性方式路由它们
外部 CLI 复用是提供商特定的：Codex CLI 可以引导一个空的
openai-codex:default 配置文件，但一旦 OpenClaw 有了本地 OAuth 配置文件，
本地刷新令牌就是规范来源；其他集成可以保持由外部管理，并重新读取它们的 CLI 认证存储
已经知道已配置提供商集合的状态和启动路径，会将外部 CLI 发现范围限制在该集合内，
因此单一提供商设置不会探测无关的 CLI 登录存储

存储（令牌存放在哪里）

密钥存储在 agent 认证存储中：

认证配置文件（OAuth + API key + 可选的值级别引用）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
旧版兼容文件：~/.openclaw/agents/<agentId>/agent/auth.json
（发现静态 api_key 条目时会将其清除）

仅用于旧版导入的文件（仍受支持，但不是主存储）：

~/.openclaw/credentials/oauth.json（首次使用时导入到 auth-profiles.json）

以上所有内容也遵循 $OPENCLAW_STATE_DIR（状态目录覆盖）。完整参考：/gateway/configuration

有关静态密钥引用和运行时快照激活行为，请参阅 Secrets Management。

当辅助 agent 没有本地认证配置文件时，OpenClaw 会使用从默认/主 agent 存储的读取穿透继承。它不会在读取时克隆主
agent 的 auth-profiles.json。OAuth 刷新令牌尤其敏感：普通复制流程默认会跳过它们，因为某些提供商会在使用后轮换
或失效刷新令牌。当某个 agent 需要独立账号时，请为它配置单独的 OAuth 登录。

Anthropic 旧版令牌兼容性

Anthropic 的公开 Claude Code 文档说明，直接使用 Claude Code 仍属于
Claude 订阅限制范围内，并且 Anthropic 员工告诉我们，OpenClaw 风格的 Claude
CLI 用法已再次允许。因此，除非 Anthropic 发布新政策，OpenClaw 会将 Claude CLI 复用和
claude -p 用法视为该集成的受认可方式。

有关 Anthropic 当前的直接 Claude Code 计划文档，请参阅 Using Claude Code
with your Pro or Max
plan
以及 Using Claude Code with your Team or Enterprise
plan。

如果你想在 OpenClaw 中使用其他订阅式选项，请参阅 OpenAI
Codex、Qwen Cloud Coding
Plan、MiniMax Coding Plan
以及 Z.AI / GLM Coding Plan。

OpenClaw 也将 Anthropic setup-token 暴露为受支持的令牌认证路径，但现在会在可用时优先复用 Claude CLI 和 claude -p。

Anthropic Claude CLI 迁移

OpenClaw 再次支持复用 Anthropic Claude CLI。如果你已经在主机上有本地
Claude 登录，新手引导/配置可以直接复用它。

OAuth 交换（登录如何工作）

OpenClaw 的交互式登录流程在 @earendil-works/pi-ai 中实现，并接入到向导/命令中。

Anthropic setup-token

流程形态：

从 OpenClaw 启动 Anthropic setup-token 或 paste-token
OpenClaw 将生成的 Anthropic 凭证存储在认证配置文件中
模型选择保持在 anthropic/...
现有 Anthropic 认证配置文件仍可用于回滚/顺序控制

OpenAI Codex（ChatGPT OAuth）

OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。

流程形态（PKCE）：

生成 PKCE verifier/challenge + 随机 state
打开 https://auth.openai.com/oauth/authorize?...
尝试在 http://127.0.0.1:1455/auth/callback 捕获回调
如果回调无法绑定（或你在远程/无头环境中），粘贴重定向 URL/code
在 https://auth.openai.com/oauth/token 交换
从访问令牌中提取 accountId 并存储 { access, refresh, expires, accountId }

向导路径是 openclaw onboard → 认证选择 openai-codex。

刷新 + 过期

配置文件会存储 expires 时间戳。

运行时：

如果 expires 在未来 → 使用已存储的访问令牌
如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭证
如果辅助 agent 读取继承来的主 agent OAuth 配置文件，刷新会写回主 agent 存储，
而不是把刷新令牌复制到辅助 agent 存储中
例外：某些外部 CLI 凭证仍由外部管理；OpenClaw 会重新读取这些 CLI 认证存储，
而不是消耗复制的刷新令牌。Codex CLI 引导有意更窄：它会种下一个空的
openai-codex:default 配置文件，然后由 OpenClaw 拥有的刷新让本地配置文件保持为规范来源。

刷新流程是自动的；通常你不需要手动管理令牌。

多账号（配置文件）+ 路由

两种模式：

1) 首选：分离 agent

如果你希望“个人”和“工作”永不交互，请使用隔离的 agent（分离的会话 + 凭证 + 工作区）：

openclaw agents add work
openclaw agents add personal

然后按 agent 配置认证（向导），并将聊天路由到正确的 agent。

2) 高级：一个 agent 中多个配置文件

auth-profiles.json 支持为同一提供商配置多个配置文件 ID。

选择使用哪个配置文件：

通过配置排序（auth.order）全局选择
通过 /model ...@<profileId> 按会话选择

示例（会话覆盖）：

/model Opus@anthropic:work

如何查看存在哪些配置文件 ID：

openclaw channels list --json（显示 auth[]）

[OpenClaw 文档]代理--基础

📄 Gateway 网关架构

概览

组件和流程

Gateway 网关（守护进程）

客户端（Mac 应用 / CLI / Web 管理）

节点（macOS / iOS / Android / headless）

WebChat

连接生命周期（单个客户端）

线缆协议（摘要）

配对 + 本地信任

协议类型和代码生成

远程访问

运维快照

不变量

相关

📄 智能体运行时

工作区（必需）

引导文件（已注入）

内置工具

Skills

运行时边界

会话

流式传输期间 Steering

模型引用

配置（最小）

相关

📄 Agent loop

入口点

工作原理（高层）

排队 + 并发

会话 + 工作区准备

提示词组装 + 系统提示词

钩子点（你可以拦截的位置）

内部钩子（Gateway 网关钩子）

插件钩子（智能体 + Gateway 网关生命周期）

流式传输 + 部分回复

工具执行 + 消息工具

回复塑形 + 抑制

压缩 + 重试

事件流（当前）

聊天渠道处理

超时

可能提前结束的位置

相关

📄 系统提示词

结构

提示词模式

提示词快照

工作区启动注入

时间处理

Skills

文档

相关

📄 上下文

快速开始（检查上下文）

示例输出

/context list

/context detail

/context map

哪些内容会计入上下文窗口

OpenClaw 如何构建系统提示词

注入的工作区文件（项目上下文）

Skills：已注入与按需加载

工具：有两类成本

命令、指令和“内联快捷方式”

会话、压缩和裁剪（哪些内容会持久化）

/context 实际报告什么

相关

📄 Agent 工作区

默认位置

额外工作区文件夹

工作区文件映射

工作区中不包含什么

Git 备份（建议，私有）

不要提交密钥

将工作区迁移到新机器

高级说明

相关

📄 OAuth

`/context list`

`/context detail`

`/context map`

`/context` 实际报告什么