OpenClaw ゲートウェイ資格情報と層別切り分けの概念図

2026 年 OpenClaw 初回 onboard 後も壊れる：credentials、環境変数の優先度、モデルプロバイダ切替の最小ループと層別ランブック

onboard が成功しても、本番でゲートウェイが安定するとは限りません。ゲートウェイを動かす Unix ユーザーが同じ ~/.openclaw/credentials/ を読めるか、systemd の EnvironmentFile がデーモン起動前に注入されているか、そしてモデル ID のプレフィックスが選択中のプロバイダと一致しているかが、「CLI では chat できるのにゲートウェイでは 401/429」という分岐を作ります。RPC と probe については《公式トラブルシューティング（gateway probe）》、接続とバージョンは《pairing》《split brain》《Docker Compose とトークン》を参照してください。

目次（TOC）

1. 三つの分岐：HOME のずれ、空の credentials、プロバイダ文字列

HOME のずれ：対話シェルでユーザー A が onboard し、launchctl や systemd はユーザー B でゲートウェイを起動していると、A には存在する credentials が B からは見えません。

空ディレクトリ：ディレクトリはあるが鍵ファイルが無いと、doctor の警告が弱く、実際の 401 はモデル呼び出しまで遅れます。

プロバイダの不一致：設定のモデル文字列と openclaw models status の実ルートが食い違うと、ログに provider mismatch 系の署名が出ます。429 や無返信の切り分けは《チャンネル緑でも無返信》と併読すると層を取り違えにくくなります。

  1. まずゲートウェイの実行ユーザーを確定する。
  2. 次に環境変数と JSON の上書き関係を揃える。
  3. 最後に429 とチャンネル挙動を見る。

2. 意思決定表：API Key、OAuth、複数プロバイダ

複数箇所に矛盾する API Key を置かず、単一の正を維持してください。そうしないと「手動シェルでは成功、サービスでは古い値」という偽陽性が残ります。

観点 API Key ファイル OAuth／ブリッジ 複数プロバイダ
秘密の置き場 credentials + chmod 600 リフレッシュとコールバック URL ファイル分割または env プレフィックス
デーモン向け EnvironmentFile で明示 ジョブは同一ユーザー ルーティングは単一の正
切り分け順 ls の後に doctor OAuth ログの後にモデル models status の後に channels

3. How-to：onboard 後の七ステップ最小ループ

# 1) ゲートウェイのユーザーと HOME を確認
ps aux | grep -i openclaw
echo "$HOME"
ls -la ~/.openclaw/credentials/
  1. plist や unit の User= と WorkingDirectory を変更票に記載する。
  2. 最小権限で credentials を保護し、誤コミットを防ぐ。
  3. 同一シェルで openclaw status と openclaw gateway status を実行し PATH のずれを避ける。
  4. 環境変数変更後はゲートウェイを完全再起動する（ホットリロードだけでは不十分な場合がある）。
  5. プロバイダ切替は最小差分：モデル文字列・ルートブロック・ファイル名を同時に揃える。
  6. openclaw doctor のマスク済み出力を保存する。
  7. 資格情報層が揃ったら公式階段に沿って gateway probe と channels を取る。
# 2) systemd 例：OPENCLAW_HOME を明示
Environment=OPENCLAW_HOME=/home/oc/.openclaw

4. 層別切り分けとログで探す語

推奨順は openclaw status → openclaw gateway status → openclaw doctor → ログの 401 403 429 credential provider です。RPC が緑でも無返信なら上記のチャンネル記事でプラグインの二重トグルを確認します。

split brain：gateway status --deep で CLI とサービスのバイナリパスが食い違う場合は PATH とインストールを先に直します。which openclaw が unit 内と違うときは《インストール経路の比較》を先に読み、credentials の議論に進みます。

5. チケットに残すフィールド

実行ユーザー、credentials のファイル名一覧（マスク可）、doctor の要約、モデル文字列一行、最後にフル再起動した時刻、設定 tarball のハッシュがあるとロールバックが容易です。Docker 利用時はコンテナ uid とボリュームマッピングを Docker Compose 記事に合わせて記載してください。

6. FAQ

問：Docker で credentials をマウントするには？答：Docker Compose 記事の uid とボリューム節を参照してください。

問：doctor を省略してよいか？答：非推奨です。低レベルエラーの多くを集約します。

7. まとめとリモート Mac への収束

資格情報層が揃うと、ゲートウェイは再現可能な環境でモデルとチャンネルを安定して呼び出せます。ノート PC のスリープや複数 HOME による揺らぎは別問題なので、観測ウィンドウをチケットに明記してください。

常時ゲートウェイと監査可能なディレクトリ構成を標準にしたい場合は SFTPMAC リモート Mac の資料も参照してください。公式階段と本文は補完関係であり、資格情報が未整合のまま 429 だけを追うのは避けてください。