2026-04-21 ヘッドレスレンタルクラウドMacでのOpenClawサブエージェント＆チャネル束ねトラブルシュート
Discordスレッドがサブエージェントに届かなくなった、あるいはTelegramキューが静かなのにゲートウェイが127.0.0.1:18789で待っている—それは束ね＋セッションの問題で、モデル障害ではない。SSHだけのレンタルApple SiliconではGUIでマッピングを直せない。本2026-04-21のRunbookはopenclaw doctor、チャネルプローブ、セッションディレクトリ検証、制御されたゲートウェイ再起動の順に進め、ヘルスプローブ、nginxイングレス、ゲートウェイ昇格/ロールバックへ誘導する。HK / JP / KR / SG / USで同じ復旧物語を共有し、パッケージレイアウトに焦点を当てたSkills＆ClawHub固定記事と役割を分ける。
タイムラインを先に固める：npmマイナー更新か？webhookパス変更か？状態ディレクトリの共有か？semver・Git SHA・設定diffをチケットに載せる。
分類に値する症状パターン
| 見えるもの | 想定レイヤー | 最初の一手 |
|---|---|---|
| ゲートウェイは健康だがチャネルが沈黙 | トークン、webhook、ペアリング | チャネル状態プローブ＋ペアリング一覧 |
| セッション言及のサブエージェント起動エラー | ファイルシステムパス検証 | sessionsディレクトリ権限と設定を確認 |
| npm更新後のフラップ | 古いグローバルと実行プロセスの不一致 | ゲートウェイ停止後、openclaw --versionと実行バイナリを比較 |
doctor、ステータス、ログ相関
openclaw doctorから始め、標準出力をログパイプラインへ。重複LaunchAgentsのガイドと照合—plistをunloadせず再インストールするとリスナーが積み上がる。
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor-$CI_BUILD_ID.log
チャネル束ねとメンションゲート
openclaw.json（または後継）でチャネルIDがエージェントIDに正しくマップされているか確認する。メンションゲート（requireMention）は暗黙購読を期待する運用で静かに落とす—チームごとの相互作用モデルを文書化する。公開イングレスはnginxでTLS終端し、レート制限を保守的に。
セッションパスとサブエージェント保存
上流リリースは検証を厳格化し、セッションファイルは設定されたsessionsルート配下に置く必要がある。アップグレード後にパスエラーが出たら、固定したsemverのリリースノートと保存設定をdiffし、chmodの前にシークレットとlaunchdに沿ってOPENCLAW_STATE_DIR等を調整する。
サンダリングヘルドなしのゲートウェイバウンス
- イングレスを一時停止 — アップストリームは503と
Retry-Afterを返す。 - 停止 — CLIまたはインストールに記載の
launchctl。 - 起動 — ローカルヘルスが通ってから外向きを再開。
Nginx、ヘルス、リージョンフェイルオーバー
ローカルcurlが通ったらnginxを再有効化し、エラー率を監視する。リージョンのMacが不健康なら、1台を何度も再起動せず料金ページのセカンダリへシフトする。
関連Runbook
メッシュアクセスはTailscaleメッシュ。コンテナとネイティブnpmの比較はDocker対ネイティブnpm。構造化ログは本番ログとフィールドを揃える。
FAQ：クラウドMacのサブエージェント
| 質問 | 回答 |
|---|---|
| サブエージェントはゲートウェイユーザーを共有すべき？ | 環境ごとに状態ディレクトリを分けるのが無難—同一Macでもセッションのクロストークを避ける。 |
| ペアリング承認を自動化できる？ | 組織のリスク許容度内のみ；チャットブリッジの端末承認の所有者を記録する。 |
| インシデントはどこで追跡？ | ゲートウェイログとプロバイダのダッシュボードを相関；チケットにsemver＋Git SHAを含める。 |
まとめ：チャネル束ねはファイアウォールルールのように—明示的なID、パス、再起動—そしてnpmグローバルを触るたびにロールバックtarを用意する。
