プリフライト · ドクター · エラー マトリックス · 再現可能なデプロイ
最初のチャネルを配線するビルダー通常は「ゲートウェイが起動しない」という問題で停止します。弱いモデルではありません。ノードのバージョン、ディレクトリの権限、.env対 YAML ドリフトでは、ビジーなポート、プロキシ、DNS がそれぞれ爆発的にレッドログになる可能性があります。このガイドでは、プリフライトチェックリスト、ミニマルチャンネルとマルチチャンネル比較、6 つの診断ステップ（含むopenclaw doctor)、エラー症状マトリックス、そしてクラウド移行セルフチェック。 pm2 および常時オンのベースラインについては、永続的なクラウド デプロイ プレイブック;価格設定のコンテキストについては、オープンレンタル料金.
インストール スクリプトは短く見えます。コストがかかる部分は、どのユーザーがゲートウェイを起動するか、構成が解決される場所、デフォルトのログ パス、どのポートが空いていなければならないか、誰がプロキシ/DNS を所有するかなど、実行時の前提条件を記述することです。 「ゲートウェイが起動しない」インシデントの多くは、OpenClaw ロジックではなく、Node と macOS の権限のやり取りによって発生します。以下の 5 つのギャップは、コミュニティ スレッドで常に表示されます。PATH ドリフトに気づく前に 3 回再インストールすることを避けるために、Runbook にギャップをキャプチャします。
次に Slack か Telegram を計画する場合は、決定してくださいトークンローテーションそして最小権限のディレクトリ早い;古い環境変数を使用して最初のチャネルが成功すると、2 番目のローテーションが苦痛になります。
ノードとパッケージマネージャーのドリフト:OpenClaw は最新の Node LTS を期待しています。 nvm、fnm、およびシステム ノードを混合すると、多くの場合、正しい結果が得られます。node -vターミナル内にありますが、プロセス スーパーバイザーの下にある古いバイナリです。ゴールデン呼び出しを 1 つ固定し、ドクター出力で実際のバイナリを確認します。
作業ディレクトリと権限の境界:デスクトップまたは iCloud ベースのフォルダーにクローンを作成すると、ロックや権限の変更が発生する可能性があります。サービス ユーザーのホームの専用サブツリーの下に運用ツリーを保持し、書き込み可能な AgentSkill パスを文書化します。
ポートとファイアウォールのデフォルト:他のデーモンと衝突するダッシュボード リスナーとゲートウェイ リスナーはすぐに終了します。企業プロキシまたはホスト ファイアウォールにより、発信 LLM 呼び出しがブロックされる場合があります。ポート スキャンと 1 行のアウトバウンド カール スモーク テストをプリフライトに追加します。
複数の構成ソース: .env、シェル プロファイル、launchd/pm2 env ブロック、YAML オーバーレイを組み合わせると、「間違ったファイルを編集した」というバグが発生します。信頼できる単一の情報源を選択し、文書の優先順位を決定します。
ロギングと可観測性のギャップ:標準出力の宛先とローテーションがないと、最初の長い実行でディスクがいっぱいになるか、実際のエラーがスクロールして消えてしまいます。インストール時にパスと保持を修正します。モニターを改造するよりも桁違いに安価です。
リストを確認し、次のセクションでインストール パスを選択します: 最小ゲートウェイのみまたはマルチチャネル実稼働トポロジ。
初日から Slack、メール、Webhook をオンにすると、失敗マトリックスが爆発的に増加します。より安全:健全なログを含む最小のプロファイルでゲートウェイを起動します次に、変更ウィンドウごとに 1 つのチャネル アダプタを追加して、ロールバックが明確になるようにします。この表は、最初のレビューに対する期待をまとめたものです。
| 寸法 | 最小限 (ゲートウェイ + 単一チャネルまたは CLI) | マルチチャンネルインクリメンタル |
|---|---|---|
| ゴール | プロセス、構成解析、LLM エグレス、ベースライン スキルを検証する | ルーティング、トークンのローテーション、同時セッションの分離を検証します。 |
| 構成面 | 少数の環境変数、浅い YAML | 多くの Webhook/トークン。誤差曲面は急速に拡大します |
| トリアージ順序 | 最初にゲートウェイのログとドクター、次にモデル API | チャネルエラーとエージェントエラーを分離する |
| ロールバックコスト | 低 — 1 つのアダプターと差分をコメントします | 高 — チャネルごとのスナップショットを保持します |
| こんな方に最適 | 初めてのビルダーと小規模チーム | 本番環境に向かうランブックを持つチーム |
アダプターの前にアイドル状態のゲートウェイを安定させます。順序を逆にすると、3 つのエラー クラスが 1 つのログ ストリームにスタックされます。
これらの手順により、プロセスレベルの障害(起動時に終了、不正な設定、ビジーポート)。プロセスが正常であるにもかかわらずメッセージが到着しない場合は、ゲートウェイが緑色に表示されてからアダプターをデバッグしてください。コミュニティ CLI は頻繁に出荷されますopenclaw doctor(または修正バリアント) — リリース ノートの正確なサブコマンドを置き換えます。
再現コマンドをフリーズします。npm スクリプト、グローバル CLI、pm2、および cwd をチケットに記録します。
環境のセルフチェックを実行します。実行するopenclaw doctor、完全な出力をアーカイブし、ノード パス、権限の拒否、deps の欠落、およびスキーマ エラーを丸で囲みます。
レイヤー内の構成を検証します。YAML/JSON を解析し、環境変数がシェル プロファイルによってオーバーライドされていないことを確認します。
リスナーを確認します。ダッシュボードとゲートウェイのポートが空いていることを確認してください。ループバックにおける VPN の癖に注意してください。
最初の 200 ログ行をキャプチャします。最初のエラーから上に向かって進みます。多くの場合、根本原因は警告として早くに表示されます。
最小限のロールバック テスト:オプションのアダプターとサードパーティのスキルを無効にし、公式サンプルを 1 つ保持してから、復元を二分します。
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
ヒント： doctor --fixローカル構成を変更します。実稼働ノードで使用する前に、スナップショット ファイルを変更するか、変更管理を実行します。
これをオンコール チート カードとして使用します。症状を照合し、最初のアクションを実行してから、検索範囲を広げます。 3 つのパスが失敗した場合は、セクション 3 に戻って完全なログを取得し、二等分します。
| 症状 | 考えられる原因 | 最初のアクション |
|---|---|---|
| 即時終了、スタックなし | PATH 上のノードの不一致または間違ったバイナリ | nvm/pm2 ノードを調整します。再実行ドクター |
| YAML/JSON 解析エラー | インデント、エンコーディング、マージジャンク | 構文を検証します。最小限の構成を復元する |
| ポートはすでに使用されています | ゾンビプロセスまたは競合するデーモン | lsof、ポートを解放するか変更します |
| LLM タイムアウト / TLS エラー | プロキシ、DNS、企業 MITM | カール出力テスト。トラストチェーン / HTTPS_PROXY |
| プロセスが存続している間にチャネル認証が失敗する | 期限切れのトークンまたは Webhook URL のドリフト | シークレットをローテーションします。コールバックホストを検証する |
| エージェントスキル EACCES | ファイルシステムのアクセス許可またはサンドボックス | 所有権を修正します。監査スキルスクリプト |
警告：繰り返しを避けるsudo npm install -gプロセス モデルを理解していないと、ランタイムが間違ったモジュール ツリーを解決しているにもかかわらず、グローバルが「インストール済み」と報告する可能性があります。
設置の消火と長期にわたる信頼性は隣接する分野です。1 つ目は再現可能なコールド スタートを最適化し、2 つ目はクラッシュ回復と監査可能性を最適化します。これらの測定可能なプロンプトは、上流のドキュメントを置き換えることなくレビューに役立ちます。
ノートパソコンが接続できない場合無人そしてゼロダイアログ要件、クラウド セルフチェックによるガーディアン再起動ポリシーの追加、ダッシュボード公開、ログ ローテーション - 運用アンカーを永続的なクラウド プレイブック.
セキュリティリマインダー:決して完全に貼り付けないでください.envファイルをチャットに追加します。期限切れの秘密チャネルと文書の取り消しを使用します。
ラップトップがスリープ、アップデート、共有セッションをやりくりすると、動作中のインストールでは修正できないランダム性が生じます。専用のリージョンに配置されたクラウド Mac ノードにより、「蓋が開いたときに起動する」よりも「毎日起動する」ことが簡単になります。 OpenClaw を配信標準に組み込むチームにとって、通常は、VpsMesh Mac Mini クラウド レンタルの方が適しています。: ネイティブ Apple シリコン、24 時間年中無休のメタル、柔軟なレンタル期間 — マシンの状態ではなくゲートウェイ ロジックにサイクルを費やします。
いつものCWDドリフトまたは環境オーバーライド: pm2/systemd は、対話型シェルとは別のパスをロードします。再びドクターを信頼する前に、セクション 3 の argv と cwd をキャプチャします。
ハートビートと無人 SLA がラップトップで存続することはほとんどありません。読んでください永続的デプロイガイドを使用してください。注文ページそして価格ページ地域向け。
から始めてくださいヘルプセンターSSH/VNC トピックの場合。エスカレーションのために医師の出力とブート ログを保存します。