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

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

Docker環境でDEBUG環境変数を設定すると、Python版Agent SDKがCLIからの応答を受け取れなくなる既知の不具合を解説します。原因と回避策、TypeScript SDKとの挙動の違いをまとめます。

読了目安 約12分

DockerコンテナでPython版Claude Agent SDKを動かし、DEBUG環境変数を設定するとどうなるでしょうか。CLIサブプロセス自体は正常に起動するのに、Python側がメッセージを一切受け取れなくなる不具合が報告されています。報告はClaude Code 2.0.45・Python版SDK 0.1.7(2025年11月)の環境です。Issueは2026年3月25日にclosed(completed)になりました。PR #723で、Python SDK側にstdoutの非JSON行を読み飛ばす修正が入りました。修正はPython SDK 0.1.51以降に含まれます。

DEBUGを外せば動くため気づきにくく、Docker・AWS Lambda・Bedrockなどコンテナ実行が前提の環境で踏みやすいパターンです。原因は起動時の診断ログがstdoutに混ざることです。回避策はDEBUGを設定しないことです。Python SDK 0.1.51以降なら、メッセージが0件で終わる症状は避けられます。TypeScript SDKでは名前の似た別の環境変数が逆方向に必要になるケースもあります。

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

Issue #347の報告者は、次の手順でこの不具合を再現しています。タイトルは「Python SDK is broken in Docker environment with DEBUG env var and Claude Code 2.0.43+」です。

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"]

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

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

報告された症状は2通りある

同じIssueには、別の環境からの報告も続いています。どちらも[SandboxDebug]行を確認しており、症状は元報告と少し違います。ログにはControl request timeout: initializeが出ていて、サイレントに終わるのではなく、初期化のコントロールリクエストがタイムアウトして例外になる形です。

くらべる

同じ原因で出る2つの見え方

元の報告(0.1.7)

何も返らず終了

query()が例外なしでメッセージ0件のまま終わります。CLI側の終了コードは正常なので、ログを見ないと失敗に気づけません。

後続の報告

initializeのタイムアウト

Control request timeout: initializeで例外になります。mchtech氏のログはx64、leetrout氏はAWS Lambda(arm64)上のBedrock利用です。

Issueのコメントで原因まで分析しているのはgauri-kumar氏だけです。タイムアウト側の報告に原因分析は付いていないため、2つの症状が同じ仕組みから出ているかは、コメントの範囲では断定できません。

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

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を設定しなければ症状が出ない点は、元の報告に明記されています。出力の条件はClaude Code 2.0.45の報告時点のもので、export DEBUG=falseでも[SandboxDebug]行が出たとされています。現行の公式ドキュメントでは、DEBUGが有効になるのは1・true・yes・onのときだけです。DEBUG=express:*のような他ツール向けの値は無視されます。falseで出た報告との差は、判定条件がバージョンで変わった可能性もあります。

同じデバッグモードは--debugや--debug-file <path>でも有効になります。通常のデバッグログは~/.claude/debug/<session-id>.txt(またはCLAUDE_CODE_DEBUG_LOGS_DIRのパス)へ書かれます。Issueで試されているのは環境変数のDEBUGだけです。

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

似た症状(コンテナ内でメッセージが届かない・タイムアウトする)でも原因が別のことがあります。報告者は、stdoutの読み取り経路を次の4段階で切り分けています。

手順

stdoutの経路を手前から確かめる

  1. 1

    CLIを直接叩く

    echo "Say hello" | /path/to/claude --output-format stream-json --verboseを実行し、system・assistant・resultのJSON行が返るかを見ます。ここで問題が出るなら、原因はSDKより手前のCLIかサンドボックス設定です。

  2. 2

    Pythonのサブプロセス経由で読む

    anyio.open_process()でCLIを起動し、process.stdoutのバイト列が届くかを確認します。報告環境では、3件のJSONメッセージを含む2,639バイトが届いていました。

  3. 3

    行単位のストリームで読む

    TextReceiveStreamで1行ずつ読み、デバッグ行とJSON行の数を数えます。報告環境は合計7行で、デバッグ行4行とJSON行3行でした。[SandboxDebug]が手前に混ざっているかがここで分かります。

  4. 4

    SDKのTransportで読む

    SubprocessCLITransport.read_messages()を直接呼び、返るメッセージが0件になるかを確認します。1〜3が正常で4だけ失敗するなら、原因はSDK側のJSONバッファ処理に絞れます。

1の時点で失敗する場合は、CLIのインストールやサンドボックス設定を先に疑います。

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

Python SDKをDockerで使うコンテナには、DEBUG環境変数を渡さない構成が確実な回避策です。DockerfileのENV、docker run -e、Lambdaの環境変数設定にDEBUGが紛れていないかを見直します。コンテナ内では次のように確かめられます。

# DEBUGが残っていないかを確認し、あれば外してから実行する
env | grep -E '^DEBUG='
unset DEBUG
python your_agent.py

Issueは2026年3月25日に、PR #723(stdoutの非JSON行を読み飛ばす修正)でcloseされました。変更はPython SDKのstdout解析処理にあり、0.1.51以降では非JSON行が読み飛ばされます。0.1.50以前のSDKでは、DEBUGを渡さない構成が確実な策です。Control request timeout: initializeが0.1.51以降でも出るなら、別の原因を疑います。

この[SandboxDebug]メッセージの引き金は、Linux上でseccomp用バイナリが見つからない状態です。Claude Codeのv2.1.92(2026年4月4日)の変更履歴に、対応が載っています。Linuxサンドボックスがnpm・ネイティブビルドの両方にapply-seccompヘルパーを同梱し、Unixソケットのブロックが復元されました。

ただしこれは隔離機能の修正で、診断行がstderrに書かれるようになったという記載は、変更履歴にありません。0.1.50以前のSDKを使い続ける場合は、DEBUGを設定しない回避策が引き続き有効です。

CLIのstderrを拾いたいときは、Python SDKのClaudeAgentOptionsにあるstderrコールバックを使います。debug_stderrは非推奨で、SDKが値を無視します。この2つはstderr側の話で、stdoutに混ざる診断行を取り除くものではありません。

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

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

報告によると、この変数が無いと、SDKが内部で起動するcli.jsサブプロセスが送りません。送られないのは、コンテナ内のSubagentStart/SubagentStopのcontrol_requestです。PostToolUse・PreToolUse・Notificationなど他のフック種別は、同じプロトコルで正常に動きます。変数を設定すると、サブプロセスの環境にDEBUG=1が入り(未設定なら明示的に削除)、--debug-to-stderrが引数に加わります。デバッグ出力はstderrへ向かいます。

同じコメントでは、書き込みはバッファ経由で、サーバー起動ごとに約5〜50KBが書かれ、Dockerでは一時的なものだと説明されています。回避策は次の1行です。

ENV DEBUG_CLAUDE_AGENT_SDK=1
くらべる

名前が似た2つの変数の向き

Python SDK / CLI本体が読む

DEBUG

Docker環境で設定すると、応答を受け取れなくなります。対処は設定しないことです。

TypeScript SDK(v0.2.72の報告)

DEBUG_CLAUDE_AGENT_SDK

未設定だと、Docker環境でSubagentStart/Stopフックが発火しません。該当フックを使うなら=1を設定します。

DEBUG_CLAUDE_AGENT_SDKは、TypeScript SDKがcli.jsの引数を組み立てるときに参照する別の変数です。Number531氏は、同じデバッグモードの分岐がコンテナとローカルで違う挙動をする点を、両方の報告の共通点として挙げています。

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

Issueに出てくる条件は3つあり、いずれもコンテナ上でPython SDKを動かす構成です。

まとめ

報告に出てくる3つの環境

  • Dockerコンテナ全般

    元Issueの再現手順そのものです。Python 3.12のスリムイメージにNode.js 22とCLIを入れた構成で、症状が出ています。

  • AWS Lambdaのコンテナイメージ(arm64)

    leetrout氏の報告です。Python SDKからBedrockを使う構成で、Control request timeout: initializeが出ています。

  • Bedrock経由の利用

    CLAUDE_CODE_USE_BEDROCK=1を設定するコンテナです。元Issueの再現手順にもこの設定が入っています。

Claude Code全体の環境変数はClaude Code環境変数リファレンスにあります。コンテナでの起動エラー全般(バイナリのアーキテクチャ不一致など)はAgent SDKのエラー集で扱っています。

まとめ

Python版Agent SDKをコンテナで動かすなら、DEBUGを渡さない構成にしておくか、Python SDKを0.1.51以降へ更新すれば、メッセージが0件で終わる症状は避けられます。Control request timeout: initializeで止まる場合は、更新後も出るなら別原因の可能性があります。どちらの場合も、まずenv | grep DEBUGで設定の有無を見ます。残っていなければ、上の4段階でstdoutの経路を切り分けます。TypeScript SDKでフックが発火しないときは、別変数のDEBUG_CLAUDE_AGENT_SDK=1を試す余地があります。

この記事を共有:XはてブLinkedIn

関連する記事

Agent SDK をもっと見る →