WSL2 上の Codex から Serena MCP を叩いて VS Code と連携するまでのメモ

はじめに

WSL2 上の Ubuntu で OpenAI Codex（TUI） を動かし、
MCP サーバーである Serena を連携させたうえで、最終的に VS Code の「OpenAI Codex」拡張からも Serena を使えるようにする、という一連の作業を行いました。

この記事でやっていることは、大きく次の 3 つです。

1. WSL2 上の Codex TUI ⇔ Serena MCP の連携
2. Codex 起動時の自動アクティベート
3. VS Code 上の Codex からも Serena を使えるようにする

それぞれを軸に、疑問・問題・解決方法・ログをまとめていきます。

環境

今回の検証環境は次の通りです。

• OS / 実行環境
  • ホスト OS: Windows 10 / 11
  • WSL2: Ubuntu
• Codex
  • 実行形態: CLI / TUI 版（codex コマンド）
  • バージョン: OpenAI Codex (v0.64.0)
  • 設定ファイル: ~/.codex/config.toml
• Serena
  • インストール・実行: uvx 経由
  • 設定ファイル: ~/.serena/serena_config.yml
• エディタ / IDE
  • VS Code（Remote – WSL 経由で Ubuntu 上のディレクトリを開く）
  • 拡張機能: OpenAI Codex

WSL2 上の Codex TUI ⇔ Serena MCP の連携

まずは、WSL2 上の Codex TUI から Serena MCP を利用できるようにする手順と、
そこで発生した問題・解消方法をまとめます。

Codex 側で Serena MCP を登録する

初期状態の ~/.codex/config.toml（抜粋）は次のようなものでした。

model = "gpt-5-codex"
model_reasoning_effort = "high"

[tools]
web_search = true

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]

[projects."/home/{ユーザー名}/TestProject"]
trust_level = "trusted"

ここに Serena 用の MCP サーバー定義を追記します。

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server", "--context", "codex"]

あわせて WSL2 上で uv / uvx をセットアップしておきます。

curl -LsSf https://astral.sh/uv/install.sh | sh echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

which uvx  # /home/{ユーザー名}/.local/bin/uvx などが返ってくればOK

Codex 起動時に Serena がタイムアウトする問題

この状態で codex を実行すると、起動時に以下の警告が出ました。

⚠ MCP client for `serena` timed out after 10 seconds. Add or adjust `startup_timeout_sec` in your
  config.toml:
  [mcp_servers.serena]
  startup_timeout_sec = XX

⚠ MCP startup incomplete (failed: serena)

Serena を 手動で起動すると正常に立ち上がっているのに、
Codex から起動すると「10 秒待っても応答がない」という扱いになっています。

Serena を手動起動したときのログ（一部）は次の通りです。

uvx --from git+https://github.com/oraios/serena \
    serena start-mcp-server --context codex

INFO  ... Initializing Serena MCP server
INFO  ... Loading Serena configuration from /home/{ユーザー名}/.serena/serena_config.yml
INFO  ... Starting Serena server (version=0.1.4-..., process id=...)
INFO  ... Available projects: TestProject
INFO  ... Serena web dashboard started at http://127.0.0.1:24283/dashboard/index.html
INFO  ... Starting MCP server with 23 tools: [...]
INFO  ... MCP server lifetime setup complete

ログ上は MCP サーバーとして正常起動しており、Codex との間のハンドシェイクで詰まっていることがわかります。

startup_timeout_sec では解決しなかった

まずは素直に Codex 側のタイムアウト時間を伸ばしました。
~/.codex/config.toml:

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server", "--context", "codex"]
startup_timeout_sec = 30

しかし、結果は

⚠ MCP client for `serena` timed out after 30 seconds

と、メッセージ内の秒数が変わっただけで、本質的な改善にはなりませんでした。

解決策: Web ダッシュボードを無効にする

調査していくと、以下のような既知のパターンに一致していることが分かりました。

• Serena の Web ダッシュボード機能が有効な状態だと、Codex や Claude からの MCP 接続がタイムアウトするケースがある
• --enable-web-dashboard=false を付けて起動すると解消する

そこで、Codex の config.toml を次のように修正しました。

[mcp_servers.serena]
command = "uvx"
args = [
  "--from", "git+https://github.com/oraios/serena",
  "serena", "start-mcp-server",
  "--context", "codex",
  "--enable-web-dashboard=false"
]
startup_timeout_sec = 30

この設定にした上で Codex を起動すると、Serena のタイムアウト警告が消え、
/mcp コマンドで次のように表示されるようになりました。

• serena
  • Status: enabled
  • Auth: Unsupported
  • Command: uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context codex --enable-web-dashboard=false
  • Tools: activate_project, check_onboarding_performed, find_file, find_symbol, ...

この時点で

• Codex から Serena MCP が正しく起動・認識されている
• Serena のツール一覧が見えている

という状態まで持っていくことができました。

起動時の自動アクティベート（Activate the current dir as project using serena）

次のテーマは 「プロジェクトのアクティベート」を自動化することです。

.serena があっても Activate は必要？

Serena をすでに Claude で利用していたため、
例えば ~/TestProject/.serena はすでに存在している状態でした。

ここでの疑問は、

.serena が存在している場合でも、Codex で
「Activate the current dir as project using serena」を実行する必要があるのか？

という点です。

結論としては、必要でした。

• .serena がある → プロジェクトの解析結果・メモリなどはすでに存在する
• とはいえ 「今この Codex セッションでどのプロジェクトを使うか」 は、毎回 Serena に教える必要がある

手動で Activate したときのログ

TestProject ディレクトリで Codex を起動し、
チャット欄から次のように入力します。

Activate the current dir as project using serena

すると、以下のようなログが表示されました。

• Called serena.activate_project({"project":"."})
  └ The project with name 'TestProject' at /home/(ユーザー名)/TestProject is activated.
    Programming languages: php; file encoding: utf-8
    Available project memories: ["task_completion_checklist", "suggested_commands", "codebase_structure",
        "project_overview", "code_style_and_conventions"]

• Called serena.check_onboarding_performed({})
  └ The onboarding was already performed, below is the list of available memories.

.serena があるのでオンボーディングはスキップされ、

「このセッションでは TestProject をアクティブプロジェクトとする」状態になったことがわかります。

毎回手で打つのは面倒 → startup_messages で自動送信

毎回同じ文言を打つのは面倒だったので、
Codex の startup_messages 機能を使って 起動直後に自動送信させることにしました。

~/.codex/config.toml の末尾に以下を追加します。

messages = [
  { role = "user", content = "Activate the current dir as project using serena" }
]

最終的な設定ファイルのイメージは次のようになります。

model = "gpt-5.1-codex-max"
model_reasoning_effort = "high"

[features]
web_search_request = true

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]

[mcp_servers.serena]
command = "uvx"
args = [
  "--from", "git+https://github.com/oraios/serena",
  "serena", "start-mcp-server",
  "--context", "codex",
  "--enable-web-dashboard=false",
]
startup_timeout_sec = 30

[projects."/home/{ユーザー名}/TestProject"]
trust_level = "trusted"

[notice]
"hide_gpt-5.1-codex-max_migration_prompt" = true

[startup_messages]
messages = [
  { role = "user", content = "Activate the current dir as project using serena" }
]

Codex を起動すると、画面上には応答が出ない場合もありますが、
~/.codex/log/codex-tui.log を確認すると起動直後に

Called serena.activate_project({"project":"."})

が出力されており、裏で自動的にアクティベートされていることがわかります。

その後、「Serena のツールを使って、このリポジトリのディレクトリ構造をざっくり教えて。」といった依頼をすると、Codex の出力の中で serena.list_dir などのツール呼び出しが行われるようになり、
自動アクティベートが効いていることを確認できました。

VS Code 上の Codex から Serena を使えるようにする

最後のテーマは、VS Code の「OpenAI Codex」拡張から Serena MCP を叩けるようにすることです。

VS Code に OpenAI Codex 拡張をインストール

1. Windows 側で VS Code を起動
2. Extensions から「OpenAI Codex」を検索
3. Publisher が OpenAI の公式拡張をインストール

Remote – WSL で Ubuntu に接続

VS Code の Remote WSL 機能を使って、Ubuntu 上のプロジェクトを開きます。

1. 左下の「><」アイコンから WSL: Ubuntu に接続
2. File > Open Folder で ~/TestProject を開く

この状態で VS Code を利用すると、

• VS Code 内の Codex 拡張も WSL 側のホームディレクトリを使う
• つまり、CLI 用に設定した ~/.codex/config.toml をそのまま共有できる

という形になります。

VS Code 上で Serena が見えているか確認

VS Code 側の Codex ビューを開いて、Serena が MCP として認識されているかを確認しました。

• mcp_servers.serena の設定が CLI と同じように参照されている
• startup_messages によって起動時に自動で「Activate the current dir as project using serena」が送られている
• 実際に「Serena のツールを使って〜」と依頼すると、背後で serena.find_symbol などが呼ばれている

結果として、

• WSL2 上の Codex TUI と同じ Serena MCP を
• VS Code の Codex 拡張からも利用できる

ことを確認できました。

ハマりどころと学び

最後に、今回の 3 テーマを通じてハマったポイントと学びを簡単にまとめます。

Codex TUI ⇔ Serena MCP 連携

• Serena がログ上は起動しているのに Codex からはタイムアウトする場合、
  • startup_timeout_sec だけでなく
  • --enable-web-dashboard=false を付ける、という切り口がある
• codex mcp list と ~/.codex/log/codex-tui.log の両方を見ることで、
  「どこまでうまくいっているか」の切り分けがしやすい

起動時の自動アクティベート

• .serena がすでに存在していても、セッションごとの「アクティブプロジェクト」は別問題
• Codex では「Activate the current dir as project using serena」を使うことで、
  セッション内で利用するプロジェクトを明示する必要がある
• startup_messages でこのフレーズを自動送信することで、
  起動のたびに手入力する手間をなくせる

VS Code 上の Codex 連携

• Remote – WSL を使って VS Code から Ubuntu 環境に接続すると、
  CLI 用の ~/.codex/config.toml を VS Code 拡張と共有できる
• MCP 設定を 1 箇所（config.toml）にまとめておけば、
  • ターミナルの Codex TUI
  • VS Code の Codex 拡張
    の両方から Serena MCP を呼べるようになり、構成がシンプルになる

おわりに

この記事では、

1. WSL2 上の Codex TUI ⇔ Serena MCP の連携
2. Codex 起動時の自動アクティベート
3. VS Code 上の Codex からも Serena を使えるようにする

という 3 つの観点で、設定・ハマりポイント・ログをまとめました。

特に、大きなコードベースを扱うときに Serena の find_symbol / get_symbols_overview / find_referencing_symbols といったツールは非常に強力なので、大規模な PHP / Rails / Laravel プロジェクトを読み解くときにかなり強力と感じました。

同じように WSL2 上の環境で Codex と Serena を連携させたい方の参考になれば幸いです。