オンボーディング再設計の実装計画

更新され続けるドキュメント。 このページでは、管理役のオンボーディング再設計を 実装レベルで追跡し、各フェーズが反映されるたびに更新します。最後のフェーズが マージされた時点で、このページをユーザー向けのオンボーディングガイドとして書き直し、 ドキュメントのナビゲーションに追加します。それまでは意図的に docs.json に含めません。

目指す姿

技術者ではないユーザーが openclaw onboard と入力する（またはアプリを開く）と、 一貫した会話主体である OpenClaw、すなわちシステムの管理役（「custodian」は 内部でのみ使用する名称で、ユーザーには常に「OpenClaw」と表示されます）が迎えます。 OpenClaw はユーザーの AI を見つけ、質問する代わりに事前通知したデフォルトですべてを設定し、 エージェントの誕生を目に見えるアイデンティティ確立の瞬間として演出します。その後も永続的に システムの世話役として連絡可能な状態を保ちます。デフォルトで魔法のように動作し、 同意の境界は 1 つだけで、行き止まりはありません。

設計原則（決定済みのため、安易に再議論しないこと）：

• 簡単に取り消せる事前通知付きデフォルトで、進行を妨げる質問を置き換えます。唯一の 必須要件は推論が動作することです。それ以外はすべて任意の提案です。
• 質問ゼロが同意の境界です。「フルアクセス」（推奨）では 検出が通知なしで自動的に行われます。「最初に確認」では、AI のスキャン、 アプリのスキャン、メモリソースのスキャンを含むすべての検出について、 1 回の明示的な同意を求めます。また、一切スキャンしない完全な手動経路も用意します。
• 段階的に知能化する会話型 UI：管理役の画面は AI が動作する前から 存在し（スクリプト化された対話）、経路が検証された瞬間にモデル駆動へ切り替わり、 そのことを明示します。知能があるふりは決してしません。経路の検証前に自由文が 入力された場合は、「まず頭脳を動かせるようにします」と穏やかに応答します。
• 孵化は儀式です。同じスレッド内でアバターが切り替わり、 エージェントが自ら名前を付け、自分の顔を選びます。管理役は階層構造を一度だけ説明します。 「システムについては私に尋ねるか、そのままエージェントに尋ねてください。エージェントが取り次ぎます。」
• 信頼レベルはソースごとに区分します。公式カタログのエントリは 事前選択される場合があります。サードパーティの ClawHub Skills は、モデルの ランキングにかかわらず決して事前選択されず、そのラベルには公開者のコードが インストールされることを明記します。
• 設定済みのインストール環境は不可侵です。オンボーディングを再実行しても、 行われるのは検証だけです。セットアップを再適用したり、Gateway サービスを再起動したりすることはありません。
• ターミナルは質問ではなくフォールバックです。Gateway に到達できる場合は ブラウザのダッシュボードを優先し、「ターミナルとブラウザのどちらを使用しますか？」とは決して尋ねません。
• 性能の低いモデルには簡略化した画面を提供し（自動 localModelLean）、 ツール、コードモード、コンテキストウィンドウといった用語を使わず、平易な言葉で説明します。

現在リリース済みのフロー（フェーズ 1～3 完了後）

新規 macOS インストールでの openclaw onboard の正常系では、Enter キーを押すのは合計 4 回です。

1. セキュリティに関する注意事項 → Enter キーを 1 回押して確認します（保存され、二度と尋ねられません）。
2. 質問ゼロ：「どのようにセットアップしますか？」—「フルアクセス」（推奨） または「最初に確認」。選択は wizard.accessMode として保存され、再実行時には保存済みの 選択がデフォルトになります。保護モードで「手動で設定」を選択すると、 スキャンせずにプロバイダーピッカーへ進み、メモリソースのスキャンも省略します。
3. 検出演出：コーディング CLI、環境キー、ローカルランタイムを検出します。 コーディングエージェントが見つかると軽いコメントを表示し、候補を順番にライブテストして、 失敗は 1 行の概要にまとめて静かに収集します（詳細は「その他のオプションを表示」から確認できます）。 最初に動作した経路をデフォルトとして通知し、キーを 1 回押すだけで完全なピッカーへ移動できます。 他の選択肢を確認したりスキップしたりしても、動作中の経路は維持されます。
4. メモリのインポート提案（Claude Code / Codex / Hermes）。検出を拒否した場合は 省略されます。
5. 新規インストールのみ：標準セットアッププランが自動的に 適用されます（ワークスペース、Gateway サービス、セッション。会話内で「はい」と答えた場合に 実行されるものと同じプランです）。設定済みのインストールでは「セットアップ済み」と表示され、 サービスには一切変更を加えません。
6. アプリの推奨：インストール済みアプリと、検証済みモデルを使用して 公式カタログおよび ClawHub から照合した項目を提示します。公式チャンネル Plugin は あらかじめチェックされ、サードパーティの Skills は警告ラベル付きで任意選択となります。 スキップ可能です。無効化スイッチは wizard.appRecommendations です。
7. 孵化：Gateway に到達できる場合、ブラウザへの引き継ぎとして ダッシュボード URL を開く（GUI）か表示し（ヘッドレス/SSH）、Control UI の接続を待ちます。 「ダッシュボードに接続しました。ブラウザで続行します。」到達できない場合、または --tui を指定した場合は、ブートストラップ孵化メッセージを設定した ターミナル TUI が開き、エージェントが自己紹介します。

リモート Gateway のオンボーディングでは、従来の会話型引き継ぎ （handoffMode: "chat"）を維持します。セットアップはリモート Gateway 上で適用する必要があります。

フェーズ

フェーズ別の実装メモ

フェーズ 1 — アプリの推奨（PR #109668）

• スキャナー：src/infra/installed-apps.ts（TCC を必要としない macOS の列挙。 シンボリックリンクされた .app バンドルも追跡します）。
• 候補：公式カタログ + ClawHub 検索。全体の時間制限は 20s で、 オフライン時はカタログのみの候補へ正常に縮退します。カタログエントリはトップレベルの id を持たないパッケージマニフェストであるため、候補のキーには解決済みの Plugin ID を使用します（実際の同梱カタログに対する回帰テスト済みです。以前 entry.id をキーにした際には、カタログ全体が 1 つに集約され、公式の推奨が すべて失われました）。
• AI マッチャー：検証済みの経路 （src/system-agent/setup-app-recommendations.ts）で 1 回の補完を実行します。管理された バンドル ID マップは使用せず、モデルが偶然の名前の一致を除外します。出力は 解決済みモデル自身の maxTokens 予算によって制限されます（明示的な上限が 渡されない場合、ストリーム層が適用します）。
• サプライチェーン保護：ClawHub の掲載文は公開者が制御でき、 マッチャーのプロンプトに渡されるため、掲載項目が自身を「推奨」として宣伝できます。 事前選択できるのは公式カタログのエントリだけです。ClawHub Skills は常に 明示的なチェックを必要とし、「サードパーティの ClawHub Skill。公開者のコードを インストールします」というラベルが付けられます。
• Node コマンド device.apps（TS Node ホスト、Android エンベロープとの同等性）。 共有はデフォルトで無効です。Gateway の無効化スイッチは wizard.appRecommendations です。
• 提供処理は従来型ウィザードとガイド付き管理役フロー （src/wizard/setup.app-recommendations.ts）に置かれます。ブートストラップ末尾への 移行は引き続きフェーズ 5 の範囲です（サービスはすでに注入可能なインベントリソースを 受け取れます）。1 回限りのセマンティクス（承認されるまでのみ提案し、スキャン結果を保存）も フェーズ 5 のストアとともに導入されます。現時点では再実行すると再度提案されます。
• 併せて修正：カスタム completeSetupInference プロンプトが、 32 トークンの検証プローブ出力上限を継承しないようになりました （SETUP_INFERENCE_TEST_MAX_TOKENS は「OK と返信」のプローブだけに適用されます）。

フェーズ 2 — CLI 管理役の基盤（PR #109841）

• src/commands/onboard-guided.ts でフローを再構成しました。リモート Gateway の オンボーディングでは、handoffMode: "chat" を介して従来のチャット引き継ぎを維持します。
• 質問ゼロでは wizard.accessMode（"full" | "guarded"）を保存します。 再実行時には保存済みの選択がデフォルトになります（デフォルトを受け入れても、 保護モードからフルアクセスへ通知なしで切り替わることはありません）。保護モード + 手動では listManualSetupInferenceOptions（設定/マニフェストのみ、プローブなし）を使用し、 メモリソースのスキャンを省略します。
• 検出：失敗を静かに収集し、概要を 1 行だけ表示します。詳細は 「その他のオプションを表示」から確認できます。コーディングエージェントについて軽いコメントを表示し、 通知済みの経路をデフォルトにします。軽量なセッション数取得用の接続点が用意されるまで、 コメント内のセッション数は延期し、定性的な表現だけを使用します。
• 新規インストール：applySystemAgentSetup（決定論的な会話内の 「はい」）を実行した後、ブートストラップメッセージを設定した launchTuiCli により 孵化します。設定済みのインストール（既存のモデルまたは Gateway 設定がある場合。 ウィザードのタイムスタンプは configure/doctor と共有されているため根拠になりません）では、 検証のみを行い、適用も Gateway サービスの再起動も行いません。適用に失敗した場合は 会話型チャットへフォールバックします。

フェーズ 3 — ブラウザ優先の引き継ぎ（PR #110054、マージ済み）

• src/commands/onboard-browser-handoff.ts は純粋なグラフィカルセッションの 検出（SSH_CONNECTION/SSH_TTY、Linux では DISPLAY/WAYLAND_DISPLAY） と、GUI の 60 秒 / SSH の 300 秒の待機を担う。ガイド付きオンボーディングでは現在、 macOS でのみハンドオフが有効になる。--tui およびその他のプラットフォームでは ターミナルへの退避経路を維持する。Linux/Windows での有効化はフォローアップとする。
• ダッシュボードリンクは、従来の完了処理と同じ resolveAdvertisedControlUiLinks、resolveLocalControlUiProbeLinks、buildOnboardingControlUiUrl ヘルパーを使用する。ブラウザの起動には共有の openUrl ヘルパーを使用する。
• 準備完了のポーリングでは、既存の system-presence RPC を、設定済みの共有シークレットを 提示する CLI モードのループバッククライアントとして使用する。これは、すべての openclaw コマンドが使用する信頼済み経路である。生の共有認証を使用する Control UI クライアントは、 SecretRef Gateway では「device identity required」で拒否される。到達可能性の 事前チェックは待機ループと同じターゲット（およびシークレット）を解決するため、 ゲートと待機処理で認証の判定が食い違うことはない。ハンドオフが完了するのは、 接続済みの openclaw-control-ui/webchat プレゼンス行が起動前の ベースラインより新しい場合のみである（すでに開いているダッシュボードでは 完了できない）。
• gateway.controlUi.enabled: false は、URL が表示される前に処理を短絡する。
• 同じ分離設定の Gateway に対してエンドツーエンドで実証済み：URL の出力 → 実際の ブラウザ接続 → 「ダッシュボードに接続しました — ブラウザで続行します」→ ターミナルへの退避経路なし。以前の「token mismatch」による保留はテストハーネスの アーティファクトだった。以下のテスト手順書を参照。

フェーズ 4 — Web カストディアンサーフェス（マージ済み：#110141、#110242）

• openclaw.chat 上の /custodian ページで、オプションカードコンポーネント （2～4 枚のカード、推奨は最大 1 つ、常にスキップ可能）を使用する。オンボーディングの外枠には ?onboarding=1 を使用し、モデルセットアップの初回実行完了後にここへハンドオフする。
• 構造化された質問は、SystemAgentChatResult 上の型付きで追加的な question フィールドである（オプションごとの reply テキスト。 macOS アプリ/TUI では通常文も常に単独で表示される）。生成元は、オンボーディングの 両方のウェルカムバリアントと、2～4 個の選択肢に限定されたホスト型ウィザードの 選択/確認ステップであり、実際のチャンネルウィザードではカードとして表示される。 PR1 の文字列マーカーによる暫定対応は削除された。
• セッションの所有権は、Gateway URL と提示されたすべての認証情報 （トークン、パスワード、ブートストラップトークン、保存済みデバイストークン。hello の 一時的な切断をまたいでも維持）を単位として設定される。失敗したユーザーターンは 再実行できない。機密入力はそのまま送信され、トランスクリプトではマスクされる。

フェーズ 5 — ハッチとブートストラップ（マージ済み：#110173、#110331）

• カストディアンは名前のないエージェントを作成し（ツール呼び出し）、エージェントの ブートストラップは自身の命名から始まる。PR1 ではセレモニーを 3 段階（名前 → 魂を表す 一文 → Skills に関する質問）に制限し、自分で描くアバター/画像生成の段階的処理 （モデル生成の候補 → プリセットマーク → ロゴを維持）はフォローアップに延期する。同じ スレッド内でアバターを切り替える。爪痕マークは引き続きカストディアン専用とする。 合意したアイデンティティは二重に永続化される。エージェントが読み取る IDENTITY.md/SOUL.md と、チャンネルおよび UI に表示される openclaw agents set-identity である。
• 推奨事項（フェーズ 1 のサービス。一度限りのセマンティクスで保存済みスキャン）は、 ブートストラップファイルが削除される前の最後のブートストラップ手順として提示される： 「最小構成、それとも利便性を最大限にしますか？」ブートストラップは openclaw onboard recommendations --json を介して保存済みの提案を読み取り（不透明なインストール ID のみ）、 選択の処理後に確認済みとするため、二度と質問しない。チャンネル接続ボタンには チャンネルごとのセットアップ手順書が付属する。エージェントは対話形式で 認証情報を収集し、設定の書き込みをカストディアンへ中継する （「OpenClaw に依頼しています…」が標準的な表現）。
• 自己学習は宣言せず質問し、スキルワークショップへの同意確認も兼ねる。 ClawHub のリリースに対する信頼性、スキャン、検証、整合性チェック、および パブリッシャーコードに関する警告を説明する。すべてのリリースが署名済みであるかのように 示唆してはならない。
• 自動ハッチをリリース済み。新規インストール時にセットアップの適用が成功すると、 ハッチを通知してハンドオフする（ターミナル TUI / Gateway クライアントでは open-agent）。Web ページはエージェントチャットに遷移し、 「目を覚まして、友よ！」という下書きが事前入力される。ハンドオフは、書き込み後の 検証が問題なく完了した場合にのみ実行される。削除後にエージェントが 0 件になった場合の 自動処理ではなく提案を行う対応は、引き続きフォローアップの仕上げ項目とする。

フェーズ 6 — カストディアンのプレゼンス（PR1 マージ済み：#110269、コメント/呼び出しは PR2）

• PR1 でリリース済み：デフォルトでピン留めされた「OpenClaw」サイドバー項目 （新規プロファイル。既存ユーザーは保存済みのピンを維持し、カスタマイズ/More から アクセス可能）、「OpenClaw に質問」を Settings の先頭項目として追加、通常の外枠での /custodian 訪問時にケアテイカーの挨拶を要求（オンボーディングのウェルカム バリアントは使用しない）。「セットアップを終了」はオンボーディングモードでのみ表示する。 ドッキングされたインライン Settings ペインには、共有会話ビューの切り出しが必要 （フォローアップ）。
• Clippy のような過剰介入を防ぐガードレール付きのイベント反応型コメント： 重大な変更または失敗した変更のみを対象とし、依頼されない限り Settings の訪問ごとに 最大 1 回。同じイベント接続点により、将来的に認証の機能低下やチャンネルの障害についても カストディアンが代弁できる。
• チャンネル：日常的には非表示（エージェントが中継）。明示的に呼び出した場合、 および同じスレッド内でエージェント停止イベントが発生した場合にアクセスでき、 プラットフォームが許可する場合は独自の名前と爪のアバターを使用する。
• セットアップ時に弱いモデルを検出した場合：localModelLean を自動設定し、 カストディアンが平易な言葉でその旨を伝え、アップグレードを提案する。
• カストディアンは自身の内部ニックネーム（「カストディアンと呼ぶ人もいます。 OpenClaw で構いません」）を認識し、常にエージェントを名前で呼ぶ。

フェーズ 7 — レジリエンス（構築前にオーナーの判断が必要）

当初の構想である「設定がどれほど壊れていてもカストディアンにアクセスできなければならない」は、 リポジトリのセキュリティポリシーと衝突する。ルートガイドでは、設定が構造的に無効な場合、 Gateway は起動を拒否すると規定されており、設定済みだが利用不可のケイパビリティへ 機能低下するのは SecretRef オーナーの障害のみである。無効な設定から何らかの サーフェスを提供することは、実装の詳細ではなくポリシー変更である。次の 2 つの スコープから 1 つを選ぶ：

• オプション A（推奨、ポリシー準拠）：CLI 側の自動 doctor。 Gateway または CLI の起動が既知の形式の無効な設定により失敗した場合、CLI は openclaw doctor --fix の実行を提案（または同意を得て実行）し、その後 1 回だけ再試行して 平易に結果を報告する。Gateway の動作は変更しない。カストディアンには既存の SecretRef 機能低下経路とターミナルを介して引き続きアクセスできる。
• オプション B（オーナーの明示的な承認とセキュリティレビューが必要）： Gateway 最小サーフェスモード。 構造的に無効な設定の場合、カストディアンとの会話と doctor アクションのみを提供するロックダウン済みサーフェスを起動する。これは フェイルクローズの起動契約を書き換えるため、コードを作成する前に独自の 受信保護方針を定義しなければならない。

フェーズ 4～6 の残りのフォローアップ（追跡中、未スケジュール）：ハッチ用のアバター/画像生成の 段階的処理、型付き question フィールドの macOS アプリでの表示、カストディアン用の ドッキングされたインライン Settings ペイン（共有会話ビューの切り出しが必要）、 イベント反応型コメントおよびチャンネル呼び出し/エージェント停止時の復旧 （フェーズ 6 PR2）、弱いモデルに対する localModelLean の自動実行、既存ユーザーの 保存済みサイドバーピンに OpenClaw 項目を採用するかどうか。

テストとランディングの手順書（苦労して得た知見。フェーズ 4～6 の前に読むこと）

• OPENCLAW_STATE_DIR は Gateway サービスを分離しない。 LaunchAgent ラベル（ai.openclaw.gateway）はマシン全体で共有される。分離した状態ディレクトリを 使用する新規インストールのオンボーディングテストは、実際のマシンのサービスを 書き換えて再起動する（ラッパースクリプトは分離ディレクトリ内に配置されるため、その ディレクトリを消去すると次回のサービス起動が失敗する）。新規インストールテストの後は必ず、 実際の環境から openclaw gateway install --force && openclaw gateway restart を使用して復元し、plist を確認すること。製品側の フォローアップ：状態ディレクトリ単位のサービスラベル、または外部サービスを検出する オンボーディング。

• 安全なエンドツーエンドハーネス：分離した設定に gateway セクションを事前設定し（これによりオンボーディングは設定済みインストール経路を通り、 サービスには一切触れない）、予備ポートで単純なトークンを使用して openclaw gateway run を通常のフォアグラウンドプロセスとして実行する。このハーネスにより、 実際のブラウザ接続を含むフェーズ 3 のループを実証した。

• 認証経路は認証情報だけでなく、クライアントのアイデンティティによっても異なる。 プレゼンスやその他のオペレーター読み取りでは、同じ設定から取得した認証情報を持つ CLI モードのループバッククライアントを使用する。トークン認証の Gateway には 共有シークレットが必要である。SecretRef/none の Gateway では、トークンなしで 信頼済みループバック認証へフォールバックできる。Control UI として識別される ブラウザクライアントには、デバイスアイデンティティまたはセキュアコンテキストの ループバック許可が必要である。異なる設定を提供する Gateway に対して認証するプローブ （LaunchAgent の落とし穴を参照）は「token mismatch」で失敗する。このアーティファクトにより、 フェーズ 3 は一時的に保留された。

• 完了プローブ：runSetupInferenceTest は検証プローブを 32 出力トークンに制限する。カスタムプロンプトはこの制限を回避し、モデル自身の maxTokens によって制限される。推論モデルは最初に非表示の推論でその予算を 消費する。テキストが空のターンは通常、そこで予算を使い切ったことを意味する。

• エージェントのランディングには、正確な HEAD に対するホスト型 CI が必要。 負荷の高い CI ワークフローは、組織の負荷状況によっては push 時に キューへ入らない場合がある。メンテナー向けのフォールバックは、PR ブランチに対する リリースゲートのディスパッチである：

  gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>

  実行はブランチ ref 上で行い、 head_sha が一致するようにする必要がある。また、タイトルは CI release gate <sha> となり、scripts/verify-pr-hosted-gates.mjs が これを受け入れる。その後、通常どおり scripts/pr で準備/マージする。

• フォーカスしたテスト以外に CI が適用するゲート：ドキュメントマップ （ドキュメントページを追加した後の pnpm docs:map:gen）、oxlint （no-map-spread、max-lines。ファイルを分割し、抑制はしない）、 check:test-types、knip のデッドコード検出（本番コードが使用するものだけを export し、 テストは公開 API 経由にする）、およびライブテストのシャード分類器 （新しい *.live.test.ts はすべて test/scripts/test-live-shard.test.ts に記載する必要がある）。

決定ログ

• 同意を先に求める方式ではなく、キルスイッチ付きの魔法のようなスキャン（フェーズ 1。永続出力では、スキャン前にモデルと ClawHub の使用を開示し、結果の注記でもそれを繰り返す）。
• Node device.apps コマンドを含む完全な垂直統合（フェーズ 1）。
• サードパーティの ClawHub Skills は事前選択せず、発行元のコードをインストールするものとしてラベル付けする。公式エントリは事前にチェックされる場合がある （フェーズ 1、リリース済みのセキュリティ方針）。
• アクセスカードは 3 枚ではなく 2 枚。同意を選択肢の最初に組み込む（フェーズ 2）。
• ブロッキングボタンではなく、通知を伴う自動孵化（フェーズ 2/5）。
• ブラウザ優先：ターミナルでの孵化はフォールバックであり、「ターミナルか ブラウザか？」とは決して質問しない（フェーズ 3）。
• 管理役は Web/CLI のみではなく、チャンネル上のプレゼンス（呼び出し + 復旧）を得る （フェーズ 6）。
• 孵化は同じスレッド内でアバターを切り替えて行われる。完了後、 アプリは通常の UI に移行する（フェーズ 5）。
• 設定画面は「設定」という名前を維持する。管理役は設定画面に（さらにサイドバーにも）配置され、 設定画面を置き換えない（フェーズ 6）。
• オプションカードには制約がある。選択肢は 2～4 個、推奨は必ず 1 個だけで、 常にスキップ可能。同じコンポーネントをオンボーディングとエージェント質問ツールの 両方で使用する（フェーズ 4）。
• 「OpenClaw に問い合わせています…」が標準的な委任表現である。ソウルは趣向を加えてもよいが、 ツールの説明は簡潔なままにする（フェーズ 5）。
• 弱いモデル向けのトリミングを説明する際、ユーザー向け文言では「コードモード」、「ツール」、 「コンテキストウィンドウ」とは決して表現しない（フェーズ 6）。

既知のギャップとフォローアップ

• LaunchAgent ラベルは状態ディレクトリ単位でスコープされていない（前述のテスト上の落とし穴であり、 実際のマルチインスタンス製品上のギャップでもある）。
• 推奨事項の一度限りのセマンティクスと保存済みスキャン（フェーズ 5）。現在は再実行すると 再度提示される。
• ブラウザへの引き継ぎは macOS のみ。Linux/Windows への対応は保留中。
• セッション数に関する軽妙な文言は定性的なもの。数を示すには、低コストでセッション数を取得できる接続点が必要。
• ブラウザへの引き継ぎ先は通常のダッシュボード。オンボーディングモードの管理役への ディープリンクはフェーズ 4 で導入される。