コーディングエージェント本体を「安い互換バックエンド」で走らせる

LLM を直接叩く部分を安いモデルに逃がす話ではない。コーディングエージェントの CLI そのものを、 API 互換のある別プロバイダのエンドポイントに向けて走らせ、エージェント実行のコストを下げる話。

エージェント CLI の多くは接続先を環境変数で差し替えられる。互換エンドポイントを出しているプロバイダなら、 CLI を書き換えずにバックエンドだけ swap できる。ただし素直にやると4種類の壊れ方をする。 実際に踏んだものと、その回避策・検証手順をまとめる。

全体像

監督エージェント（高品質・高単価）
   └─ ラッパー（このMDで作るもの）
        └─ spawn: エージェントCLI -p "<指示>"
             env: BASE_URL=<互換エンドポイント> / AUTH_TOKEN=<安いプロバイダのキー>

ラッパーがやることは3つだけ。接続先の解決、子プロセスの env 組み立て、使用量の記録。

罠1（最重要）: env をグローバルに書くと監督ごと切り替わる

process.env.BASE_URL = ... と書いたり、CLI の設定ファイルに保存すると、 監督セッション自身が気づかないうちに安いモデルで動き始める。品質が落ちた理由が誰にも分からなくなる。

必ず spawn する子プロセスの env にだけ渡す。

export function buildChildEnv(config, key, parentEnv = process.env) {
  const env = { ...parentEnv, BASE_URL: config.base, AUTH_TOKEN: key };
  if (config.maxContextTokens) env.MAX_CONTEXT_TOKENS = String(config.maxContextTokens);
  return env;
}

spawn(CLI, ['-p', prompt, '--model', model], { cwd, env: buildChildEnv(config, key) });

テストで親の process.env が汚れていないことを必ず assert する。これは1行で書けて、事故は致命的。

const env = buildChildEnv(cfg, 'DUMMY', { PATH: 'x' });
assert.equal(env.BASE_URL, cfg.base);
assert.equal(process.env.BASE_URL, undefined);   // 親が汚れていない

罠2: カタログ外のモデル名だとコンテキスト窓を誤って小さく仮定される

エージェント CLI は自分が知っているモデル名の一覧を持っており、そこに無い名前を渡すと 「安全側の既定値（例: 200k）」を窓として仮定する。実際のモデルが 1M 持っていても、 CLI は 200k で自動要約（auto-compact）を始めるので、長い作業ほど無駄に文脈を捨てる。

対策は、実際の窓を環境変数で明示すること。CLI が出す警告文に、その変数名が書かれていることが多い。

// プロバイダ定義に実窓を持たせる
{ base: '<互換エンドポイント>', defaultModel: '<実モデル名>', maxContextTokens: 1000000 }

検証方法: 明示前は警告が出て、明示後は消える。消えたことをもって「効いた」と判断する。 窓の値はプロバイダの公式 pricing / model ページに書いてある（推測しない。桁を間違えると逆効果）。

罠3: 別名モデル（エイリアス）を既定にしない

<provider>-chat のような総称エイリアスは、プロバイダ側の都合で将来どの世代に張り替わるか読めない。 実際、エイリアスを指定したのに応答の model フィールドには別の実モデル名が入って返ってくる。

既定は実モデル名にし、上位モデルは --model で明示的に選ばせる。 応答 JSON の model フィールドを1回見れば、何が実際に動いたか分かる。

罠4: 契約が「どのアカウントに付いたか」は推測せず実測する

複数アカウントを持っていると、決済したアカウントと、手元のキーが一致しない事故が起きる。 アカウント名から推測しない。両方のキーで同じリクエストを投げ、200 が返る方が契約側。

for key in <キーA> <キーB>; do
  curl -s -o /dev/null -w "%{http_code}\n" <互換エンドポイント> -H "x-api-key: $key" -d '<最小リクエスト>'
done

契約が無い側は「残高不足 / リソースパッケージ無し」系のエラーコードを返す。 このエラーは「対象外のツールから叩いた」ときにも同じコードで返ることがあるので、 エンドポイントが公式サポート対象かも併せて確認する（公式FAQに一覧がある）。

罠5: 決済がカードで全滅しても、支払い手段を変えると通ることがある

海外プロバイダの決済で、同じカードが金額を変えても全部落ちることがある。 このとき「そのサービスは契約できない」と結論するのは早い。エラーメッセージで切り分ける。

メッセージ	意味	打ち手
card was declined	発行会社が拒否	金額を下げる（年払い→月払い）、海外利用制限を解除
processing error	決済処理の失敗	拡張機能を切る、時間を空ける
unable to authenticate your payment method	本人認証(3-D Secure)が成立していない	カード側で本人認証を登録。別の支払い手段に変える

最小額でも落ちるなら金額の問題ではない＝カードと決済代行の相性なので、 カードを変えるより先に PayPal 等の別手段を探す。実例では、カードは全パターン失敗したのに PayPal に切り替えた瞬間に通った。

補足: 本人認証はサードパーティ Cookie を使うため、シークレット/プライベートウィンドウでは失敗しやすい。 「拡張機能が怪しいからシークレットで」は本人認証を壊す方向に働く。拡張機能を疑うなら シークレットではなく通常ウィンドウで拡張機能だけ個別にオフにする。

使用量を記録する

安いレーンに逃がした量を後から測れないと、削減できているか判断できない。 ラッパーの最後に1行追記するだけでよい。キーは絶対に書かない。

const entry = { t: new Date().toISOString(), provider, model,
                in: Math.ceil(prompt.length / 4), out: Math.ceil(outputChars / 4),
                secs: Number(secs.toFixed(3)) };
fs.appendFileSync(ledgerPath, `${JSON.stringify(entry)}\n`, 'utf8');

完了と言う前の検証手順

1. --dry-run … 接続先・モデル・キーの有無だけ（値は出さない）を表示して確認
2. 実タスクを1件通す … 答えが決まっている極小の指示（例: 「7 とだけ返せ」）。exit code も見る
3. 使用量の記録が1行増えたか
4. 罠2の警告が消えたか
5. テストが通るか（課金される API は叩かない設計にする）

テストを課金なしにするコツは、接続先の解決と env 組み立てを spawn から切り離して export すること。 この2つを純粋関数にすれば、キーが無い環境でも全ケース検証できる。

期待値（正直な限界）

• 速くはない。互換バックエンド経由のエージェント実行は、些末な指示でも 1.5〜2 分かかった実測がある。 人が待つ対話用ではなく、夜間バッチ・機械的な一括作業向け。
• 品質は上位モデルに劣る。判断を伴う作業は監督に残す。機械的な変換・整形・定型実装だけ流す。
• 定額プランの多くは契約者本人の利用に限定され、共有・再配布が規約で禁止されている （違反すると返金なしで凍結される条項が普通）。キーを配布物に埋め込まない。 複数台で使いたければ台数分契約する。

チェックリスト

• env は子プロセスにだけ渡している（親の汚染をテストで assert）
• 実モデル名を既定にしている（エイリアスを既定にしていない）
• 実コンテキスト窓を明示し、警告が消えたことを確認した
• キーを標準出力・ログ・使用量記録に出していない
• 実タスクを1件通して exit code を確認した
• テストが課金 API を叩かない
• 規約上の共有可否を確認し、配布物にキーを埋めていない