Agent SDKがDockerのDEBUG環境変数で動かなくなる原因と回避策

DockerコンテナでPython版Claude Agent SDKを動かし、DEBUG環境変数を設定するとどうなるでしょうか。CLIサブプロセス自体は正常に起動するのに、Python側がメッセージを一切受け取れなくなる不具合が報告されています。この報告はClaude Code 2.0.45・Python版SDK 0.1.7(2025年11月)時点のもので、Issueはclosedになっていますが修正コミットへの言及はなく、それ以降のバージョンで再現するかは一次ソースからは確認できません。DEBUGを外せば動くため気づきにくく、Docker・AWS Lambda・Bedrockなどコンテナ実行が前提の環境で踏みやすいパターンです。原因は起動時ログのstdout混入で、回避策はDEBUGを設定しないことです。TypeScript SDKでは名前の似た別の環境変数が逆方向に必要になるケースもあります。

何が起きるか — DEBUG設定時だけコンテナ内で応答が止まる

Issue #347の報告者は、次の手順でこの不具合を再現しています。

FROM python:3.12-slim
 
RUN apt-get update && apt-get install -y \
    build-essential curl git ca-certificates chromium \
    && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/* && apt-get clean
 
RUN npm install -g @anthropic-ai/claude-code@2.0.45
RUN pip install anyio claude-agent-sdk
 
ENV CLAUDE_CODE_USE_BEDROCK=1
CMD ["tail", "-f", "/dev/null"]

このイメージをビルドしてコンテナに入り、DEBUG環境変数に何らかの値を設定してからAgent SDKのクイックスタート相当のサンプルコードを実行すると、次の症状が起きます。

• Claude CodeのCLIサブプロセス自体は正常に起動し、終了コードも正常
• Pythonのquery()はasync for message in ...のイテレーターからメッセージを一切受け取れず、そのまま黙って終了する
• DEBUG環境変数を設定しなければ同じコードは問題なく動く
• macOS上の非Docker環境では、DEBUGの値に関わらず正常に動く

報告時点のバージョンはClaude Code 2.0.45・Python版SDK(claude-agent-sdk)0.1.7です。同じ症状はmchtech氏、leetrout氏(AWS Lambda arm64・Bedrock利用)からも独立に報告されています。3件の報告はいずれもLinuxコンテナ上での実行という共通点があります。

原因 — CLIの起動時ログがstdoutに混ざりJSONパースが壊れる

Issueへのコメントで、報告者の一人であるgauri-kumar氏が原因を次のように分析しています。この分析はAnthropicの公式な確認コメントではなく、ユーザーによる調査です。

Docker環境ではLinux上でseccompフィルタリング用のバイナリが見つからず、CLIは次のような診断メッセージを出力します。

[SandboxDebug] [Sandbox Linux] Seccomp filtering not available (missing binaries for arm64). Sandbox will run without Unix socket blocking (allowAllUnixSockets mode). This is less restrictive but still provides filesystem and network isolation.

この[SandboxDebug]行は、SDKとCLIの通信に使うstream-json形式のJSON出力と同じstdoutに書き込まれます。gauri-kumar氏の調査によると、Python SDKのSubprocessCLITransport._read_messages_impl()はstdoutの全行を読み込み、バッファに貯めてからJSONとしてパースを試みる実装です。[SandboxDebug]のような非JSON行が混ざると、そこから始まるバッファ全体のパースが「Expecting value: line 1 column 2」で失敗し続けます。結果としてメッセージは0件のまま、処理が終わります。

DEBUG環境変数を設定していないときにこの問題が起きないのは、[SandboxDebug]行自体がその条件下では出力されないためです。報告(Claude Code 2.0.45時点)ではexport DEBUG=falseのように値の内容を問わず[SandboxDebug]行が出力されたとされています。一方、現行の公式ドキュメントでは、DEBUGは1・true・yes・onのいずれかを設定した場合にのみ--debugフラグ相当のデバッグモードが有効になると説明されています。報告時点の判定条件が現行ドキュメントの条件と同じかどうかは一次ソースからは確認できません。通常のデバッグログは~/.claude/debug/<session-id>.txt(またはCLAUDE_CODE_DEBUG_LOGS_DIRで指定したパス)に書き込まれます。ただし今回問題になっている[SandboxDebug]行は、このログファイルとは別に起動時の標準出力へ直接書かれているとみられます。

自分の環境で同じ原因かを切り分ける方法

似た症状(コンテナ内でメッセージが届かない・タイムアウトする)でも原因が別のこともあるため、報告者は次の4段階でstdoutの読み取り経路を切り分けています。同じ手順は自分の環境で再現するかを確認するときにも使えます。

1. CLIを直接叩く: echo "Say hello" | /path/to/claude --output-format stream-json --verboseを実行し、system・assistant・resultのJSON行が正しく返るかを見ます。ここで問題が出るならSDKより手前、CLI自体かサンドボックス設定の問題です
2. Pythonのサブプロセス経由で読む: anyio.open_process()でCLIを起動し、process.stdoutを直接読んでバイト列が届くかを確認します。報告環境ではここまでは正常に動作していました
3. 行単位のストリームで読む: TextReceiveStreamで1行ずつ読み、デバッグ行とJSON行が合計何行届くかを数えます。[SandboxDebug]行がJSON行の手前に混ざっているかがこの段階で分かります
4. SDKのTransportで読む: SubprocessCLITransport.read_messages()を直接呼び出し、返るメッセージが0件になるかを確認します。1〜3が正常で4だけ失敗するなら、原因はSDK側のJSONバッファ処理に絞り込めます

この4段階のうち1〜3が通り4だけ失敗する場合は、本記事で扱っている[SandboxDebug]行の混入が濃厚です。1の時点で失敗する場合は、CLIのインストール自体やサンドボックス設定を先に疑ってください。

回避策 — Dockerコンテナ内ではDEBUGを設定しない

現状確認できている最も確実な回避策は、Python SDKをDocker環境で使うコンテナにDEBUG環境変数を渡さないことです。報告されている条件はDocker全般、AWS Lambdaのコンテナイメージ(arm64)、Bedrock経由の利用(CLAUDE_CODE_USE_BEDROCK=1)です。これらの環境ではDockerfileやdocker run -eの一覧を確認し、DEBUGが意図せず渡っていないかをチェックする価値があります。

Issueのコメント欄には、Anthropic側からの修正コミットへの言及は見当たらず、Python SDK側での恒久的な修正が入ったという報告もありません。バージョンを更新しても再現する可能性があるため、コンテナ環境でPython SDKを使う場合はDEBUGを明示的に未設定のままにしておくのが安全です。

なお、この[SandboxDebug]メッセージの引き金になっているのは「Linux上でseccomp用バイナリが見つからない」状態です。Claude Codeの変更履歴によると、この状態自体はv2.1.92(2026年4月4日)で対応が入っています。同バージョンでLinuxサンドボックスがnpm・ネイティブビルドの両方にapply-seccompヘルパーを同梱するようになり、Unixソケットのブロック機能が復元されました。ただしこれはサンドボックスの隔離機能に関する修正で、[SandboxDebug]診断行がstdoutではなくstderrに書かれるようになったとは変更履歴に明記されていません。アーキテクチャや実行環境によっては同種のメッセージが出力される余地が残るため、DEBUGを設定しないという回避策自体は引き続き有効です。

TypeScript SDKでは逆に「DEBUGが無いと動かない」ケースがある

同じIssueへのコメントで、Number531氏はTypeScript版SDK(v0.2.72)における逆方向の挙動を報告しています。TypeScript SDKでは、Docker環境でSubagentStart・SubagentStopフックを発火させるためにDEBUG_CLAUDE_AGENT_SDK=1という環境変数が必要だという内容です。この変数は公式の環境変数リファレンスには記載がありません。Number531氏がコード調査から見つけた非公式な変数です。

報告によると、DEBUG_CLAUDE_AGENT_SDK=1を設定しない場合、SDKが内部で起動するcli.jsサブプロセスはコンテナ内でフックのコールバックを送りません。対象はSubagentStart/SubagentStopのcontrol_requestだけで、PostToolUse・PreToolUse・Notificationなど他のフック種別は同じプロトコル経由で正常に動きます。この変数を設定すると、cli.jsの内部で次の2つが起きるとされています。

同じコメントでは、この変更は「バッファ書き込みで、コンテナ起動ごとに約5〜50KB、Docker終了時に消える」ため本番環境でも使いやすいとされています。

両者は名前が似ていますが別の環境変数です。DEBUGはClaude Code CLI本体が読む変数です。DEBUG_CLAUDE_AGENT_SDKはTypeScript SDKがcli.js起動時の引数を組み立てる際に参照する非公式の変数で、混同するとどちらの問題も解決しません。Number531氏自身も、Python SDKではDEBUGが壊し、TypeScript SDKではDEBUG_CLAUDE_AGENT_SDKが直すという対照的な報告になっている点を指摘しています。両言語ともcli.js内部のデバッグモード分岐が、コンテナ環境ではローカル実行と異なる挙動をする点は共通しています。

この不具合を踏みやすい実行環境

現時点で報告されている条件は次の3つです。いずれもDockerコンテナ上でPython SDKを実行する構成という共通点があります。

• Dockerコンテナ全般でPython SDKを実行する構成(元Issueの再現手順そのもの)
• AWS Lambdaのコンテナイメージ(arm64)からPython SDKを呼び出す構成(leetrout氏の報告と同条件)
• Bedrock経由でClaude Codeを使う構成(CLAUDE_CODE_USE_BEDROCK=1を設定するコンテナは、報告の再現手順そのもの)

コンテナ内でenv | grep DEBUGのように出力を確認し、Python SDKを呼び出す前に不要なDEBUGが残っていないかを見るのが手早い切り分け方法です。Claude Code全体の環境変数の一覧はClaude Code環境変数リファレンスにまとめています。

まとめ

Docker環境でPython版Agent SDKを使いDEBUG環境変数を設定すると、CLIが出力する[SandboxDebug]診断行がstdoutのJSONストリームに混ざります。結果としてSDK側のメッセージ受信がサイレントに失敗します。原因はユーザー調査によるものでAnthropicの公式コミットへの言及はなく、確実な回避策は「Dockerコンテナ内でPython SDKを使うときはDEBUGを設定しない」ことです。TypeScript SDKでは逆にDEBUG_CLAUDE_AGENT_SDK=1が特定フックの発火に必要になるケースがあり、名前が似た2つの変数を混同しないよう注意してください。コンテナでの起動エラー全般(バイナリのアーキテクチャ不一致など)はAgent SDKのエラー集で扱っています。