codex-browser-fix

Codex Browser Fix

Codex 専用です。デスクトップアプリには、ChatGPT 拡張機能を通じて任意の Chromium ブラウザーを操作する Chrome プラグインがバンドルされています。これを妨げる問題が 2 つありますが、ベンダーのスキルではどちらも扱っていません。

症状	原因	修正
拡張機能が検出された後に Codex auth token is unavailable が発生する	config.toml でカスタムの model_provider が設定されています。ブラウザーヘルパーは codex app-server を起動してその設定を引き継ぐため、ChatGPT のサインイン情報が認識されません	プリフライトでランチャーをインストールし、そのサブプロセスに限ってプロバイダーを上書きします
昨日は拡張機能が見つかったのに、今日は見つからない、またはエラーになる	デスクトップアプリが更新され、~/.codex/plugins/cache/openai-bundled/chrome が古いバンドルを参照したままになっています	プリフライトでキャッシュと信頼ハッシュを、インストール済みアプリに合わせて再同期します
ユーザーが Chrome や Edge 以外の Chromium ブラウザー（Brave、Vivaldi、Opera）を指定したのに、エージェントが Chrome を選択した	ベンダーのスキルには chrome と edge しか記載されていません。他のファミリーには list() による照合が必要です	family で選択します（以下を参照）

インストール済みの Chrome プラグイン独自のスキル（アプリバンドル内の skills/control-chrome/SKILL.md）が、ブラウザー API の正式な参照元です。このスキルでは、ローカルのセットアップ、復旧、ブラウザーファミリーの選択を扱います。

適用するタイミング

• ユーザーが、タブやサインイン情報を必要とするタスクで Brave、Vivaldi、Opera、Edge、Chrome、または「自分のブラウザー」を指定した場合
• Chrome プラグインで Codex auth token is unavailable エラーが発生した場合
• ブラウザーの検出で拡張機能への接続が見つからない場合、または ChatGPT や Codex デスクトップアプリの更新直後に失敗する場合
• 「ブラウザーのセットアップを確認して」／「ブラウザーの接続を修正して」と依頼された場合

ワークフロー

1. プラグインのプリフライト

browser-client.mjs をインポートする前、またはブラウザーを選択する前に実行します。Bun と ChatGPT または Codex デスクトップアプリが必要です。<skill-dir> はインストール済みのスキルフォルダーです（Codex のデフォルト：~/.codex/skills/codex-browser-fix）。

bun "<skill-dir>/scripts/browser-plugin-preflight.mts"          # sync + verify
bun "<skill-dir>/scripts/browser-plugin-preflight.mts" --check  # read-only verify

usage: browser-plugin-preflight.mts [--check] [--plugin-dir <dir>]
  --check             verify only, nothing written; exit 1 on drift
  --plugin-dir <dir>  the bundled Chrome plugin directory of a non-standard install
the codex home is $CODEX_HOME or ~/.codex
exits: 0 synchronized, or verified current; 1 a missing file or a stale setting; 2 usage

アプリバンドルのバージョン、browser-client.mjs のインポート元となるプラグインのパス、同期されたキャッシュが表示されます。デスクトップアプリを更新または再起動するたびに、再実行してください。

失敗すると、不足しているファイルまたは古い設定を示して終了コード 1 で終了します。--check の場合も、config.toml、バンドル、または実行可能ファイルが存在しないときは、成功ではなくエラーになります。

変更するのは以下だけです（<home> は codex のホームディレクトリです）。

• <home>/plugins/cache/openai-bundled/chrome：既存の固定バージョンの各エントリー、現在のバージョンのエントリー、latest リンクが、インストール済みのアプリバンドルに追従します。<home>/plugins/cache/openai-bundled/browser：現在のバージョンに対応するコピーと、その latest リンクのみが対象です。置き換えられた古いコピーは <home>/plugin-rollbacks/ に移されます。
• <home>/config.toml の [mcp_servers.node_repl.env]：CODEX_CLI_PATH、アプリのバージョン、信頼済みコードパスが対象です。[shell_environment_policy.set] の下では、browser-client.mjs` のハッシュが対象です。各値は、すでにその場所に割り当てられている必要があります。編集後に解析検証を行い、それ以外は変更されていないことを確認します。
• <home>/scripts/browser-codex：生成されるランチャーです。app-server サブコマンドに限り、-c 'model_provider="openai"' を追加します。それ以外のすべてのサブコマンドは変更せずに渡されます。メインのプロバイダー、CODEX_HOME、認証情報には触れません。
• 各 <home>/hosts/<host>/：個別の plugins/cache/openai-bundled/browser 対応キャッシュと、config.toml がある場合は同じ設定変更および個別の scripts/browser-codex が対象です。Chrome キャッシュはグローバルでのみ管理されます。

2. ベンダーの手順でブートストラップする

インストール済みの control-chrome スキルに従い、その node_repl JavaScript ツールを使用します。プリフライトで表示されたパスから browser-client.mjs をインポートし、setupBrowserRuntime() を一度呼び出して、ターンをまたいで agent とブラウザーのバインディングを再利用します。動作中のセッションをリセットしてセットアップを繰り返さないでください。

3. ブラウザファミリーを選択する

Chrome と Edge にはベンダーセレクターがあります：agent.browsers.get("chrome") と agent.browsers.get("edge")。それ以外の Chromium ファミリーは、次のリストから照合します：

// Declared once per session; call it again with a profile name after asking.
async function selectExtension(family, profileName) {
  const label = (c) => c.profileName ?? c.name; // the name shown when asking
  const candidates = (await agent.browsers.list()).filter(
    (c) =>
      c.type === "extension" &&
      c.family === family &&
      (profileName === undefined || label(c) === profileName),
  );
  if (candidates.length === 0) throw new Error(`No connected ${family} extension`);
  if (candidates.length > 1) {
    const profiles = candidates.map(label).join(", ");
    throw new Error(`Several ${family} profiles connected (${profiles}); ask which one`);
  }
  return agent.browsers.get(candidates[0].id);
}
let browser = await selectExtension("<family>", undefined); // the family the user asked for; ("<family>", "Work") once the profile is known
nodeRepl.write(await browser.documentation());

• 候補がない場合：ユーザーの言葉でブラウザを利用できないと伝えます（拡張機能がない、または接続が切れています）。候補が複数ある場合：どのプロファイルかを尋ね、その名前を指定して selectExtension を再度呼び出し、browser を再割り当てします。決して推測しないでください。
• ファミリー名はプラグインの scripts/extension-ids.json に従います：brave、chrome、edge、opera、vivaldi。
• ブラウザの明示的な指定は必須条件です。プラグイン名が Chrome だからといって Google Chrome に置き換えたり、Computer Use や新しいブラウザに切り替えたりしないでください。
• 選択後、ベンダースキルの指示に従って documentation() の出力全体を読み、セッションに名前を付けてから、browser.user.openTabs() にあるタスクに一致する正確なタブオブジェクトを取得します。
• 古いタブや閉じられたタブの場合は、既存のブラウザバインディングから新しいタブを取得します。明示的な切断があった場合、またはユーザーが切り替えを求めた場合にのみ、ブラウザを再選択します。

4. 作業して引き継ぐ

• 操作する前にページを確認します。意味のある操作を行うたびに状態を再確認します。クリックやアップロードが完了しても、結果が保存されたとは限りません。成功を報告する前に、ページ上で各フィールド、メディア、保存状態を確認します。
• 写真やドキュメントをアップロードする前に、ベンダーのアップロード手順を読みます。
• ベンダーの引き継ぎルールに従ってタブを維持します。ブラウザーのストレージにはローカルの下書きやサインイン状態が保存されているため、決して消去しないでください。
• 接続の設定によって、ほかの操作が許可されるわけではありません。アプリケーション、メッセージ、購入、公開には、引き続き現在のリクエストとプロジェクトの承認ルールが適用されます。

復旧

• Codex auth token is unavailable、検出結果が空、キャッシュまたは信頼性に関するエラーが発生した場合：事前チェックを実行してから、復旧手順を読みます。
• ブートストラップが正常に完了した後に検出または選択に失敗した場合：await agent.documentation.get("bootstrap-troubleshooting")。
• 拡張機能のインストールまたは通信に失敗した場合：await agent.documentation.get("chrome-troubleshooting")。
• 実行中のブラウザーヘルパーは、起動時の環境を維持します。新しいランチャー設定は、そのヘルパーが次回起動したときに反映されます。適用するために、正常に動作している接続を終了しないでください。

決して行わないこと：メインの model_provider を無効にしてから再び有効にする、トークンをコピーする、アプリのバイナリにパッチを適用する、または推測でコンポーネントを再インストールする。実際にサインインが必要な場合は、ユーザー自身で対応する必要があると伝えてください。

デスクトッププラグインを利用できない場合のフォールバック

事前チェックの --check は MCP ホストとは無関係に、Bun があればどのターミナルからでも実行でき、欠けているバンドル、キャッシュ、設定を報告します。役立つ場合は、タスクに必要な素材をローカルで準備してください。

ライブブラウザーの作業は、Chrome プラグインと要求されたブラウザー接続を備えたデスクトップ Codex セッションでのみ再開できます。別のブラウザーや自動化トランスポートで代用しないでください。

参考資料

• references/recovery.md：認証インシデントの事例、事前チェックで同期される内容、拡張機能とタブの障害の切り分け
• scripts/browser-plugin-preflight.mts：唯一のセットアップ実装（同期と --check）
• scripts/browser-auth-launcher.mts：ランチャー生成ツール。上流でユニットテスト済み（https://github.com/Vivswan/skills, tests/skills/codex-browser-fix/browser-auth-launcher.test.ts）
• scripts/codex-config-toml.mts：config.toml の編集。上流でユニットテスト済み（https://github.com/Vivswan/skills, tests/skills/codex-browser-fix/codex-config-toml.test.ts）