Codex Cloudでmiseのバージョン固定が効かない時の対処法

mise install bun が通ったのに bun が command not found になる。Codex Cloud で mise を使っていて、この現象にハマった。

ローカルでは .tool-versions でバージョンを固定しているから油断していた。Cloud 上ではそのまま効かない。

症状

指定した bun や node のバージョンが Cloud 上でズレる。mise install bun が成功しているのに、直後に bun を叩くと見つからない。キャッシュ復元後に依存関係がずれることもある。

どれか一つでも起きていれば、mise のインストールと有効化を混同している可能性が高い。

原因

Codex Cloud は .tool-versions や .mise.toml をそのまま自動適用しない。ローカルと同じ感覚で放置すると動かない。

一番ハマるのは mise install の挙動。mise install bun はバイナリをダウンロードするだけで、シェルにパスを通さない。mise activate か mise exec を別で叩く必要がある。ここを知らないと何度やっても command not found が出続ける。

AGENTS.md に bun を使えと書いても、方針の補助にしかならない。環境構築そのものは別の仕組みで制御する。

setup.sh と maintenance.sh で解決する

Codex Cloud の Environment 設定を Manual setup にして、セットアップスクリプトを自分で書く。

`.tool-versions`

bun 1.3.8
nodejs 25.6.0

`.codex/cloud/setup.sh`

#!/usr/bin/env bash

set -euo pipefail

mise use -g bun@1.3.8
mise use -g node@25.6.0

eval "$(mise activate bash --shims)"
bun install --frozen-lockfile

mise use -g でグローバルにツールを登録してから、mise activate bash --shims で shims 経由のパスを通す。この 2 ステップに分けるのが勘所で、mise install 一発で済ませようとすると失敗する。

`.codex/cloud/maintenance.sh`

#!/usr/bin/env bash

set -euo pipefail

bun install --frozen-lockfile

キャッシュ復元後に走るスクリプト。setup.sh で設定済みのパスが残っている前提で書いている。

運用手順

Codex Cloud の Environment 設定で Manual setup を有効にし、setup script に .codex/cloud/setup.sh、maintenance script に .codex/cloud/maintenance.sh を指定する。Environment のキャッシュをリセットして再作成すれば反映される。

AGENTS.md には補助として Use bun for install/run. Do not use npm unless explicitly requested. を書いておく。

注意点

mise install だけでは bun は実行できない。mise activate か mise exec が必要になる。インストールとシェル有効化は別のステップだという前提で構成を組まないと、同じところでつまずく。

setup script と後続処理は別セッションで動く。PATH に依存する設定は各スクリプト内で完結させた方がいい。maintenance script で bun が見つからなければ、mise exec -- bun ... で回避できる。

まとめ

Codex Cloud で mise を安定させるには、Manual setup で setup.sh と maintenance.sh を自前で用意し、mise use -g と mise activate を組み合わせてパスを通す。mise install だけで済ませようとしないこと。

Codex Cloud が独自 Docker イメージに対応すれば、この回避策ごと不要になるかもしれない。