@termix-it/cryptoclaw 1.0.0

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-03T07:47:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 504c824bff4790006c8b73600daca66b919e049178e9711e6e65b6254731911a
+  source_path: debugging.md
+  workflow: 15
+---
+
+# 调试
+
+本页介绍用于流式输出的调试辅助工具，特别是当提供商将推理混入正常文本时。
+
+## 运行时调试覆盖
+
+在聊天中使用 `/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 标志，它们将在每次重启时传递。
+
+## Dev 配置文件 + dev Gateway 网关（--dev）
+
+使用 dev 配置文件来隔离状态，并启动一个安全、可丢弃的调试设置。有**两个** `--dev` 标志：
+
+- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之移动）。
+- **`gateway --dev`：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
+
+推荐流程（dev 配置文件 + dev 引导）：
+
+```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. **Dev 引导**（`gateway --dev`）
+   - 如果缺失则写入最小配置（`gateway.mode=local`，绑定 loopback）。
+   - 将 `agent.workspace` 设置为 dev 工作区。
+   - 设置 `agent.skipBootstrap=true`（无 BOOTSTRAP.md）。
+   - 如果缺失则填充工作区文件：
+     `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
+   - 默认身份：**C3‑PO**（礼仪机器人）。
+   - 在 dev 模式下跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
+
+重置流程（全新开始）：
+
+```bash
+pnpm gateway:dev:reset
+```
+
+注意：`--dev` 是**全局**配置文件标志，会被某些运行器吞掉。
+如果你需要明确拼写，请使用环境变量形式：
+
+```bash
+OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
+```
+
+`--reset` 清除配置、凭证、会话和 dev 工作区（使用 `trash`，而非 `rm`），然后重新创建默认的 dev 设置。
+
+提示：如果非 dev 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-03T10:05:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: daf0eca0e6bd1cbc2c400b2e94e1698709a96b9cdba1a8cf00bd580a61829124
+  source_path: diagnostics/flags.md
+  workflow: 15
+---
+
+# 诊断标志
+
+诊断标志让你可以启用定向调试日志，而无需在所有地方开启详细日志。标志是可选启用的，除非子系统检查它们，否则不会生效。
+
+## 工作原理
+
+- 标志是字符串（不区分大小写）。
+- 你可以在配置中或通过环境变量覆盖来启用标志。
+- 支持通配符：
+  - `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
+```
+
+或在复现时使用 tail：
+
+```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-03T07:47:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b49ae50e5d306612f89f93a86236188a4f2ec23f667e2388b043832be3ac1546
+  source_path: environment.md
+  workflow: 15
+---
+
+# 环境变量
+
+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: Changing onboarding wizard steps or config schema endpoints
+summary: 新手引导向导和配置模式的 RPC 协议说明
+title: 新手引导和配置协议
+x-i18n:
+  generated_at: "2026-02-03T07:47:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 55163b3ee029c02476800cb616a054e5adfe97dae5bb72f2763dce0079851e06
+  source_path: experiments/onboarding-config-protocol.md
+  workflow: 15
+---
+
+# 新手引导 + 配置协议
+
+目的：CLI、macOS 应用和 Web UI 之间共享的新手引导 + 配置界面。
+
+## 组件
+
+- 向导引擎（共享会话 + 提示 + 新手引导状态）。
+- CLI 新手引导使用与 UI 客户端相同的向导流程。
+- Gateway 网关 RPC 公开向导 + 配置模式端点。
+- 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, uiHints, version, generatedAt }`
+
+## UI 提示
+
+- `uiHints` 按路径键入；可选元数据（label/help/group/order/advanced/sensitive/placeholder）。
+- 敏感字段渲染为密码输入；无脱敏层。
+- 不支持的模式节点回退到原始 JSON 编辑器。
+
+## 注意
+
+- 本文档是跟踪新手引导/配置协议重构的唯一位置。