@gguf/claw 2026.2.1 → 2026.2.3

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-01T20:25:08Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d7e469674bd9435b846757ea0d5dc8f174eaa8533917fc013b1ef4f82859496d
+  source_path: experiments/plans/cron-add-hardening.md
+  workflow: 14
+---
+
+# Cron Add 加固与 Schema 对齐
+
+## 背景
+
+近期 Gateway网关日志显示 `cron.add` 反复因无效参数（缺少 `sessionTarget`、`wakeMode`、`payload` 以及格式错误的 `schedule`）而失败。这表明至少有一个客户端（可能是智能体工具调用路径）正在发送包装过的或部分指定的任务载荷。此外，TypeScript、Gateway网关 schema、CLI 标志和 UI 表单类型之间的 cron 提供商枚举存在偏差，同时 `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-01T20:25:02Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a2eca5fcc85376948cfe1b6044f1a8bc69c7f0eb94d1ceafedc1e507ba544162
+  source_path: experiments/plans/group-policy-hardening.md
+  workflow: 14
+---
+
+# 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: 草稿
+summary: 计划：添加 OpenResponses /v1/responses 端点并平稳废弃 Chat Completions
+title: OpenResponses Gateway网关计划
+x-i18n:
+  generated_at: "2026-02-01T20:25:20Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 71a22c48397507d1648b40766a3153e420c54f2a2d5186d07e51eb3d12e4636a
+  source_path: experiments/plans/openresponses-gateway.md
+  workflow: 14
+---
+
+# 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`
+- 成功响应返回一个 `ResponseResource`，包含 `object: "response"`、`status` 和 `output` 项。
+- 流式传输使用语义化事件，例如：
+  - `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]`
+- 推理项可以暴露 `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`，在接入令牌计量之前使用零值。
+
+## 验证策略（无 SDK）
+
+- 为以下支持的子集实现 Zod schema：
+  - `CreateResponseBody`
+  - `ItemParam` + 消息内容部分联合类型
+  - `ResponseResource`
+  - Gateway网关使用的流式事件结构
+- 将 schema 保存在单个隔离模块中，以避免漂移并支持未来的代码生成。
+
+## 流式实现（第一阶段）
+
+- SSE 行同时包含 `event:` 和 `data:`。
+- 必需的序列（最小可行方案）：
+  - `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` 不变。
+- 手动测试：使用 curl 请求 `/v1/responses`，设置 `stream: true`，验证事件顺序和终止 `[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）
+  - 决策：独立 CLI 还是深度集成 OpenClaw
+  - 添加离线召回 + 反思（retain/recall/reflect）
+summary: 研究笔记：Clawd 工作区离线记忆系统（Markdown 作为事实来源 + 派生索引）
+title: 工作区记忆研究
+x-i18n:
+  generated_at: "2026-02-01T20:25:43Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1753c8ee6284999fab4a94ff5fae7421c85233699c9d3088453d0c2133ac0feb
+  source_path: experiments/research/memory.md
+  workflow: 14
+---
+
+# 工作区记忆 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 仅用全文搜索即可发挥作用；语义/向量和图谱是可选升级。
+- **智能体友好**：使"在 token 预算内召回"变得简单（返回小型事实包）。
+
+## 北极星模型（Hindsight × Letta）
+
+需要融合两部分：
+
+1. **Letta/MemGPT 风格的控制循环**
+
+- 保持一个小型"核心"始终在上下文中（角色设定 + 关键用户事实）
+- 其他所有内容都在上下文之外，通过工具检索
+- 记忆写入是显式的工具调用（追加/替换/插入），持久化后在下一轮重新注入
+
+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：在派生索引上查询
+
+召回应支持：
+
+- **词法**："查找精确术语/名称/命令"（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]`
+  - 最后更新时间
+  - 证据链接（支持 + 矛盾的事实 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）**：这是一种近似最近邻检索方法，通过在子空间中使用学习/结构化碰撞来实现强召回率/延迟权衡（论文：arXiv 2411.14754, 2024）。
+
+对于 `~/.openclaw/workspace` 的务实建议：
+
+- **不要从** SuCo 开始。
+- 从 SQLite FTS +（可选的）简单嵌入开始；你将立即获得大部分用户体验收益。
+- 仅在以下情况时考虑 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-01T20:25:19Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 66fa2c64ff374c9cfcdb4e7a951b0d164d512295e65513eb682f12191b75e557
+  source_path: gateway/authentication.md
+  workflow: 14
+---
+
+# 认证
+
+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` 命令可用）