smoke-test

スモークテストスキルパック

マシンまたはコンテナを再起動した後、または何かが正常に動作していないように見える場合は、 gbrain smoke-test を実行してください。

契約

このスキルで保証される内容：

• 8 つのコアテストで、再起動後の gbrain の健全性を確認します（OpenClaw サービスが存在する場合はそれらも確認し、存在しない場合はスキップします）
• 範囲を限定できるローカルの障害は、報告前に自動修正されます。ワーカープロセスの修復は明示的な操作が必要です。プロセストポロジーとシェルジョブのポリシーはオペレーターが決定するためです
• ~/.gbrain/smoke-tests.d/*.sh のドロップインスクリプトでユーザーが拡張できます
• 結果は /tmp/gbrain-smoke-test.log に記録されます
• 終了コード = 未修正の失敗数（0 = すべて合格）

組み込みテスト

#	テスト	自動修正
1	Bun ランタイム	bun.sh からインストール
2	GBrain CLI の読み込み	依存関係を再インストール
3	GBrain データベース（gbrain engine status --json によるエンジンの識別情報、その後 doctor --json の connection チェック）	gbrain db-repair --yes を実行して再テスト
4	GBrain ワーカープロセス	—（ネイティブのスーパーバイザー状態 + 重複検出）
5	OpenClaw Codex プラグイン（Zod CJS）。OpenClaw がない場合はスキップ	npm install zod@4 --force
6	OpenClaw ゲートウェイ。OpenClaw がない場合はスキップ	—（まだ起動していない可能性があります）
7	埋め込み API キー	—（.env を確認）
8	Brain リポジトリの存在	—

使用方法

CLI

gbrain smoke-test

これはすべてのインストールで使用する呼び出し方法です。インストール済みパッケージからテストスクリプトを解決します。

任意の起動スクリプトまたはログインフックから

gbrain smoke-test >> /tmp/bootstrap.log 2>&1

OpenClaw のブートストラップから（OpenClaw のデプロイのみ）

ensure-services.sh または同等のスクリプトに追加します：

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

エージェントから

exec: gbrain smoke-test

コントリビューター向けの注記：gbrain リポジトリのチェックアウト内では、bash scripts/smoke-test.sh を使ってスクリプトを直接実行することもできます。

カスタムテストの追加

~/.gbrain/smoke-tests.d/ に実行可能なスクリプトを作成します：

# ~/.gbrain/smoke-tests.d/check-redis.sh
#!/bin/bash
redis-cli ping | grep -q PONG

ルール：

• 終了コード 0 = 合格、0 以外 = 失敗
• ファイル名がテスト名になります（例：check-redis.sh は check-redis）
• テストは高速に保ってください（それぞれ 10 秒未満）
• テストはアルファベット順に実行されます

組み込みテストの追加（gbrain コントリビューター向け）

このセクションは、gbrain のソースリポジトリで作業するコントリビューター向けです。プラグインのインストールではスクリプトは読み取り専用で配布され、アップグレード時に上書きされます。追加のチェックを行いたい場合は、上記の ~/.gbrain/smoke-tests.d/ のドロップインスクリプトを使用してください。

scripts/smoke-test.sh を編集します。次のパターンに従ってください：

# ── N. [Service Name] ──────────────────────────────────────
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

設計ルール：

1. まずテストする — 壊れていることを確認せずに修正しないでください
2. 修正後に再テストする — 修正が機能したことを確認してください
3. すべてにタイムアウトを設定する — ハングする可能性があるコマンドには timeout N を指定してください
4. ヘルパーを使う — pass()、fail()、fixed()、skip() を使用してください
5. 冪等な修正にする — 繰り返し実行しても安全にしてください
6. 適切にスキップする — 前提条件が欠けている場合は skip() を呼び出し、失敗にしないでください

環境変数

変数	デフォルト	説明
GBRAIN_SMOKE_LOG	/tmp/gbrain-smoke-test.log	ログファイルのパス
GBRAIN_DIR_OVERRIDE	（自動検出）	gbrain のインストールパスを強制指定
GBRAIN_BUN_PATH	（自動検出）	Bun バイナリのパスを強制指定
GBRAIN_DATABASE_URL	（.env から取得）	データベース接続 URL
GBRAIN_SMOKE_WORKER_PID_FILE	/tmp/gbrain-worker.pid	旧式の単独ワーカー PID パス
OPENCLAW_GATEWAY_PORT	18789	テストするゲートウェイポート
GBRAIN_BRAIN_PATH	（デプロイ固有）	Brain リポジトリのパス。コンテナへのデプロイでは /data/brain がデフォルトです。それ以外の場合は、Brain リポジトリのパスを設定してください。未設定の場合、テスト 8 は失敗ではなくスキップされます。

既知の問題と自動修正

Codex の Zod core.cjs が見つからない（2026-04-23 に発見）

（OpenClaw ゲートウェイへのデプロイのみ：これは OpenAI Codex CLI ではなく、OpenClaw の Codex ACP プラグインに関する問題です。）

• 症状： Cannot find module './core.cjs' → すべての Codex ACP セッションが失敗します
• 原因： Zod v4 の npm パッケージは、一部のインストール環境で core.cjs を含まずに配布されます
• 自動修正： codex 拡張機能の zod ディレクトリで npm install zod@4 --force を実行します
• 永続性： コンテナを再起動すると維持されません（ゲートウェイが依存関係を再インストールします）
• スモークテストを再起動のたびに実行する必要があるのはこのためです

GBrain Worker 認証エラー

• 症状： Worker が DB に接続できません
• 原因： GBRAIN_DATABASE_URL が Worker のサブプロセスに引き継がれていません
• 自動修正： スクリプトで DATABASE_URL と GBRAIN_DATABASE_URL の両方を明示的に渡します

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックが発生した場合は、エージェント運用者プロトコルに従ってください。このスキル固有の対応は次のとおりです。

• 終了コード ＝ 未修正の失敗数です。それぞれについて名前と試した修正方法を報告してください。テストがスキップされた場合に、すべて成功したと報告してはいけません。
• データベーステストが GBRAIN_DB_ACCESS マーカーで失敗した場合は、gbrain db-repair を実行して再テストしてください。rewrite 層にはユーザーの同意が必要です。
• 埋め込み API キーのチェックに失敗した場合、自動修正はありません。不足しているキーをユーザーに伝え、そのキーが設定されるまでは検索がキーワードのみで行われることを伝えてください。

アンチパターン

• ❌ チャットのたびにスモークテストを実行すること。コンテナーの再起動ごとに 1 回（またはユーザーの要求時）で十分です。スクリプトの実行コストは低いですが、ゼロではありません。
• ❌ ハングする可能性のあるコマンドを timeout N で囲まずに、ユーザーのドロップインスクリプトに記述すること。ドロップインスクリプトが 1 つハングすると、その後のすべての実行が停止します。
• ❌ チェックが実際に壊れていることを確認せずに自動修正すること。pass → fail-detected → fix → re-test のループが基本です。再テストを省略した修正では、壊れたままの状態でも成功と報告する可能性があります。
• ❌ skip を fail として扱うこと。前提条件が満たされていない場合（OpenClaw がインストールされていない、brain リポジトリが設定されていないなど）は失敗ではなく、スキップです。終了コードはスキップされたチェックではなく、実際の失敗数を表します。
• ❌ ユーザーのドロップインスクリプトでパスをハードコードすること。環境変数（GBRAIN_DATABASE_URL、HOME など）を読み取り、コンテナーを再ビルドしてもスクリプトを使えるようにしてください。

出力形式

スクリプトは、各チェックについて 1 行のステータス（✅/❌/🔧/⏭️）を標準出力に書き込み、最後に Results: N/M passed, F auto-fixed, S skipped という要約行を出力します。構造化されたタイムスタンプ付きログは $GBRAIN_SMOKE_LOG（デフォルトは /tmp/gbrain-smoke-test.log）に追記され、実行後の調査に利用できます。終了コードは未修正の失敗数と等しくなります（0 ＝ すべて成功、正の整数 ＝ 残っている失敗数）。