chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
22b131f2e1
commit
8c4ce27ed9
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要检查原始模型输出，以排查推理泄漏
|
||||
- 你想在迭代时以监视模式运行 Gateway 网关
|
||||
- 你需要一个可重复的调试工作流
|
||||
summary: 调试工具：监视模式、原始模型流，以及推理泄漏追踪
|
||||
- 你需要检查原始模型输出，以排查推理泄露。
|
||||
- 你想在迭代时以监视模式运行 Gateway 网关。
|
||||
- 你需要一个可重复的调试工作流。
|
||||
summary: 调试工具：监视模式、原始模型流，以及推理泄露追踪
|
||||
title: 调试
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T18:22:07Z"
|
||||
generated_at: "2026-04-23T04:19:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bc31ce9b41e92a14c4309f32df569b7050b18024f83280930e53714d3bfcd5cc
|
||||
source_hash: 45f1c55268c02d2d52abf348760d1e00e7536788c3a9aa77854692c4d964fb6e
|
||||
source_path: help/debugging.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 调试
|
||||
|
||||
本页介绍用于流式输出的调试辅助工具，尤其适用于提供商将推理内容混入普通文本时的情况。
|
||||
本页介绍用于调试流式输出的辅助工具，尤其适用于提供商将推理内容混入普通文本的情况。
|
||||
|
||||
## 运行时调试覆盖
|
||||
|
||||
在聊天中使用 `/debug` 来设置**仅运行时**的配置覆盖（存储在内存中，而不是磁盘）。
|
||||
`/debug` 默认禁用；可通过 `commands.debug: true` 启用。
|
||||
当你需要切换一些较少使用的设置，而不想编辑 `openclaw.json` 时，这会很方便。
|
||||
在聊天中使用 `/debug` 来设置**仅限运行时**的配置覆盖（保存在内存中，而不是磁盘中）。
|
||||
`/debug` 默认禁用；使用 `commands.debug: true` 启用。
|
||||
当你需要切换一些不常见的设置，又不想编辑 `openclaw.json` 时，这会很方便。
|
||||
|
||||
示例：
|
||||
|
||||
@ -33,11 +33,11 @@ x-i18n:
|
||||
/debug reset
|
||||
```
|
||||
|
||||
`/debug reset` 会清除所有覆盖，并恢复为磁盘上的配置。
|
||||
`/debug reset` 会清除所有覆盖项，并恢复为磁盘上的配置。
|
||||
|
||||
## 会话追踪输出
|
||||
|
||||
当你想在单个会话中查看插件拥有的追踪/调试行，而不启用完整详细模式时，请使用 `/trace`。
|
||||
当你想在单个会话中查看由 plugin 拥有的 trace/debug 行，而不想开启完整详细模式时，使用 `/trace`。
|
||||
|
||||
示例：
|
||||
|
||||
@ -47,35 +47,160 @@ x-i18n:
|
||||
/trace off
|
||||
```
|
||||
|
||||
将 `/trace` 用于插件诊断，例如 Active Memory 调试摘要。
|
||||
对于常规的详细状态/工具输出，继续使用 `/verbose`；对于仅运行时的配置覆盖，继续使用 `/debug`。
|
||||
将 `/trace` 用于 plugin 诊断，例如 Active Memory 调试摘要。
|
||||
常规的详细状态/工具输出继续使用 `/verbose`，而仅限运行时的配置覆盖继续使用 `/debug`。
|
||||
|
||||
## 临时 CLI 调试计时
|
||||
|
||||
OpenClaw 将 `src/cli/debug-timing.ts` 保留为一个用于本地排查的小型辅助工具。它刻意**默认不接入** CLI 启动流程、命令路由或任何命令。仅在你调试慢命令时使用它，然后在提交行为变更之前移除导入和时间跨度标记。
|
||||
|
||||
当某个命令执行缓慢，而你需要先快速拆解各阶段耗时，再决定是使用 CPU 分析器还是修复某个特定子系统时，就使用它。
|
||||
|
||||
### 添加临时时间跨度
|
||||
|
||||
将辅助工具加在你要排查的代码附近。例如，在调试
|
||||
`openclaw models list` 时，对
|
||||
`src/commands/models/list.list-command.ts` 的临时补丁可能如下所示：
|
||||
|
||||
```ts
|
||||
// Temporary debugging only. Remove before landing.
|
||||
import { createCliDebugTiming } from "../../cli/debug-timing.js";
|
||||
|
||||
const timing = createCliDebugTiming({ command: "models list" });
|
||||
|
||||
const authStore = timing.time("debug:models:list:auth_store", () => ensureAuthProfileStore());
|
||||
|
||||
const loaded = await timing.timeAsync(
|
||||
"debug:models:list:registry",
|
||||
() => loadListModelRegistry(cfg, { sourceConfig }),
|
||||
(result) => ({
|
||||
models: result.models.length,
|
||||
discoveredKeys: result.discoveredKeys.size,
|
||||
}),
|
||||
);
|
||||
```
|
||||
|
||||
指南：
|
||||
|
||||
- 临时阶段名称统一使用 `debug:` 前缀。
|
||||
- 只在怀疑较慢的几个部分周围加少量时间跨度。
|
||||
- 优先使用较宽泛的阶段名称，例如 `registry`、`auth_store` 或 `rows`，而不是辅助函数名称。
|
||||
- 同步工作使用 `time()`，Promise 使用 `timeAsync()`。
|
||||
- 保持 stdout 干净。该辅助工具会写入 stderr，因此命令的 JSON 输出仍可被解析。
|
||||
- 在提交最终修复 PR 之前，移除临时导入和时间跨度标记。
|
||||
- 在说明优化内容的 issue 或 PR 中附上计时输出或简要总结。
|
||||
|
||||
### 以可读输出运行
|
||||
|
||||
可读模式最适合实时调试：
|
||||
|
||||
```bash
|
||||
OPENCLAW_DEBUG_TIMING=1 pnpm openclaw models list --all --provider moonshot
|
||||
```
|
||||
|
||||
以下是一次临时 `models list` 排查的示例输出：
|
||||
|
||||
```text
|
||||
OpenClaw CLI debug timing: models list
|
||||
0ms +0ms start all=true json=false local=false plain=false provider="moonshot"
|
||||
2ms +2ms debug:models:list:import_runtime duration=2ms
|
||||
17ms +14ms debug:models:list:load_config duration=14ms sourceConfig=true
|
||||
20.3s +20.3s debug:models:list:auth_store duration=20.3s
|
||||
20.3s +0ms debug:models:list:resolve_agent_dir duration=0ms agentDir=true
|
||||
20.3s +0ms debug:models:list:resolve_provider_filter duration=0ms
|
||||
25.3s +5.0s debug:models:list:ensure_models_json duration=5.0s
|
||||
31.2s +5.9s debug:models:list:load_model_registry duration=5.9s models=869 availableKeys=38 discoveredKeys=868 availabilityError=false
|
||||
31.2s +0ms debug:models:list:resolve_configured_entries duration=0ms entries=1
|
||||
31.2s +0ms debug:models:list:build_configured_lookup duration=0ms entries=1
|
||||
33.6s +2.4s debug:models:list:read_registry_models duration=2.4s models=871
|
||||
35.2s +1.5s debug:models:list:append_discovered_rows duration=1.5s seenKeys=0 rows=0
|
||||
36.9s +1.7s debug:models:list:append_catalog_supplement_rows duration=1.7s seenKeys=5 rows=5
|
||||
|
||||
Model Input Ctx Local Auth Tags
|
||||
moonshot/kimi-k2-thinking text 256k no no
|
||||
moonshot/kimi-k2-thinking-turbo text 256k no no
|
||||
moonshot/kimi-k2-turbo text 250k no no
|
||||
moonshot/kimi-k2.5 text+image 256k no no
|
||||
moonshot/kimi-k2.6 text+image 256k no no
|
||||
|
||||
36.9s +0ms debug:models:list:print_model_table duration=0ms rows=5
|
||||
36.9s +0ms complete rows=5
|
||||
```
|
||||
|
||||
从这段输出中得到的发现：
|
||||
|
||||
| 阶段 | 耗时 | 含义 |
|
||||
| ---------------------------------------- | ---------: | ------------------------------------------------------------------------------------------------------- |
|
||||
| `debug:models:list:auth_store` | 20.3s | 加载 auth-profile store 是最大的开销，应优先排查。 |
|
||||
| `debug:models:list:ensure_models_json` | 5.0s | 同步 `models.json` 的开销已经大到值得检查缓存或跳过条件。 |
|
||||
| `debug:models:list:load_model_registry` | 5.9s | 构建 registry 以及提供商可用性处理也是有意义的开销。 |
|
||||
| `debug:models:list:read_registry_models` | 2.4s | 读取全部 registry 模型并非没有代价，对 `--all` 可能会产生影响。 |
|
||||
| 行追加阶段 | 3.2s total | 即使只构建五行显示结果也需要数秒，因此值得更仔细地检查过滤路径。 |
|
||||
| `debug:models:list:print_model_table` | 0ms | 渲染不是瓶颈。 |
|
||||
|
||||
这些发现已经足以指导下一次补丁，而无需将计时代码保留在生产路径中。
|
||||
|
||||
### 以 JSON 输出运行
|
||||
|
||||
当你想保存或比较计时数据时，使用 JSON 模式：
|
||||
|
||||
```bash
|
||||
OPENCLAW_DEBUG_TIMING=json pnpm openclaw models list --all --provider moonshot \
|
||||
2> .artifacts/models-list-timing.jsonl
|
||||
```
|
||||
|
||||
stderr 中的每一行都是一个 JSON 对象：
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "models list",
|
||||
"phase": "debug:models:list:registry",
|
||||
"elapsedMs": 31200,
|
||||
"deltaMs": 5900,
|
||||
"durationMs": 5900,
|
||||
"models": 869,
|
||||
"discoveredKeys": 868
|
||||
}
|
||||
```
|
||||
|
||||
### 提交前清理
|
||||
|
||||
在创建最终 PR 之前：
|
||||
|
||||
```bash
|
||||
rg 'createCliDebugTiming|debug:[a-z0-9_-]+:' src/commands src/cli \
|
||||
--glob '!src/cli/debug-timing.*' \
|
||||
--glob '!*.test.ts'
|
||||
```
|
||||
|
||||
除非该 PR 明确是在添加永久性的诊断能力，否则这个命令不应返回任何临时插桩调用位置。对于常规性能修复，只保留行为变更、测试，以及附带计时证据的简短说明即可。
|
||||
|
||||
对于更深层的 CPU 热点，请使用 Node 分析（`--cpu-prof`）或外部分析器，而不是继续添加更多计时包装。
|
||||
|
||||
## Gateway 网关监视模式
|
||||
|
||||
为了快速迭代，请在文件监视器下运行 Gateway 网关：
|
||||
为了更快迭代，请在文件监视器下运行 Gateway 网关：
|
||||
|
||||
```bash
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
这对应于：
|
||||
它对应于：
|
||||
|
||||
```bash
|
||||
node scripts/watch-node.mjs gateway --force
|
||||
```
|
||||
|
||||
监视器会在 `src/` 下与构建相关的文件、扩展源码文件、扩展的 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts` 发生变更时重启。
|
||||
扩展元数据变更会在不强制执行 `tsdown` 重建的情况下重启 Gateway 网关；源码和配置变更仍会先重建 `dist`。
|
||||
文件监视器会在以下内容发生变化时重启：`src/` 下与构建相关的文件、扩展源码文件、扩展 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts`。扩展元数据变化会在**不强制执行** `tsdown` 重建的情况下重启 Gateway 网关；源码和配置变化仍会先重建 `dist`。
|
||||
|
||||
在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们都会在每次重启时透传。
|
||||
现在，对于同一仓库/标志组合重复运行相同的监视命令时，会替换旧的监视器，而不是留下重复的监视器父进程。
|
||||
你可以在 `gateway:watch` 后附加任意 Gateway 网关 CLI 标志，它们会在每次重启时透传。现在，对于同一仓库/同一标志组合，重复运行相同的监视命令会替换旧的监视器，而不会留下重复的监视器父进程。
|
||||
|
||||
## 开发配置文件 + 开发 Gateway 网关（`--dev`）
|
||||
|
||||
使用开发配置文件来隔离状态，并为调试启动一个安全、可丢弃的环境。这里有**两个** `--dev` 标志：
|
||||
使用开发配置文件可以隔离状态，并为调试快速启动一个安全、可丢弃的环境。这里有**两个** `--dev` 标志：
|
||||
|
||||
- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口也会随之变化）。
|
||||
- **`gateway --dev`：** 告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区（并跳过 `BOOTSTRAP.md`）。
|
||||
- **全局 `--dev`（配置文件）**：将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认设为 `19001`（派生端口也会随之偏移）。
|
||||
- **`gateway --dev`**：告诉 Gateway 网关在缺失时自动创建默认配置和工作区（并跳过 `BOOTSTRAP.md`）。
|
||||
|
||||
推荐流程（开发配置文件 + 开发引导）：
|
||||
|
||||
@ -86,19 +211,19 @@ 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`（browser/canvas 端口也会相应变化）
|
||||
- `OPENCLAW_GATEWAY_PORT=19001`（浏览器/canvas 端口也会相应偏移）
|
||||
|
||||
2. **开发引导**（`gateway --dev`）
|
||||
- 如果缺失，则写入最小配置（`gateway.mode=local`，绑定到 loopback）。
|
||||
- 将 `agent.workspace` 设置为开发工作区。
|
||||
- 若配置不存在，则写入最小配置（`gateway.mode=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`）。
|
||||
@ -109,8 +234,8 @@ OPENCLAW_PROFILE=dev openclaw tui
|
||||
pnpm gateway:dev:reset
|
||||
```
|
||||
|
||||
注意：`--dev` 是一个**全局**配置文件标志，某些运行器会吞掉它。
|
||||
如果你需要明确写出来，请使用环境变量形式：
|
||||
注意：`--dev` 是一个**全局**配置文件标志，某些运行器会把它吞掉。
|
||||
如果你需要明确写出它，请使用环境变量形式：
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
|
||||
@ -118,7 +243,7 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
|
||||
|
||||
`--reset` 会清除配置、凭证、会话和开发工作区（使用 `trash`，而不是 `rm`），然后重新创建默认的开发环境。
|
||||
|
||||
提示：如果一个非开发 Gateway 网关已经在运行（launchd/systemd），请先停止它：
|
||||
提示：如果非开发 Gateway 网关已经在运行（launchd/systemd），请先停止它：
|
||||
|
||||
```bash
|
||||
openclaw gateway stop
|
||||
@ -126,8 +251,8 @@ openclaw gateway stop
|
||||
|
||||
## 原始流日志（OpenClaw）
|
||||
|
||||
OpenClaw 可以在任何过滤/格式化之前记录**原始 assistant 流**。
|
||||
这是查看推理内容是否作为纯文本增量到达（或作为单独的 thinking 块到达）的最佳方式。
|
||||
OpenClaw 可以在进行任何过滤/格式化**之前**记录**原始 assistant 流**。
|
||||
这是查看推理内容是否以普通文本增量形式到达（或作为单独的 thinking 块到达）的最佳方式。
|
||||
|
||||
通过 CLI 启用：
|
||||
|
||||
@ -154,7 +279,8 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
|
||||
|
||||
## 原始分块日志（pi-mono）
|
||||
|
||||
要在解析为块之前捕获**原始 OpenAI-compat 分块**，pi-mono 提供了一个单独的日志记录器：
|
||||
为了在分块被解析为 block 之前捕获**原始 OpenAI-compat chunk**，
|
||||
pi-mono 提供了单独的日志记录器：
|
||||
|
||||
```bash
|
||||
PI_RAW_STREAM=1
|
||||
@ -170,11 +296,11 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
|
||||
|
||||
`~/.pi-mono/logs/raw-openai-completions.jsonl`
|
||||
|
||||
> 注意：这仅由使用 pi-mono 的
|
||||
> `openai-completions` 提供商的进程输出。
|
||||
> 注意：这只会由使用 pi-mono 的
|
||||
> `openai-completions` provider 的进程输出。
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- 原始流日志可能包含完整提示词、工具输出和用户数据。
|
||||
- 请将日志保留在本地，并在调试后删除。
|
||||
- 如果你要共享日志，请先清理其中的密钥和个人身份信息。
|
||||
- 如果你需要共享日志，请先清理其中的密钥和个人身份信息。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user