@captain-app/openclaw 2026.2.4

package/docs/zh-CN/experiments/plans/cron-add-hardening.md

@@ -0,0 +1,70 @@
+---
+last_updated: "2026-01-05"
+owner: openclaw
+status: complete
+summary: 加固 cron.add 输入处理，对齐 schema，改进 cron UI/智能体工具
+title: Cron Add 加固
+x-i18n:
+  generated_at: "2026-02-03T07:47:26Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d7e469674bd9435b846757ea0d5dc8f174eaa8533917fc013b1ef4f82859496d
+  source_path: experiments/plans/cron-add-hardening.md
+  workflow: 15
+---
+
+# Cron Add 加固 & Schema 对齐
+
+## 背景
+
+最近的 Gateway 网关日志显示重复的 `cron.add` 失败，参数无效（缺少 `sessionTarget`、`wakeMode`、`payload`，以及格式错误的 `schedule`）。这表明至少有一个客户端（可能是智能体工具调用路径）正在发送包装的或部分指定的任务负载。另外，TypeScript 中的 cron 提供商枚举、Gateway 网关 schema、CLI 标志和 UI 表单类型之间存在漂移，加上 `cron.status` 的 UI 不匹配（期望 `jobCount` 而 Gateway 网关返回 `jobs`）。
+
+## 目标
+
+- 通过规范化常见的包装负载并推断缺失的 `kind` 字段来停止 `cron.add` INVALID_REQUEST 垃圾。
+- 在 Gateway 网关 schema、cron 类型、CLI 文档和 UI 表单之间对齐 cron 提供商列表。
+- 使智能体 cron 工具 schema 明确，以便 LLM 生成正确的任务负载。
+- 修复 Control UI cron 状态任务计数显示。
+- 添加测试以覆盖规范化和工具行为。
+
+## 非目标
+
+- 更改 cron 调度语义或任务执行行为。
+- 添加新的调度类型或 cron 表达式解析。
+- 除了必要的字段修复外，不大改 cron 的 UI/UX。
+
+## 发现（当前差距）
+
+- Gateway 网关中的 `CronPayloadSchema` 排除了 `signal` + `imessage`，而 TS 类型包含它们。
+- Control UI CronStatus 期望 `jobCount`，但 Gateway 网关返回 `jobs`。
+- 智能体 cron 工具 schema 允许任意 `job` 对象，导致格式错误的输入。
+- Gateway 网关严格验证 `cron.add` 而不进行规范化，因此包装的负载会失败。
+
+## 变更内容
+
+- `cron.add` 和 `cron.update` 现在规范化常见的包装形式并推断缺失的 `kind` 字段。
+- 智能体 cron 工具 schema 与 Gateway 网关 schema 匹配，减少无效负载。
+- 提供商枚举在 Gateway 网关、CLI、UI 和 macOS 选择器之间对齐。
+- Control UI 使用 Gateway 网关的 `jobs` 计数字段显示状态。
+
+## 当前行为
+
+- **规范化：**包装的 `data`/`job` 负载被解包；`schedule.kind` 和 `payload.kind` 在安全时被推断。
+- **默认值：**当缺失时，为 `wakeMode` 和 `sessionTarget` 应用安全默认值。
+- **提供商：**Discord/Slack/Signal/iMessage 现在在 CLI/UI 中一致显示。
+
+参见 [Cron 任务](/automation/cron-jobs) 了解规范化的形式和示例。
+
+## 验证
+
+- 观察 Gateway 网关日志中 `cron.add` INVALID_REQUEST 错误是否减少。
+- 确认 Control UI cron 状态在刷新后显示任务计数。
+
+## 可选后续工作
+
+- 手动 Control UI 冒烟测试：为每个提供商添加一个 cron 任务 + 验证状态任务计数。
+
+## 开放问题
+
+- `cron.add` 是否应该接受来自客户端的显式 `state`（当前被 schema 禁止）？
+- 我们是否应该允许 `webchat` 作为显式投递提供商（当前在投递解析中被过滤）？

package/docs/zh-CN/experiments/plans/group-policy-hardening.md

@@ -0,0 +1,45 @@
+---
+read_when:
+  - 查看历史 Telegram 允许列表更改
+summary: Telegram 允许列表加固：前缀 + 空白规范化
+title: Telegram 允许列表加固
+x-i18n:
+  generated_at: "2026-02-03T07:47:16Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a2eca5fcc85376948cfe1b6044f1a8bc69c7f0eb94d1ceafedc1e507ba544162
+  source_path: experiments/plans/group-policy-hardening.md
+  workflow: 15
+---
+
+# Telegram 允许列表加固
+
+**日期**：2026-01-05  
+**状态**：已完成  
+**PR**：#216
+
+## 摘要
+
+Telegram 允许列表现在不区分大小写地接受 `telegram:` 和 `tg:` 前缀，并容忍意外的空白。这使入站允许列表检查与出站发送规范化保持一致。
+
+## 更改内容
+
+- 前缀 `telegram:` 和 `tg:` 被同等对待（不区分大小写）。
+- 允许列表条目会被修剪；空条目会被忽略。
+
+## 示例
+
+以下所有形式都被接受为同一 ID：
+
+- `telegram:123456`
+- `TG:123456`
+- `tg:123456`
+
+## 为什么重要
+
+从日志或聊天 ID 复制/粘贴通常会包含前缀和空白。规范化可避免在决定是否在私信或群组中响应时出现误判。
+
+## 相关文档
+
+- [群聊](/concepts/groups)
+- [Telegram 提供商](/channels/telegram)

package/docs/zh-CN/experiments/plans/openresponses-gateway.md

@@ -0,0 +1,121 @@
+---
+last_updated: "2026-01-19"
+owner: openclaw
+status: draft
+summary: 计划：添加 OpenResponses /v1/responses 端点并干净地弃用 chat completions
+title: OpenResponses Gateway 网关计划
+x-i18n:
+  generated_at: "2026-02-03T07:47:33Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 71a22c48397507d1648b40766a3153e420c54f2a2d5186d07e51eb3d12e4636a
+  source_path: experiments/plans/openresponses-gateway.md
+  workflow: 15
+---
+
+# OpenResponses Gateway 网关集成计划
+
+## 背景
+
+OpenClaw Gateway 网关目前在 `/v1/chat/completions` 暴露了一个最小的 OpenAI 兼容 Chat Completions 端点（参见 [OpenAI Chat Completions](/gateway/openai-http-api)）。
+
+Open Responses 是基于 OpenAI Responses API 的开放推理标准。它专为智能体工作流设计，使用基于项目的输入加语义流式事件。OpenResponses 规范定义的是 `/v1/responses`，而不是 `/v1/chat/completions`。
+
+## 目标
+
+- 添加一个遵循 OpenResponses 语义的 `/v1/responses` 端点。
+- 保留 Chat Completions 作为兼容层，易于禁用并最终移除。
+- 使用隔离的、可复用的 schema 标准化验证和解析。
+
+## 非目标
+
+- 第一阶段完全实现 OpenResponses 功能（图片、文件、托管工具）。
+- 替换内部智能体执行逻辑或工具编排。
+- 在第一阶段更改现有的 `/v1/chat/completions` 行为。
+
+## 研究摘要
+
+来源：OpenResponses OpenAPI、OpenResponses 规范网站和 Hugging Face 博客文章。
+
+提取的关键点：
+
+- `POST /v1/responses` 接受 `CreateResponseBody` 字段，如 `model`、`input`（字符串或 `ItemParam[]`）、`instructions`、`tools`、`tool_choice`、`stream`、`max_output_tokens` 和 `max_tool_calls`。
+- `ItemParam` 是以下类型的可区分联合：
+  - 具有角色 `system`、`developer`、`user`、`assistant` 的 `message` 项
+  - `function_call` 和 `function_call_output`
+  - `reasoning`
+  - `item_reference`
+- 成功响应返回带有 `object: "response"`、`status` 和 `output` 项的 `ResponseResource`。
+- 流式传输使用语义事件，如：
+  - `response.created`、`response.in_progress`、`response.completed`、`response.failed`
+  - `response.output_item.added`、`response.output_item.done`
+  - `response.content_part.added`、`response.content_part.done`
+  - `response.output_text.delta`、`response.output_text.done`
+- 规范要求：
+  - `Content-Type: text/event-stream`
+  - `event:` 必须匹配 JSON `type` 字段
+  - 终止事件必须是字面量 `[DONE]`
+- Reasoning 项可能暴露 `content`、`encrypted_content` 和 `summary`。
+- HF 示例在请求中包含 `OpenResponses-Version: latest`（可选头部）。
+
+## 提议的架构
+
+- 添加 `src/gateway/open-responses.schema.ts`，仅包含 Zod schema（无 gateway 导入）。
+- 添加 `src/gateway/openresponses-http.ts`（或 `open-responses-http.ts`）用于 `/v1/responses`。
+- 保持 `src/gateway/openai-http.ts` 不变，作为遗留兼容适配器。
+- 添加配置 `gateway.http.endpoints.responses.enabled`（默认 `false`）。
+- 保持 `gateway.http.endpoints.chatCompletions.enabled` 独立；允许两个端点分别切换。
+- 当 Chat Completions 启用时发出启动警告，以表明其遗留状态。
+
+## Chat Completions 弃用路径
+
+- 保持严格的模块边界：responses 和 chat completions 之间不共享 schema 类型。
+- 通过配置使 Chat Completions 成为可选，这样无需代码更改即可禁用。
+- 一旦 `/v1/responses` 稳定，更新文档将 Chat Completions 标记为遗留。
+- 可选的未来步骤：将 Chat Completions 请求映射到 Responses 处理器，以便更简单地移除。
+
+## 第一阶段支持子集
+
+- 接受 `input` 为字符串或带有消息角色和 `function_call_output` 的 `ItemParam[]`。
+- 将 system 和 developer 消息提取到 `extraSystemPrompt` 中。
+- 使用最近的 `user` 或 `function_call_output` 作为智能体运行的当前消息。
+- 对不支持的内容部分（图片/文件）返回 `invalid_request_error` 拒绝。
+- 返回带有 `output_text` 内容的单个助手消息。
+- 返回带有零值的 `usage`，直到 token 计数接入。
+
+## 验证策略（无 SDK）
+
+- 为以下支持子集实现 Zod schema：
+  - `CreateResponseBody`
+  - `ItemParam` + 消息内容部分联合
+  - `ResponseResource`
+  - Gateway 网关使用的流式事件形状
+- 将 schema 保存在单个隔离模块中，以避免漂移并允许未来代码生成。
+
+## 流式实现（第一阶段）
+
+- 带有 `event:` 和 `data:` 的 SSE 行。
+- 所需序列（最小可行）：
+  - `response.created`
+  - `response.output_item.added`
+  - `response.content_part.added`
+  - `response.output_text.delta`（根据需要重复）
+  - `response.output_text.done`
+  - `response.content_part.done`
+  - `response.completed`
+  - `[DONE]`
+
+## 测试和验证计划
+
+- 为 `/v1/responses` 添加端到端覆盖：
+  - 需要认证
+  - 非流式响应形状
+  - 流式事件顺序和 `[DONE]`
+  - 使用头部和 `user` 的会话路由
+- 保持 `src/gateway/openai-http.e2e.test.ts` 不变。
+- 手动：用 `stream: true` curl `/v1/responses` 并验证事件顺序和终止 `[DONE]`。
+
+## 文档更新（后续）
+
+- 为 `/v1/responses` 使用和示例添加新文档页面。
+- 更新 `/gateway/openai-http-api`，添加遗留说明和指向 `/v1/responses` 的指针。

package/docs/zh-CN/experiments/proposals/model-config.md

@@ -0,0 +1,42 @@
+---
+read_when:
+  - 探索未来模型选择和认证配置文件的方案
+summary: 探索：模型配置、认证配置文件和回退行为
+title: 模型配置探索
+x-i18n:
+  generated_at: "2026-02-01T20:25:05Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 48623233d80f874c0ae853b51f888599cf8b50ae6fbfe47f6d7b0216bae9500b
+  source_path: experiments/proposals/model-config.md
+  workflow: 14
+---
+
+# 模型配置（探索）
+
+本文档记录了未来模型配置的**构想**。这不是正式的发布规范。如需了解当前行为，请参阅：
+
+- [模型](/concepts/models)
+- [模型故障转移](/concepts/model-failover)
+- [OAuth + 配置文件](/concepts/oauth)
+
+## 动机
+
+运营者希望：
+
+- 每个提供商支持多个认证配置文件（个人 vs 工作）。
+- 简单的 `/model` 选择，并具有可预测的回退行为。
+- 文本模型与图像模型之间有清晰的分离。
+
+## 可能的方向（高层级）
+
+- 保持模型选择简洁：`provider/model` 加可选别名。
+- 允许提供商拥有多个认证配置文件，并指定明确的顺序。
+- 使用全局回退列表，使所有会话以一致的方式进行故障转移。
+- 仅在明确配置时才覆盖图像路由。
+
+## 待解决的问题
+
+- 配置文件轮换应该按提供商还是按模型进行？
+- UI 应如何为会话展示配置文件选择？
+- 从旧版配置键迁移的最安全路径是什么？

package/docs/zh-CN/experiments/research/memory.md

@@ -0,0 +1,235 @@
+---
+read_when:
+  - 设计超越每日 Markdown 日志的工作区记忆（~/.openclaw/workspace）
+  - Deciding: standalone CLI vs deep OpenClaw integration
+  - 添加离线回忆 + 反思（retain/recall/reflect）
+summary: 研究笔记：Clawd 工作区的离线记忆系统（Markdown 作为数据源 + 派生索引）
+title: 工作区记忆研究
+x-i18n:
+  generated_at: "2026-02-03T10:06:14Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1753c8ee6284999fab4a94ff5fae7421c85233699c9d3088453d0c2133ac0feb
+  source_path: experiments/research/memory.md
+  workflow: 15
+---
+
+# 工作区记忆 v2（离线）：研究笔记
+
+目标：Clawd 风格的工作区（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`），其中"记忆"以每天一个 Markdown 文件（`memory/YYYY-MM-DD.md`）加上一小组稳定文件（例如 `memory.md`、`SOUL.md`）的形式存储。
+
+本文档提出一种**离线优先**的记忆架构，保持 Markdown 作为规范的、可审查的数据源，但通过派生索引添加**结构化回忆**（搜索、实体摘要、置信度更新）。
+
+## 为什么要改变？
+
+当前设置（每天一个文件）非常适合：
+
+- "仅追加"式日志记录
+- 人工编辑
+- git 支持的持久性 + 可审计性
+- 低摩擦捕获（"直接写下来"）
+
+但它在以下方面较弱：
+
+- 高召回率检索（"我们对 X 做了什么决定？"、"上次我们尝试 Y 时？"）
+- 以实体为中心的答案（"告诉我关于 Alice / The Castle / warelay 的信息"）而无需重读多个文件
+- 观点/偏好稳定性（以及变化时的证据）
+- 时间约束（"2025 年 11 月期间什么是真实的？"）和冲突解决
+
+## 设计目标
+
+- **离线**：无需网络即可工作；可在笔记本电脑/Castle 上运行；无云依赖。
+- **可解释**：检索的项目应该可归因（文件 + 位置）并与推理分离。
+- **低仪式感**：每日日志保持 Markdown，无需繁重的 schema 工作。
+- **增量式**：v1 仅使用 FTS 就很有用；语义/向量和图是可选升级。
+- **对智能体友好**：使"在 token 预算内回忆"变得简单（返回小型事实包）。
+
+## 北极星模型（Hindsight × Letta）
+
+需要融合两个部分：
+
+1. **Letta/MemGPT 风格的控制循环**
+
+- 保持一个小的"核心"始终在上下文中（角色 + 关键用户事实）
+- 其他所有内容都在上下文之外，通过工具检索
+- 记忆写入是显式的工具调用（append/replace/insert），持久化后在下一轮重新注入
+
+2. **Hindsight 风格的记忆基底**
+
+- 分离观察到的、相信的和总结的内容
+- 支持 retain/recall/reflect
+- 带有置信度的观点可以随证据演变
+- 实体感知检索 + 时间查询（即使没有完整的知识图谱）
+
+## 提议的架构（Markdown 数据源 + 派生索引）
+
+### 规范存储（git 友好）
+
+保持 `~/.openclaw/workspace` 作为规范的人类可读记忆。
+
+建议的工作区布局：
+
+```
+~/.openclaw/workspace/
+  memory.md                    # 小型：持久事实 + 偏好（类似核心）
+  memory/
+    YYYY-MM-DD.md              # 每日日志（追加；叙事）
+  bank/                        # "类型化"记忆页面（稳定、可审查）
+    world.md                   # 关于世界的客观事实
+    experience.md              # 智能体做了什么（第一人称）
+    opinions.md                # 主观偏好/判断 + 置信度 + 证据指针
+    entities/
+      Peter.md
+      The-Castle.md
+      warelay.md
+      ...
+```
+
+注意：
+
+- **每日日志保持为每日日志**。无需将其转换为 JSON。
+- `bank/` 文件是**经过整理的**，由反思任务生成，仍可手动编辑。
+- `memory.md` 保持"小型 + 类似核心"：你希望 Clawd 每次会话都能看到的内容。
+
+### 派生存储（机器回忆）
+
+在工作区下添加派生索引（不一定需要 git 跟踪）：
+
+```
+~/.openclaw/workspace/.memory/index.sqlite
+```
+
+后端支持：
+
+- 用于事实 + 实体链接 + 观点元数据的 SQLite schema
+- SQLite **FTS5** 用于词法回忆（快速、小巧、离线）
+- 可选的嵌入表用于语义回忆（仍然离线）
+
+索引始终**可从 Markdown 重建**。
+
+## Retain / Recall / Reflect（操作循环）
+
+### Retain：将每日日志规范化为"事实"
+
+Hindsight 在这里重要的关键洞察：存储**叙事性、自包含的事实**，而不是微小的片段。
+
+`memory/YYYY-MM-DD.md` 的实用规则：
+
+- 在一天结束时（或期间），添加一个 `## Retain` 部分，包含 2-5 个要点：
+  - 叙事性（保留跨轮上下文）
+  - 自包含（独立时也有意义）
+  - 标记类型 + 实体提及
+
+示例：
+
+```
+## Retain
+- W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy's birthday.
+- B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
+- O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes into files.
+```
+
+最小化解析：
+
+- 类型前缀：`W`（世界）、`B`（经历/传记）、`O`（观点）、`S`（观察/摘要；通常是生成的）
+- 实体：`@Peter`、`@warelay` 等（slug 映射到 `bank/entities/*.md`）
+- 观点置信度：`O(c=0.0..1.0)` 可选
+
+如果你不想让作者考虑这些：反思任务可以从日志的其余部分推断这些要点，但有一个显式的 `## Retain` 部分是最简单的"质量杠杆"。
+
+### Recall：对派生索引的查询
+
+Recall 应支持：
+
+- **词法**："查找精确的术语/名称/命令"（FTS5）
+- **实体**："告诉我关于 X 的信息"（实体页面 + 实体链接的事实）
+- **时间**："11 月 27 日前后发生了什么"/"自上周以来"
+- **观点**："Peter 偏好什么？"（带置信度 + 证据）
+
+返回格式应对智能体友好并引用来源：
+
+- `kind`（`world|experience|opinion|observation`）
+- `timestamp`（来源日期，或如果存在则提取的时间范围）
+- `entities`（`["Peter","warelay"]`）
+- `content`（叙事性事实）
+- `source`（`memory/2025-11-27.md#L12` 等）
+
+### Reflect：生成稳定页面 + 更新信念
+
+反思是一个定时任务（每日或心跳 `ultrathink`），它：
+
+- 根据最近的事实更新 `bank/entities/*.md`（实体摘要）
+- 根据强化/矛盾更新 `bank/opinions.md` 置信度
+- 可选地提议对 `memory.md`（"类似核心"的持久事实）的编辑
+
+观点演变（简单、可解释）：
+
+- 每个观点有：
+  - 陈述
+  - 置信度 `c ∈ [0,1]`
+  - last_updated
+  - 证据链接（支持 + 矛盾的事实 ID）
+- 当新事实到达时：
+  - 通过实体重叠 + 相似性找到候选观点（先 FTS，后嵌入）
+  - 通过小幅增量更新置信度；大幅跳跃需要强矛盾 + 重复证据
+
+## CLI 集成：独立 vs 深度集成
+
+建议：**深度集成到 OpenClaw**，但保持可分离的核心库。
+
+### 为什么要集成到 OpenClaw？
+
+- OpenClaw 已经知道：
+  - 工作区路径（`agents.defaults.workspace`）
+  - 会话模型 + 心跳
+  - 日志记录 + 故障排除模式
+- 你希望智能体自己调用工具：
+  - `openclaw memory recall "…" --k 25 --since 30d`
+  - `openclaw memory reflect --since 7d`
+
+### 为什么仍要分离库？
+
+- 保持记忆逻辑可测试，无需 Gateway 网关/运行时
+- 可从其他上下文重用（本地脚本、未来的桌面应用等）
+
+形态：
+记忆工具预计是一个小型 CLI + 库层，但这仅是探索性的。
+
+## "S-Collide" / SuCo：何时使用（研究）
+
+如果"S-Collide"指的是 **SuCo（Subspace Collision）**：这是一种 ANN 检索方法，通过在子空间中使用学习/结构化碰撞来实现强召回/延迟权衡（论文：arXiv 2411.14754，2024）。
+
+对于 `~/.openclaw/workspace` 的务实观点：
+
+- **不要从** SuCo 开始。
+- 从 SQLite FTS +（可选的）简单嵌入开始；你会立即获得大部分 UX 收益。
+- 仅在以下情况下考虑 SuCo/HNSW/ScaNN 级别的解决方案：
+  - 语料库很大（数万/数十万个块）
+  - 暴力嵌入搜索变得太慢
+  - 召回质量明显受到词法搜索的瓶颈限制
+
+离线友好的替代方案（按复杂性递增）：
+
+- SQLite FTS5 + 元数据过滤（零 ML）
+- 嵌入 + 暴力搜索（如果块数量低，效果出奇地好）
+- HNSW 索引（常见、稳健；需要库绑定）
+- SuCo（研究级；如果有可嵌入的可靠实现则很有吸引力）
+
+开放问题：
+
+- 对于你的机器（笔记本 + 台式机）上的"个人助理记忆"，**最佳**的离线嵌入模型是什么？
+  - 如果你已经有 Ollama：使用本地模型嵌入；否则在工具链中附带一个小型嵌入模型。
+
+## 最小可用试点
+
+如果你想要一个最小但仍有用的版本：
+
+- 添加 `bank/` 实体页面和每日日志中的 `## Retain` 部分。
+- 使用 SQLite FTS 进行带引用的回忆（路径 + 行号）。
+- 仅在召回质量或规模需要时添加嵌入。
+
+## 参考资料
+
+- Letta / MemGPT 概念："核心记忆块" + "档案记忆" + 工具驱动的自编辑记忆。
+- Hindsight 技术报告："retain / recall / reflect"，四网络记忆，叙事性事实提取，观点置信度演变。
+- SuCo：arXiv 2411.14754（2024）："Subspace Collision"近似最近邻检索。

package/docs/zh-CN/gateway/authentication.md

@@ -0,0 +1,142 @@
+---
+read_when:
+  - 调试模型认证或 OAuth 过期
+  - 记录认证或凭证存储
+summary: 模型认证：OAuth、API 密钥和 setup-token
+title: 认证
+x-i18n:
+  generated_at: "2026-02-03T07:47:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 66fa2c64ff374c9cfcdb4e7a951b0d164d512295e65513eb682f12191b75e557
+  source_path: gateway/authentication.md
+  workflow: 15
+---
+
+# 认证
+
+OpenClaw 支持模型提供商的 OAuth 和 API 密钥。对于 Anthropic 账户，我们推荐使用 **API 密钥**。对于 Claude 订阅访问，使用 `claude setup-token` 创建的长期令牌。
+
+参阅 [/concepts/oauth](/concepts/oauth) 了解完整的 OAuth 流程和存储布局。
+
+## 推荐的 Anthropic 设置（API 密钥）
+
+如果你直接使用 Anthropic，请使用 API 密钥。
+
+1. 在 Anthropic 控制台创建 API 密钥。
+2. 将其放在 **Gateway 网关主机**（运行 `openclaw gateway` 的机器）上。
+
+```bash
+export ANTHROPIC_API_KEY="..."
+openclaw models status
+```
+
+3. 如果 Gateway 网关在 systemd/launchd 下运行，最好将密钥放在 `~/.openclaw/.env` 中以便守护进程可以读取：
+
+```bash
+cat >> ~/.openclaw/.env <<'EOF'
+ANTHROPIC_API_KEY=...
+EOF
+```
+
+然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查：
+
+```bash
+openclaw models status
+openclaw doctor
+```
+
+如果你不想自己管理环境变量，新手引导向导可以为守护进程使用存储 API 密钥：`openclaw onboard`。
+
+参阅[帮助](/help)了解环境变量继承的详情（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）。
+
+## Anthropic：setup-token（订阅认证）
+
+对于 Anthropic，推荐的路径是 **API 密钥**。如果你使用 Claude 订阅，也支持 setup-token 流程。在 **Gateway 网关主机**上运行：
+
+```bash
+claude setup-token
+```
+
+然后将其粘贴到 OpenClaw：
+
+```bash
+openclaw models auth setup-token --provider anthropic
+```
+
+如果令牌是在另一台机器上创建的，手动粘贴：
+
+```bash
+openclaw models auth paste-token --provider anthropic
+```
+
+如果你看到类似这样的 Anthropic 错误：
+
+```
+This credential is only authorized for use with Claude Code and cannot be used for other API requests.
+```
+
+…请改用 Anthropic API 密钥。
+
+手动令牌输入（任何提供商；写入 `auth-profiles.json` + 更新配置）：
+
+```bash
+openclaw models auth paste-token --provider anthropic
+openclaw models auth paste-token --provider openrouter
+```
+
+自动化友好检查（过期/缺失时退出 `1`，即将过期时退出 `2`）：
+
+```bash
+openclaw models status --check
+```
+
+可选的运维脚本（systemd/Termux）在此处记录：[/automation/auth-monitoring](/automation/auth-monitoring)
+
+> `claude setup-token` 需要交互式 TTY。
+
+## 检查模型认证状态
+
+```bash
+openclaw models status
+openclaw doctor
+```
+
+## 控制使用哪个凭证
+
+### 每会话（聊天命令）
+
+使用 `/model <alias-or-id>@<profileId>` 为当前会话固定特定的提供商凭证（示例配置文件 ID：`anthropic:default`、`anthropic:work`）。
+
+使用 `/model`（或 `/model list`）获取紧凑的选择器；使用 `/model status` 获取完整视图（候选项 + 下一个认证配置文件，以及配置时的提供商端点详情）。
+
+### 每智能体（CLI 覆盖）
+
+为智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
+
+```bash
+openclaw models auth order get --provider anthropic
+openclaw models auth order set --provider anthropic anthropic:default
+openclaw models auth order clear --provider anthropic
+```
+
+使用 `--agent <id>` 指定特定智能体；省略它则使用配置的默认智能体。
+
+## 故障排除
+
+### "No credentials found"
+
+如果 Anthropic 令牌配置文件缺失，在 **Gateway 网关主机**上运行 `claude setup-token`，然后重新检查：
+
+```bash
+openclaw models status
+```
+
+### 令牌即将过期/已过期
+
+运行 `openclaw models status` 确认哪个配置文件即将过期。如果配置文件缺失，重新运行 `claude setup-token` 并再次粘贴令牌。
+
+## 要求
+
+- Claude Max 或 Pro 订阅（用于 `claude setup-token`）
+- 已安装 Claude Code CLI（`claude` 命令可用）