smoke-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Smoke Test Skillpack

冒烟测试技能包

Run
gbrain smoke-test
or
bash scripts/smoke-test.sh
after any container restart.

容器重启后运行
gbrain smoke-test
或
bash scripts/smoke-test.sh
。

Contract

功能承诺

This skill guarantees:

8 core tests verify gbrain + OpenClaw health after restart
Known failures are auto-fixed before reporting
User-extensible via
```
~/.gbrain/smoke-tests.d/*.sh
```
drop-in scripts
Results logged to
```
/tmp/gbrain-smoke-test.log
```
Exit code = number of unfixed failures (0 = all pass)

本技能承诺：

8项核心测试验证重启后gbrain + OpenClaw的健康状态
报告前自动修复已知故障
可通过
```
~/.gbrain/smoke-tests.d/*.sh
```
即插即用脚本进行用户扩展
结果记录至
```
/tmp/gbrain-smoke-test.log
```
退出码 = 未修复故障数量（0表示全部通过）

Built-in Tests

内置测试

#	Test	Auto-Fix
1	Bun runtime	Install from bun.sh
2	GBrain CLI loads	Reinstall deps
3	GBrain database (doctor)	—
4	GBrain worker process	Start worker
5	OpenClaw Codex plugin (Zod CJS)	`npm install zod@4 --force`
6	OpenClaw gateway	— (may not be started yet)
7	Embedding API key	— (check .env)
8	Brain repo exists	—

序号	测试内容	自动修复方案
1	Bun runtime	从bun.sh安装
2	GBrain CLI加载	重新安装依赖
3	GBrain数据库（诊断）	—
4	GBrain工作进程	启动工作进程
5	OpenClaw Codex插件（Zod CJS）	`npm install zod@4 --force`
6	OpenClaw网关	—（可能尚未启动）
7	Embedding API密钥	—（检查.env文件）
8	Brain仓库存在	—

Usage

使用方法

CLI

CLI方式

bash

gbrain smoke-test

bash

gbrain smoke-test

Direct

直接运行

bash

bash scripts/smoke-test.sh

bash

bash scripts/smoke-test.sh

From OpenClaw bootstrap

从OpenClaw启动脚本调用

Add to your

ensure-services.sh

or equivalent:

bash

bash /path/to/gbrain/scripts/smoke-test.sh >> /tmp/bootstrap.log 2>&1

添加至你的

ensure-services.sh

或等效脚本：

bash

bash /path/to/gbrain/scripts/smoke-test.sh >> /tmp/bootstrap.log 2>&1

From an agent

从Agent调用

exec: bash /data/gbrain/scripts/smoke-test.sh

exec: bash /data/gbrain/scripts/smoke-test.sh

Adding Custom Tests

添加自定义测试

Create executable scripts in

~/.gbrain/smoke-tests.d/

bash

undefined

在

~/.gbrain/smoke-tests.d/

目录下创建可执行脚本：

bash

undefined

~/.gbrain/smoke-tests.d/check-redis.sh

#!/bin/bash redis-cli ping | grep -q PONG


Rules:
- Exit 0 = pass, non-zero = fail
- Filename becomes the test name (e.g. `check-redis` from `check-redis.sh`)
- Keep tests fast (< 10s each)
- Tests run in alphabetical order

#!/bin/bash redis-cli ping | grep -q PONG


规则：
- 退出码0表示通过，非0表示失败
- 文件名即为测试名称（例如`check-redis.sh`对应测试名`check-redis`）
- 测试需保持快速（每个测试耗时<10秒）
- 测试按字母顺序运行

Adding Built-in Tests

添加内置测试

Edit

scripts/smoke-test.sh

. Follow this pattern:

bash

undefined

编辑

scripts/smoke-test.sh

，遵循以下模式：

bash

undefined

── N. [Service Name] ──────────────────────────────────────

── N. [服务名称] ──────────────────────────────────────

if [test condition]; then pass "[Service Name]" else

Auto-fix attempt

[fix command] if [re-test condition]; then fixed "[What was fixed]" pass "[Service Name] (after fix)" else fail "[Service Name] — [error detail]" fi fi

undefined

if [测试条件]; then pass "[服务名称]" else

尝试自动修复

[修复命令] if [重新测试条件]; then fixed "[修复内容]" pass "[服务名称]（修复后）" else fail "[服务名称] — [错误详情]" fi fi

undefined

Design rules:

设计规则：

Test first — never fix without confirming broken
Re-test after fix — verify the fix worked
Timeout everything —
```
timeout N
```
on any command that could hang
Use helpers —
```
pass()
```
,
```
fail()
```
,
```
fixed()
```
,
```
skip()
```
Idempotent fixes — safe to run repeatedly
Skip gracefully —
```
skip()
```
when a prerequisite is missing, don't fail

先测试再修复 — 确认故障后再执行修复操作
修复后重新测试 — 验证修复是否生效
所有操作设置超时 — 对可能挂起的命令使用
```
timeout N
```
使用辅助函数 —
```
pass()
```
,
```
fail()
```
,
```
fixed()
```
,
```
skip()
```
修复操作幂等 — 重复执行不会产生问题
优雅跳过 — 当依赖缺失时使用
```
skip()
```
，不要标记为失败

Environment Variables

环境变量

Var	Default	Description
`GBRAIN_SMOKE_LOG`	`/tmp/gbrain-smoke-test.log`	Log file path
`GBRAIN_DIR_OVERRIDE`	(auto-detect)	Force gbrain install path
`GBRAIN_DATABASE_URL`	(from .env)	Database connection URL
`OPENCLAW_GATEWAY_PORT`	`18789`	Gateway port to test
`GBRAIN_BRAIN_PATH`	`/data/brain`	Brain repo path

变量名	默认值	描述
`GBRAIN_SMOKE_LOG`	`/tmp/gbrain-smoke-test.log`	日志文件路径
`GBRAIN_DIR_OVERRIDE`	（自动检测）	强制指定gbrain安装路径
`GBRAIN_DATABASE_URL`	（来自.env）	数据库连接URL
`OPENCLAW_GATEWAY_PORT`	`18789`	待测试的网关端口
`GBRAIN_BRAIN_PATH`	`/data/brain`	Brain仓库路径

Known Issues & Their Auto-Fixes

已知问题及自动修复方案

Codex Zod core.cjs Missing (discovered 2026-04-23)

Codex Zod core.cjs缺失（发现于2026-04-23）

Symptom:
```
Cannot find module './core.cjs'
```
→ all Codex ACP sessions fail
Cause: Zod v4 npm package ships without
```
core.cjs
```
in some installs
Auto-fix:
```
npm install zod@4 --force
```
in the codex extension's zod dir
Persistence: Does NOT survive container restart (gateway reinstalls deps)
This is why smoke tests must run on every restart

症状：
```
Cannot find module './core.cjs'
```
→ 所有Codex ACP会话失败
原因： Zod v4 npm包在部分安装场景下未包含
```
core.cjs
```
自动修复： 在codex扩展的zod目录中执行
```
npm install zod@4 --force
```
持久性： 无法在容器重启后保留（网关会重新安装依赖）
因此必须在每次重启后运行冒烟测试

GBrain Worker Auth Failure

GBrain工作进程认证失败

Symptom: Worker can't connect to DB
Cause:
```
GBRAIN_DATABASE_URL
```
not propagated to worker subprocess
Auto-fix: Script explicitly passes both
```
DATABASE_URL
```
and
```
GBRAIN_DATABASE_URL
```

症状： 工作进程无法连接数据库
原因：
```
GBRAIN_DATABASE_URL
```
未传递给工作进程子进程
自动修复： 脚本显式传递
```
DATABASE_URL
```
和
```
GBRAIN_DATABASE_URL
```
两个变量

Anti-Patterns

反模式

❌ Running smoke tests on every chat turn. Once per container restart (or on user request) is plenty. The script is cheap but it's not free.
❌ Writing a user drop-in without
```
timeout N
```
around any command that could hang. A single hung drop-in stalls every subsequent run.
❌ Auto-fixing without confirming the check is actually broken first. The
```
pass → fail-detected → fix → re-test
```
loop is the contract; fixes that skip the re-test can report success on a still-broken state.
❌ Treating
```
skip
```
as
```
fail
```
. Missing prerequisites (no OpenClaw installed, no brain repo configured) are skips, not failures. Exit code = count of real failures, not skipped checks.
❌ Hardcoding paths in a user drop-in. Read env vars (
```
GBRAIN_DATABASE_URL
```
,
```
HOME
```
, etc.) so the script travels across container rebuilds.

❌ 每次对话轮次都运行冒烟测试。仅需在容器重启后（或用户请求时）运行一次即可。脚本开销虽小但并非无成本。
❌ 在用户即插即用脚本中，不对可能挂起的命令添加
```
timeout N
```
。单个挂起的脚本会导致后续所有运行停滞。
❌ 未确认检查项确实故障就执行自动修复。
```
通过→检测到故障→修复→重新测试
```
是标准流程；跳过重新测试的修复可能会在状态仍异常时报告成功。
❌ 将
```
跳过
```
视为
```
失败
```
。缺失依赖（未安装OpenClaw、未配置brain仓库）属于跳过项，而非故障项。退出码=实际故障数量，不包含跳过的检查项。
❌ 在用户即插即用脚本中硬编码路径。读取环境变量（
```
GBRAIN_DATABASE_URL
```
,
```
HOME
```
等），确保脚本可在容器重建后正常运行。

Output Format

输出格式

The script writes a one-line status per check to stdout (✅/❌/🔧/⏭️) plus a final summary line:

Results: N/M passed, F auto-fixed, S skipped

. A structured timestamped log appends to

$GBRAIN_SMOKE_LOG

(default

/tmp/gbrain-smoke-test.log

) for post-run forensics. Exit code equals the count of unfixed failures (0 = all pass, positive integer = count of remaining failures).

脚本会向标准输出写入每行一个检查状态（✅/❌/🔧/⏭️），最后一行是总结：

结果：N/M通过，F项已修复，S项已跳过

。结构化的带时间戳日志会追加至

$GBRAIN_SMOKE_LOG

（默认

/tmp/gbrain-smoke-test.log

），用于事后分析。退出码等于未修复故障的数量（0表示全部通过，正整数表示剩余故障数量）。