コンテンツにスキップ
ClickHouse Loom
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

Codex プラグイン

Codex プラグイン

このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.

Codex プラグインは、Claude Code と同じ Loom 連携を Codex に提供します。MCP ツール、セッションを記録してプライマーを読み込むフック、コードシャントが含まれます。スクリプト、スキル、リスティング用アイコン(assets/)は Claude Code プラグインのものから生成したコピーであり、integrations/codex-plugin/hooks/hooks.json の配線だけが異なります。フックと設定項目については claude-code.md を参照してください。例外は Claude Code との違い にまとめています。 プラグインが何をどこへ送信するかについては、データの取り扱い を参照してください。

インストール

codex plugin marketplace add ClickHouse/loom        # or a path to a local clone
codex plugin add loom@loom

プラグインは macOS、Linux(glibc または musl。WSL 2 を含む)、Windows の x86_64 と arm64 で動作します。macOS と Linux では、フックは bin/loom-node を通じて Node を見つけます。ヘッダーヘルパーは PATH 上の node を実行し、見つからない場合はランチャーにフォールバックします。Windows では、どちらも cmd.exe 経由で実行され、Codex の起動時の PATH 上にある node を使用します。

プラグインは独自の MCP エントリ(.mcp.json)を持っています。サーバー URL は ?toolset=core,coding,tracker,tasks 付きで、プラグインのヘッダーヘルパー bin/loom-mcp-headers.mjs が認証します。これに加えて codex mcp add loom を実行しないでください。同じ名前のエントリはプラグインのエントリを置き換え、別の名前のエントリはすべてのツールを二重に一覧表示します。

フックの承認

Codex は、ユーザーが承認した後にのみプラグインのフックを実行します。コマンドが変わる更新の後にも、再度承認が必要です。インストール後に一度 codex を対話的に実行し、Loom のフックを承認してください。Codex は各承認を ~/.codex/config.toml の [hooks.state] 配下に trusted_hash として記録します。承認するまでは MCP ツールは動作しますが、codex exec の場合も含め、セッションはキャプチャされません。

トークン

同じマシン上の単一ユーザーのサーバーにはトークンは不要です。それ以外の場合、ヘルパーとフックは LOOM_API_KEY、~/.loom/config.json、~/.loom/token の順に読み取ります。エージェント(ワークロードトークンを持つ LOOM_CLIENT_ID)は、LOOM_API_KEY が設定されていればそれを使い、設定されていなければ交換したトークンのみを使います。LOOM_SELF_SIGNUP=open のサーバーでは、認証情報のない最初のセッションがマシンをサインアップし、~/.loom/config.json を自動的に書き込みます(LOOM_AUTO_SIGNUP=off で無効になります)。すでに持っているトークンを使うには、次のようにします。

mkdir -p ~/.loom && cat > ~/.loom/config.json <<'EOF'
{ "url": "https://loom.example.com", "token": "<writer JWT>" }
EOF
chmod 600 ~/.loom/config.json

トークンは、ダッシュボードの Settings → Tokens タブ(<server>/settings)から、または loom mint-token --subject you --org <org> --namespaces <ns> --roles writer で取得します。フックには writer が必要で、ツールは viewer でも読み取りができます。詳しくはトークンとグラントを参照してください。

サーバー

Codex のプラグインにはインストールオプションがないため、URL はプラグインの .mcp.json(出荷時は http://localhost:7777)と、フック用の plugin-defaults.json に固定されています。独自のマーケットプレイスを公開するデプロイメントでは、両方を設定し、名前を loom(.agents/plugins/marketplace.json)のままにします。スキルとヘッダーヘルパーは、そのマーケットプレイスのコピーだけを読み取ります。

1 台のマシンで別のサーバーを使う場合は、~/.codex/config.toml のエントリを上書きし(上書きはヘルパーを含めてプラグインのエントリ全体を置き換えます)、フック用に同じ URL を ~/.loom/config.json に記述します。

[mcp_servers.loom]
url = "https://loom.example.com/mcp?toolset=core,coding,tracker,tasks"
http_headers_helper = '''node -e "const f=require('fs'),p=require('path');if(process.versions.node.split('.')[0]<18)process.exit(1);const d=p.join(require('os').homedir(),'.codex','plugins','cache','loom','loom');const k=v=>v.split(/[.-]/).map(x=>x.padStart(9,'0')).join('.');const v=f.readdirSync(d).filter(x=>f.existsSync(p.join(d,x,'bin','loom-node'))).sort((a,b)=>k(a)<k(b)?-1:1).pop();import(require('url').pathToFileURL(p.join(d,v,'bin','loom-mcp-headers.mjs')).href)" || { l="$(ls -d "$HOME"/.codex/plugins/cache/loom/loom/*/bin/loom-node 2>/dev/null | sort -V | tail -1)"; sh "$l" "${l%/*}/loom-mcp-headers.mjs"; }'''

Codex は、macOS と Linux ではヘルパーを sh -c 経由で、Windows では cmd.exe 経由で、縮小された環境(HOME または USERPROFILE、PATH、ロケール、その他いくつか)で実行します。また ${PLUGIN_ROOT} は展開しません。そのためコマンドは、どちらのシェルでも実行できる node -e で始まり、ホームディレクトリの .codex 配下にインストールされている最新の loom@loom のヘッダーヘルパーを読み込みます。sh では、この手順が失敗した場合(その PATH 上の node が存在しない、または 18 より古い、あるいはインストール済みのコピーが見つからない場合)、インストール済みの最新のランチャー(bin/loom-node)にフォールバックします。このランチャーは、HOME 配下のバージョンマネージャーのデフォルトディレクトリや、一般的なインストール先ディレクトリも探します。LOOM_NODE や NVM_DIR などの変数は、ランチャーには渡されません。Windows では、PATH 上の node が実行されます。CODEX_HOME をカスタマイズしている場合は、パスを明示的に記述してください。ヘッダーヘルパーからの Authorization を拒否する Codex ビルド(“returned a reserved header”)では、さらに bearer_token_env_var = "LOOM_API_KEY" が必要で、LOOM_API_KEY を export しておきます。

loom install --client codex --server-url https://loom.example.com --token <JWT> は、bearer_token_env_var と ?toolset=coding を含むこのような上書きを書き込み、フック用に url と token を ~/.loom/config.json に書き込みます(mcp-clients.md)。

各ファイルの場所

項目 場所
MCP エントリ プラグインの .mcp.json。~/.codex/config.toml の [mcp_servers.loom] はこれを全体として上書きします
Bearer LOOM_API_KEY → ~/.loom/config.json の token → ~/.loom/token
フック設定 ~/.loom/config.json の {url, token, namespace?, org?}。LOOM_BASE_URL で上書きされます。url がない場合は plugin-defaults.json
プラグイン ~/.codex/plugins/cache/loom/loom/<version>/

Claude Code との違い

Codex 影響
Read / Grep ツールがなく、ファイルはシェルツールで読み取る コードシャントはシェルツール(Bash、shell、exec_command、local_shell)を監視し、cat、rg、grep -r を検出します。コマンドは文字列でも argv 配列でもかまいません
編集は apply_patch を経由する ファイルコンテキストと影響範囲は、パッチのテキスト(*** Update File: / *** Add File:)から対象パスを読み取ります
transcript_path が存在しない、または Codex 独自の形式の場合がある フックはターンジャーナルを保持します。loom-run が各プロンプトを、loom-conversation が Stop 時に各応答(last_assistant_message)を記録します。作業メモリのノート、run のクローズ、会話プレーン、セッションメモリがこれを読み取ります
ペイロードにターンごとのトークンカウンターがない loom-usage は組み込まれません
SessionEnd フックに与えられる時間は約 1 秒 ここで実行されるのは投げっぱなしのスクリプト(キャプチャ、run のクローズ、セッションメモリ、セッションブリーフ)のみです。会話のターンは Stop 時に送信されます
PostToolUseFailure イベントがない エラーとしてフラグが付いた PostToolUse の結果(is_error、isError、error)は、タイプ error として観測されます
mentor-hint フックはすべてのツールに一致する Loom の hint を持たない結果は無視し、独自のリクエストは行いません
フックは $SHELL -lc 経由で、Windows では cmd.exe 経由で実行される 各コマンドは bin/loom-node を通してスクリプトを起動します。これは、PATH、バージョンマネージャー配下、または通常のインストールディレクトリから Node 18+ を探します。Windows では commandWindows がシステムの PATH にある node を実行します。Codex は 0.131 からこれを読み取ります。それより前のビルドでは Windows 上で sh コマンドが cmd.exe 経由で実行されて失敗するため、Windows には Codex 0.131 以降が必要です
識別子 run ID は cx-<session_id>、デフォルトのエージェントは codex、セッションメモリには source:codex が付きます

SessionStart は startup、resume、clear、compact で発火します。プライマーは stdout に出力され、Codex がこれを開発者コンテキストとして追加します。hooks/hooks.json のすべてのコマンドは、スクリプトの第 3 引数でクライアントを指定します(… PostToolUse codex)。

スキル

プラグインには loom-memory、loom-code、loom-mentor、loom-optimize、loom-session、loom-status、improve-loom-for-my-repo が含まれています。詳細は claude-code.md を参照してください。Codex はプラグインからこれらを読み込みます。名前を指定して呼び出す($loom-status)か、説明文によって自動的に呼び出されるようにします。

プラグインなしの AGENTS.md

プラグインを使う場合は、上記のスキルがコントラクトを担うため、AGENTS.md には何も記述する必要がありません。プラグインを使わない Codex は、リポジトリのルートにある AGENTS.md からエージェント向け指示のブロックを読み込みます。このブロックにはそのリポジトリの名前空間が記載されるため、グローバルな ~/.codex/AGENTS.md には置きません。

ヘッドレス

プラグインを実行するユーザー向けにインストールしてあれば、フックは codex exec の下で実行されます。 プラグインのエントリを使わずに、1 回の実行だけサーバーを指定するには、次のようにします。

codex exec --json \
  -c 'mcp_servers.loom.url="https://loom.example.com/mcp?toolset=coding"' \
  -c 'mcp_servers.loom.bearer_token_env_var="LOOM_API_KEY"' \
  "summarise what we decided about retries"

通常のコーディング作業には ?toolset=coding だけで十分です。ツール一覧を小さくするには &schema_profile=compact を追加します(MCP リファレンス)。スケジュール実行や CI での実行については、ヘッドレスボットガイドを参照してください。

動作の確認

  • codex mcp list に loom が表示されます。最初のツール呼び出しで、ダッシュボードの Settings → Tokens タブにあるトークンの行が緑色に変わります。
  • 1 回のセッションの後:(名前空間でログ記録が有効な場合)ダッシュボードの Conversations ページにその会話が表示され、cx-<session_id> に対する run.get でそのランの observation を確認でき、次回のプライマーはワーキングメモリのノートから始まります。
  • 何も届かない場合:loom-status スキルを実行してください。このスキルは Node ランタイムを確認し、プラグインの bin/loom-client-status.mjs を実行します。Loom のチェックアウトや Python は不要です。loom doctor --client(オペレーター向け CLI)を使うと、配線のチェックも追加されます。

トラブルシューティング

症状 原因 対処
MCP 接続が 401 で失敗する ヘルパーがトークンを見つけられない ~/.loom/config.json を書き込むか、LOOM_API_KEY を export する
MCP 接続が 401 で失敗するが、フックは動作する ヘルパーが Node を見つけられず、LOOM_NODE が渡されない Codex の起動時の PATH に Node のディレクトリを含める。詳細は $loom-status に表示される
「予約済みヘッダーを返した」というエラーが出る この Codex ビルドは、ヘルパーからの Authorization を拒否する bearer_token_env_var = "LOOM_API_KEY" で上書きする
ツールが別のサーバーに接続する 同梱の URL がお使いのデプロイと異なる 上記の config.toml の上書きに加えて、~/.loom/config.json の url を設定する
ツールが二重に表示される 別の名前で 2 つ目の MCP エントリがある 削除する(codex mcp remove <name>)
フックで node: not found と表示される インストール済みのプラグインが Node ランチャーより古い codex plugin marketplace upgrade loom
フックが Node.js 18+ に関する loom: の行を出力する ランチャーが Node 18+ を見つけられない、または古い Node しか見つからない Codex の起動場所で LOOM_NODE=/path/to/node を設定する(macOS、Linux)、または $loom-status を使う
フックが何も書き込まない ビューアートークンを使っている、またはフックが別の url を読んでいる ライタートークンを使う。~/.loom/config.json と LOOM_BASE_URL を確認する
会話ページが空 名前空間で会話ログが無効になっている ダッシュボードの会話ページにある 会話を記録する スイッチ、または conversation.set_logging

関連項目

このページは役に立ちましたか?