@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/concepts/usage-tracking.md

@@ -0,0 +1,42 @@
+---
+read_when:
+  - 你正在对接提供商使用量/配额界面
+  - 你需要解释使用量跟踪行为或认证要求
+summary: 使用量跟踪界面及凭据要求
+title: 使用量跟踪
+x-i18n:
+  generated_at: "2026-02-01T20:24:46Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6f6ed2a70329b2a6206c327aa749a84fbfe979762caca5f0e7fb556f91631cbb
+  source_path: concepts/usage-tracking.md
+  workflow: 14
+---
+
+# 使用量跟踪
+
+## 功能简介
+
+- 直接从提供商的使用量端点拉取使用量/配额数据。
+- 不提供估算费用；仅展示提供商报告的时间窗口数据。
+
+## 展示位置
+
+- 聊天中的 `/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 凭据，使用量信息将被隐藏。

package/docs/zh-CN/date-time.md

@@ -0,0 +1,129 @@
+---
+read_when:
+  - 你正在更改向模型或用户展示时间戳的方式
+  - 你正在调试消息或系统提示词输出中的时间格式问题
+summary: 信封、提示词、工具和连接器中的日期与时间处理
+title: 日期与时间
+x-i18n:
+  generated_at: "2026-02-01T20:24:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 753af5946a006215d6af2467fa478f3abb42b1dff027cf85d5dc4c7ba4b58d39
+  source_path: date-time.md
+  workflow: 14
+---
+
+# 日期与时间
+
+OpenClaw 默认使用**主机本地时间作为传输时间戳**，并且**仅在系统提示词中使用用户时区**。
+提供商时间戳会被保留，因此工具保持其原生语义（当前时间可通过 `session_status` 获取）。
+
+## 消息信封（默认为本地时间）
+
+入站消息会附带一个时间戳（分钟精度）：
+
+```
+[Provider ... 2026-01-05 16:26 PST] message text
+```
+
+此信封时间戳**默认为主机本地时间**，与提供商时区无关。
+
+你可以覆盖此行为：
+
+```json5
+{
+  agents: {
+    defaults: {
+      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区
+      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` 工具；状态卡中包含时间戳行。
+
+## 系统事件行（默认为本地时间）
+
+插入到智能体上下文中的排队系统事件会带有时间戳前缀，使用与消息信封相同的时区选择（默认：主机本地时间）。
+
+```
+System: [2026-01-12 12:19:17 PST] Model switched.
+```
+
+### 配置用户时区和格式
+
+```json5
+{
+  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 时间戳
+
+如果需要本地时间，请使用已知时区在下游进行转换。
+
+## 相关文档
+
+- [系统提示词](/concepts/system-prompt)
+- [时区](/concepts/timezone)
+- [消息](/concepts/messages)

package/docs/zh-CN/debug/node-issue.md

@@ -0,0 +1,90 @@
+---
+read_when:
+  - 调试仅限 Node 的开发脚本或 watch 模式失败
+  - 排查 OpenClaw 中 tsx/esbuild 加载器崩溃问题
+summary: Node + tsx "__name is not a function" 崩溃说明及解决方法
+title: Node + tsx 崩溃
+x-i18n:
+  generated_at: "2026-02-01T20:24:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f9e9bd2281508337a0696126b0db2d47a2d0f56de7a11872fbc0ac4689f9ad41
+  source_path: debug/node-issue.md
+  workflow: 14
+---
+
+# Node + tsx "\_\_name is not a function" 崩溃
+
+## 概述
+
+通过 Node 使用 `tsx` 运行 OpenClaw 时，启动阶段报错：
+
+```
+[openclaw] Failed to start CLI: TypeError: __name is not a function
+    at createSubsystemLogger (.../src/logging/subsystem.ts:203:25)
+    at .../src/agents/auth-profiles/constants.ts:25:20
+```
+
+此问题在开发脚本从 Bun 切换到 `tsx` 后出现（提交 `2871657e`，2026-01-06）。相同的运行路径在 Bun 下正常工作。
+
+## 环境
+
+- Node: v25.x（在 v25.3.0 上观察到）
+- tsx: 4.21.0
+- 操作系统: macOS（其他运行 Node 25 的平台也可能复现）
+
+## 复现步骤（仅 Node）
+
+```bash
+# 在仓库根目录
+node --version
+pnpm install
+node --import tsx src/entry.ts status
+```
+
+## 仓库内最小复现
+
+```bash
+node --import tsx scripts/repro/tsx-name-repro.ts
+```
+
+## Node 版本检查
+
+- Node 25.3.0：失败
+- Node 22.22.0（Homebrew `node@22`）：失败
+- Node 24：尚未安装，需要验证
+
+## 说明 / 假设
+
+- `tsx` 使用 esbuild 转换 TS/ESM。esbuild 的 `keepNames` 会生成一个 `__name` 辅助函数，并用 `__name(...)` 包裹函数定义。
+- 崩溃表明 `__name` 存在但在运行时不是函数，这意味着在 Node 25 的加载器路径中该辅助函数缺失或被覆盖。
+- 其他 esbuild 使用者也报告过类似的 `__name` 辅助函数缺失或被重写的问题。
+
+## 回归历史
+
+- `2871657e`（2026-01-06）：脚本从 Bun 改为 tsx，使 Bun 成为可选项。
+- 在此之前（Bun 路径），`openclaw status` 和 `gateway:watch` 均正常工作。
+
+## 解决方法
+
+- 开发脚本使用 Bun（当前临时回退方案）。
+- 使用 Node + tsc watch，然后运行编译产物：
+  ```bash
+  pnpm exec tsc --watch --preserveWatchOutput
+  node --watch openclaw.mjs status
+  ```
+- 已在本地确认：`pnpm exec tsc -p tsconfig.json` + `node openclaw.mjs status` 在 Node 25 上可正常运行。
+- 如果可能，在 TS 加载器中禁用 esbuild 的 keepNames（防止插入 `__name` 辅助函数）；tsx 目前不提供此配置项。
+- 在 Node LTS（22/24）上测试 `tsx`，确认该问题是否为 Node 25 特有。
+
+## 参考资料
+
+- https://opennext.js.org/cloudflare/howtos/keep_names
+- https://esbuild.github.io/api/#keep-names
+- https://github.com/evanw/esbuild/issues/1031
+
+## 后续步骤
+
+- 在 Node 22/24 上复现，确认是否为 Node 25 回归问题。
+- 测试 `tsx` nightly 版本，或在存在已知回归时固定到早期版本。
+- 如果在 Node LTS 上也能复现，则向上游提交包含 `__name` 堆栈跟踪的最小复现。

package/docs/zh-CN/debugging.md

@@ -0,0 +1,160 @@
+---
+read_when:
+  - 需要检查原始模型输出中的推理泄漏
+  - 希望在迭代开发时以监视模式运行 Gateway网关
+  - 需要可重复的调试工作流
+summary: 调试工具：监视模式、原始模型流和推理泄漏追踪
+title: 调试
+x-i18n:
+  generated_at: "2026-02-01T20:24:57Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 504c824bff4790006c8b73600daca66b919e049178e9711e6e65b6254731911a
+  source_path: debugging.md
+  workflow: 14
+---
+
+# 调试
+
+本页介绍流式输出的调试辅助工具，尤其适用于提供商将推理内容混入正常文本的情况。
+
+## 运行时调试覆盖
+
+在聊天中使用 `/debug` 设置**仅运行时**的配置覆盖（仅内存，不写入磁盘）。
+`/debug` 默认禁用；通过 `commands.debug: true` 启用。
+当你需要切换一些不常用的设置而又不想编辑 `openclaw.json` 时，这非常方便。
+
+示例：
+
+```
+/debug show
+/debug set messages.responsePrefix="[openclaw]"
+/debug unset messages.responsePrefix
+/debug reset
+```
+
+`/debug reset` 会清除所有覆盖项，恢复为磁盘上的配置。
+
+## Gateway网关监视模式
+
+要快速迭代，可在文件监视器下运行 Gateway网关：
+
+```bash
+pnpm gateway:watch --force
+```
+
+对应命令为：
+
+```bash
+tsx watch src/entry.ts gateway --force
+```
+
+在 `gateway:watch` 后添加任何 Gateway网关 CLI 标志，它们会在每次重启时被透传。
+
+## 开发配置文件 + 开发 Gateway网关（--dev）
+
+使用开发配置文件来隔离状态，搭建一个安全的、可随时丢弃的调试环境。有**两个** `--dev` 标志：
+
+- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev`，并将 Gateway网关默认端口设为 `19001`（派生端口随之偏移）。
+- **`gateway --dev`：告诉 Gateway网关在缺少配置和工作区时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
+
+推荐流程（开发配置文件 + 开发引导）：
+
+```bash
+pnpm gateway:dev
+OPENCLAW_PROFILE=dev openclaw tui
+```
+
+如果你还没有全局安装，可通过 `pnpm openclaw ...` 运行 CLI。
+
+具体效果：
+
+1. **配置文件隔离**（全局 `--dev`）
+   - `OPENCLAW_PROFILE=dev`
+   - `OPENCLAW_STATE_DIR=~/.openclaw-dev`
+   - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
+   - `OPENCLAW_GATEWAY_PORT=19001`（浏览器/画布端口随之偏移）
+
+2. **开发引导**（`gateway --dev`）
+   - 如缺少配置则写入最小配置（`gateway.mode=local`，绑定 local loopback）。
+   - 将 `agent.workspace` 设为开发工作区。
+   - 设置 `agent.skipBootstrap=true`（不使用 BOOTSTRAP.md）。
+   - 如缺少工作区文件则进行初始化：
+     `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
+   - 默认身份：**C3‑PO**（礼仪机器人）。
+   - 在开发模式下跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
+
+重置流程（全新开始）：
+
+```bash
+pnpm gateway:dev:reset
+```
+
+注意：`--dev` 是一个**全局**配置文件标志，可能会被某些运行器吞掉。
+如需显式指定，请使用环境变量形式：
+
+```bash
+OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
+```
+
+`--reset` 会清除配置、凭据、会话和开发工作区（使用 `trash` 而非 `rm`），然后重新创建默认的开发环境。
+
+提示：如果非开发 Gateway网关已在运行（launchd/systemd），请先停止它：
+
+```bash
+openclaw gateway stop
+```
+
+## 原始流日志（OpenClaw）
+
+OpenClaw 可以在任何过滤/格式化之前记录**原始助手流**。
+这是查看推理内容是以纯文本增量到达还是以独立思考块到达的最佳方式。
+
+通过 CLI 启用：
+
+```bash
+pnpm gateway:watch --force --raw-stream
+```
+
+可选的路径覆盖：
+
+```bash
+pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
+```
+
+等效的环境变量：
+
+```bash
+OPENCLAW_RAW_STREAM=1
+OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
+```
+
+默认文件：
+
+`~/.openclaw/logs/raw-stream.jsonl`
+
+## 原始数据块日志（pi-mono）
+
+要在解析为块之前捕获**原始 OpenAI 兼容数据块**，pi-mono 提供了一个独立的日志记录器：
+
+```bash
+PI_RAW_STREAM=1
+```
+
+可选路径：
+
+```bash
+PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
+```
+
+默认文件：
+
+`~/.pi-mono/logs/raw-openai-completions.jsonl`
+
+> 注意：此日志仅由使用 pi-mono 的 `openai-completions` 提供商的进程生成。
+
+## 安全注意事项
+
+- 原始流日志可能包含完整的提示词、工具输出和用户数据。
+- 请将日志保存在本地，调试完成后及时删除。
+- 如需分享日志，请先清除密钥和个人身份信息。

package/docs/zh-CN/diagnostics/flags.md

@@ -0,0 +1,98 @@
+---
+read_when:
+  - 你需要在不提升全局日志级别的情况下获取定向调试日志
+  - 你需要为技术支持捕获特定子系统的日志
+summary: 用于定向调试日志的诊断标志
+title: 诊断标志
+x-i18n:
+  generated_at: "2026-02-01T20:24:56Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: daf0eca0e6bd1cbc2c400b2e94e1698709a96b9cdba1a8cf00bd580a61829124
+  source_path: diagnostics/flags.md
+  workflow: 14
+---
+
+# 诊断标志
+
+诊断标志允许你在不开启全局详细日志的情况下启用定向调试日志。标志为可选启用，除非相关子系统检查了它们，否则不会产生任何效果。
+
+## 工作原理
+
+- 标志为字符串（不区分大小写）。
+- 你可以在配置中或通过环境变量覆盖来启用标志。
+- 支持通配符：
+  - `telegram.*` 匹配 `telegram.http`
+  - `*` 启用所有标志
+
+## 通过配置启用
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http"]
+  }
+}
+```
+
+多个标志：
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http", "gateway.*"]
+  }
+}
+```
+
+更改标志后需重启 Gateway网关。
+
+## 环境变量覆盖（一次性）
+
+```bash
+OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
+```
+
+禁用所有标志：
+
+```bash
+OPENCLAW_DIAGNOSTICS=0
+```
+
+## 日志输出位置
+
+标志会将日志输出到标准诊断日志文件中。默认路径为：
+
+```
+/tmp/openclaw/openclaw-YYYY-MM-DD.log
+```
+
+如果你设置了 `logging.file`，则使用该路径。日志格式为 JSONL（每行一个 JSON 对象）。脱敏处理仍根据 `logging.redactSensitive` 设置生效。
+
+## 提取日志
+
+选择最新的日志文件：
+
+```bash
+ls -t /tmp/openclaw/openclaw-*.log | head -n 1
+```
+
+筛选 Telegram HTTP 诊断信息：
+
+```bash
+rg "telegram http error" /tmp/openclaw/openclaw-*.log
+```
+
+或在复现问题时实时追踪：
+
+```bash
+tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
+```
+
+对于远程 Gateway网关，你也可以使用 `openclaw logs --follow`（参见 [/cli/logs](/cli/logs)）。
+
+## 注意事项
+
+- 如果 `logging.level` 设置为高于 `warn` 的级别，这些日志可能会被抑制。默认的 `info` 级别即可。
+- 标志可以安全地保持启用状态；它们只会影响特定子系统的日志量。
+- 使用 [/logging](/logging) 更改日志输出目标、级别和脱敏设置。

package/docs/zh-CN/environment.md

@@ -0,0 +1,88 @@
+---
+read_when:
+  - 需要了解加载了哪些环境变量及其加载顺序
+  - 正在调试 Gateway网关中缺失的 API 密钥
+  - 正在编写提供商认证或部署环境的文档
+summary: OpenClaw 从哪里加载环境变量及其优先级顺序
+title: 环境变量
+x-i18n:
+  generated_at: "2026-02-01T20:24:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b49ae50e5d306612f89f93a86236188a4f2ec23f667e2388b043832be3ac1546
+  source_path: environment.md
+  workflow: 14
+---
+
+# 环境变量
+
+OpenClaw 从多个来源获取环境变量。规则是**永远不覆盖已有的值**。
+
+## 优先级（从高到低）
+
+1. **进程环境**（Gateway网关进程从父 shell/守护进程继承的变量）。
+2. **当前工作目录下的 `.env`**（dotenv 默认行为；不覆盖已有值）。
+3. **全局 `.env`**，位于 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`；不覆盖已有值）。
+4. **配置文件中的 `env` 块**，位于 `~/.openclaw/openclaw.json`（仅在变量缺失时应用）。
+5. **可选的登录 shell 导入**（`env.shellEnv.enabled` 或 `OPENCLAW_LOAD_SHELL_ENV=1`），仅对缺失的预期键生效。
+
+如果配置文件完全不存在，则跳过步骤 4；如果已启用，shell 导入仍会运行。
+
+## 配置文件 `env` 块
+
+有两种等效方式设置内联环境变量（两者都不覆盖已有值）：
+
+```json5
+{
+  env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: {
+      GROQ_API_KEY: "gsk-...",
+    },
+  },
+}
+```
+
+## Shell 环境导入
+
+`env.shellEnv` 会运行你的登录 shell，并仅导入**缺失的**预期键：
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000,
+    },
+  },
+}
+```
+
+等效的环境变量：
+
+- `OPENCLAW_LOAD_SHELL_ENV=1`
+- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`
+
+## 配置中的环境变量替换
+
+你可以使用 `${VAR_NAME}` 语法在配置字符串值中直接引用环境变量：
+
+```json5
+{
+  models: {
+    providers: {
+      "vercel-gateway": {
+        apiKey: "${VERCEL_GATEWAY_API_KEY}",
+      },
+    },
+  },
+}
+```
+
+详情请参阅[配置：环境变量替换](/gateway/configuration#env-var-substitution-in-config)。
+
+## 相关内容
+
+- [Gateway网关配置](/gateway/configuration)
+- [常见问题：环境变量与 .env 加载](/help/faq#env-vars-and-env-loading)
+- [模型概览](/concepts/models)

package/docs/zh-CN/experiments/onboarding-config-protocol.md

@@ -0,0 +1,47 @@
+---
+read_when: 修改新手引导向导步骤或配置 schema 端点时
+summary: 新手引导向导和配置 schema 的 RPC 协议说明
+title: 新手引导与配置协议
+x-i18n:
+  generated_at: "2026-02-01T20:24:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 55163b3ee029c02476800cb616a054e5adfe97dae5bb72f2763dce0079851e06
+  source_path: experiments/onboarding-config-protocol.md
+  workflow: 14
+---
+
+# 新手引导 + 配置协议
+
+用途：在 CLI、macOS 应用和 Web UI 之间共享新手引导与配置界面。
+
+## 组件
+
+- 向导引擎（共享会话 + 提示 + 新手引导状态）。
+- CLI 新手引导使用与 UI 客户端相同的向导流程。
+- Gateway网关 RPC 暴露向导 + 配置 schema 端点。
+- macOS 新手引导使用向导步骤模型。
+- Web UI 根据 JSON Schema + UI 提示渲染配置表单。
+
+## Gateway网关 RPC
+
+- `wizard.start` 参数：`{ mode?: "local"|"remote", workspace?: string }`
+- `wizard.next` 参数：`{ sessionId, answer?: { stepId, value? } }`
+- `wizard.cancel` 参数：`{ sessionId }`
+- `wizard.status` 参数：`{ sessionId }`
+- `config.schema` 参数：`{}`
+
+响应（结构）
+
+- 向导：`{ sessionId, done, step?, status?, error? }`
+- 配置 schema：`{ schema, uiHints, version, generatedAt }`
+
+## UI 提示
+
+- `uiHints` 按路径作为键；可选元数据（label/help/group/order/advanced/sensitive/placeholder）。
+- 敏感字段渲染为密码输入框；无脱敏层。
+- 不支持的 schema 节点回退到原始 JSON 编辑器。
+
+## 说明
+
+- 本文档是跟踪新手引导/配置协议重构的唯一位置。