1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code の Code Mode が「ゲートウェイ経由では起動しない」件と、「トークン 37% 削減」の出どころ

1
Posted at

Claude Code v2.1.323(2026-11-12)で、実験的な Code Mode が入りました。Claude がツールを 1 回ずつ呼ぶ代わりに JavaScript を書き、その中で複数のツール呼び出しをまとめて実行する機能です。

タイムラインでは「トークンが 37% 減る」という数字と一緒に回ってきました。ところが、OpenAI 互換や Anthropic 互換の API ゲートウェイ経由で Claude Code を使っている環境では、そもそも起動しません。公式ドキュメントにそう書いてあります。

この記事では次の 3 点を、公式ドキュメント(2026-11-16 確認)をもとに整理します。

  1. Code Mode が何をしているか
  2. 「37% 削減」はどこから来た数字か
  3. ゲートウェイ経由の環境で起動しない理由と、現実的な回避策

Code Mode は何をしているか

通常の Claude Code は、Bash / Read / Edit などのツールを 1 回呼ぶたびに結果を読み、次の手を決めます。Code Mode では、Claude が一連の操作を JavaScript で書き、Claude Code がそれをセッション内で実行します。公式ドキュメントの例はこうです。

const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

検索・編集・テストが 1 回の往復で済み、最後の行で「Claude が読む必要がある部分だけ」を返しています。会話画面には diff などのツール呼び出しだけが表示されます。コード本体は Ctrl+O のトランスクリプトビューアで Code 行を展開すると見られます。

有効化は環境変数 1 つです。

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

常時オンにしたい場合は ~/.claude/settings.json の env に書きます。なお、プロジェクト側の settings ではこの変数は無視されます。clone したリポジトリが勝手に Code Mode をオンにすることはできません。

「37% 削減」の出どころ

公式ドキュメントには、トークン削減率の数字はどこにも書かれていません。

数字を追うと、ある X の投稿(@fierce788、2026-11-15)がその出どころを整理していました。要点はこうです。

  • 元は第三者による 1 回きりのテスト(v2.1.323、タスク 1 件)
  • 入力トークン(キャッシュ込み)が 150,364 → 94,659。削減率を計算すると約 37%
  • 所要時間は 37 秒と 15 秒。文脈からは Code Mode 側が遅かったと読める
  • テストした本人も「各 1 回ずつではベンチマークとは言えない」と書いている

自分が気になったのは「キャッシュ込みの入力トークン」という点です。Anthropic の公式料金では、キャッシュ読み取りは通常入力の 0.1 倍です。トークン数が 37% 減っても、減ったのがキャッシュ読み取りの部分なら、請求額はほとんど変わりません。逆に、減ったのが非キャッシュの入力なら効果はもっと大きく出ます。内訳が公開されていない以上、「コストが 37% 下がる」とは言えません。

自分で確かめるなら、同じタスクを Code Mode のオン/オフで数回ずつ流し、/cost や API の usage を cache_read_input_tokens / cache_creation_input_tokens / input_tokens に分けて比べるのが確実です。

ゲートウェイ経由だと起動しない理由

公式ドキュメントの Requirements には、利用できる条件がはっきり書かれています。

  • アカウント:Claude のサブスクリプション、または Console アカウント。ゲートウェイ、Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry 経由では使えない
  • モデル:Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / Fable 5.2
  • 実行環境:ターミナルの対話型 claude のみ。-p、Agent SDK、VS Code パネル、Desktop アプリ、クラウドセッションは非対応
  • インストール:ネイティブビルド

ゲートウェイ経由で Claude Code を使う一般的な設定は、ANTHROPIC_BASE_URL と ANTHROPIC_AUTH_TOKEN の組み合わせです。トラブルシューティング表を見ると、この 2 つがそれぞれ別の理由で弾かれます。

起動時に出る理由 原因 公式の対処
it only works with the Anthropic API クラウドプロバイダ、ゲートウェイ、独自の ANTHROPIC_BASE_URL それらの設定を外す
it doesn't work with an API key helper apiKeyHelper、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_CUSTOM_HEADERS 内の Authorization / X-Api-Key 外してログインするか ANTHROPIC_API_KEY を設定
it needs settings that Claude Code downloads from Anthropic DISABLE_TELEMETRY などフィーチャーフラグ取得を止める変数 その変数を外す
OpenTelemetry is on CLAUDE_CODE_ENABLE_TELEMETRY など OTel エクスポートを止める

3 行目もゲートウェイ利用者がハマりやすいところです。社内ポリシーやプライバシー目的で DISABLE_TELEMETRY を入れている環境は多いですが、これも起動を妨げます。

つまり base URL を差し替えている時点で対象外です。ゲートウェイ側で何か対応すれば使える、という種類の制約ではありません。

開示:私は API ゲートウェイ(byesu)の開発・運用に関わっています。この制約は自分にとっても他人事ではないので、ゲートウェイ側で回避する方法はないか探しました。結論として、公式の要件を満たさない形で使う方法は紹介しません。以下はどのゲートウェイを使っている人にも当てはまる選択肢です。

ゲートウェイ利用者の現実的な選択肢

1. Code Mode を試すときだけ設定ディレクトリを分ける

Anthropic のサブスクリプションか Console アカウントを別に持っているなら、Code Mode 用と普段用で設定を分けるのが一番きれいです。

ここで注意点があります。settings.json の env に書いた値は、シェルの環境変数より優先されます(公式の env-vars ドキュメントより)。ゲートウェイの設定を ~/.claude/settings.json に書いている場合、シェルで unset ANTHROPIC_BASE_URL しても効きません。

そこで CLAUDE_CONFIG_DIR で設定ディレクトリごと分けます。

# 普段:ゲートウェイ用の設定ディレクトリ
alias claude-gw='CLAUDE_CONFIG_DIR="$HOME/.claude-gw" claude'

# Code Mode を試すとき:ゲートウェイ設定のない既定の ~/.claude、公式アカウントでログイン
alias claude-cm='env -u ANTHROPIC_BASE_URL -u ANTHROPIC_AUTH_TOKEN CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude'

~/.claude-gw/settings.json にゲートウェイの ANTHROPIC_BASE_URL などを移し、既定の ~/.claude/settings.json からは消しておきます。env -u はシェルに残っている同名の変数を外すためのものです。

Code Mode のセッションは Code Mode をオンにしたままでないと再開(--continue / --resume)できません。claude-cm で始めたセッションは claude-cm で再開してください。

2. Code Mode なしで「まとめて実行」に寄せる

Code Mode がトークンを減らす理由の大半は、「途中経過を全部モデルに読ませず、必要な部分だけ返す」ことです。Code Mode そのものは使えなくても、考え方だけなら普段の Bash ツールでかなり近づけられます。

たとえば「全 Markdown のリンク切れを探して」と頼むと、Claude はファイルを 1 つずつ Read しがちです。そこで、こう指示します。

ファイルを 1 つずつ読まずに、リンク切れを検出するスクリプトを 1 本書いて実行し、
結果(ファイル名と行番号とリンク先)だけを出力して。

公式の「Code Mode が向いているタスク」の 3 条件(多数ファイルへの同じ変更、読む前に絞り込みが要る検索、並列にできる独立したコマンド)は、そのまま「スクリプトにまとめさせるべきタスク」の目安として使えます。

ただし同等ではありません。Code Mode はスクリプト内の各ツール呼び出しにも permission ルールと PreToolUse フックを通しますが、Bash で 1 本のスクリプトを走らせると、中身はシェルのコマンドとしてまとめて実行されます。

3. 使えても、監視の粒度が変わることは知っておく

公式ドキュメントで一番大事だと思ったのは制限事項の部分です。

  • auto モードでは、分類器がチェックするのはツール呼び出しごとではなく「コード」単位。検索結果から取り出したパスのような、実行時に決まる値は見えない
  • 待ちで実行するコードは 10 分で止まる(バックグラウンド実行なら最大 2 時間)
  • Remote Control、Claude in Chrome、computer use は使えない

deny / ask ルールと PreToolUse フックは、コード内の各ツール呼び出しにも効きます。どうしても止めたい操作は、分類器任せにせずルールかフックで押さえておくのが安全です。コード自体を検査したい場合は、REPL にマッチする PreToolUse フックを書けば tool_input.code から JavaScript を読めます。

まとめ

  • Code Mode は v2.1.323 で入った実験機能。CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 で有効化
  • 「37% 削減」は第三者の 1 回きりのテストで、キャッシュ込みのトークン数。公式の数字ではなく、コスト削減率とも違う
  • ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN を使うゲートウェイ構成では起動しない。DISABLE_TELEMETRY も要注意
  • 試すなら CLAUDE_CONFIG_DIR で設定を分け、公式アカウントで起動する。使えない環境では「スクリプトにまとめて要点だけ返させる」指示で考え方を取り入れる

実験機能なので、要件は今後変わる可能性があります。変わったらこの記事も更新します。

出典:

ゲートウェイ経由で Claude Code を設定する手順(ANTHROPIC_BASE_URL の書き方、よくあるエラー)はこちらにまとめています:
https://docs.byesu.com/ja/clients/claude-cli

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?