Skip to Content
ユーザーガイド機能サンドボックス

Sandbox

このドキュメントでは、Linux におけるツール実行の制限と、既存の CLI 全体を対象とするサンドボックス手法について説明します。

Linux ツール実行サンドボックス

Linux では、最も強力なサポート対象の境界を実現するために、bwrap（Bubblewrap）を /usr/bin/bwrap（サポートされるシステムパス）にインストールし、User 設定（~/.qwen/settings.json、または QWEN_HOME で選択されるディレクトリ）または管理者の System 設定でツール実行サンドボックスを有効化します。

{
  "tools": {
    "executionSandbox": {
      "backend": "auto",
      "filesystem": "workspace-write",
      "network": "closed"
    }
  }
}

filesystem と network は必須です。backend のデフォルトは auto で、まず bwrap を試行します。bwrap が利用できず network が open の場合、auto は Landlock ABI 3 以降のカーネルで同梱の Landlock ヘルパーを使用できます。backend を bwrap または landlock に設定すると、それぞれの実装を必須とします。Landlock は network: closed を強制したり、明示的にマスクされたパスを隠したりすることはできません。いずれの要件がある場合、コマンドが開始される前に Landlock は拒否されます。自動フォールバックが残りのパスマスクを破棄することはありません。read-only を使用してワークスペースへの書き込みを拒否するか、workspace-write を使用して現在のカノニカルワークスペース内への書き込みを許可します。各コマンドはプライベートなスクラッチ空間も取得します。通常の includeDirectories 設定は書き込みアクセスを付与しません。ワークスペースは Qwen のインストールディレクトリ、ユーザー設定、ランタイム状態ディレクトリから分離してください。

CLI、モデルトランスポート、認証、セッションストレージはホスト上に残ります。シェル、ターミナル !、プロンプトシェルの補間、Monitor、Read/Write/Edit、およびサポートされるネストされたインプロセス Agent/Code Mode 呼び出しは、同じランタイムポリシーを使用します。bwrap では、network: closed はコマンドからの通常のホスト/外部 IP 接続をブロックし、open はホストネットワークを共有します。読み取りは引き続き広範です。このモードはホストのシークレットを隠したり、パス名の Unix ソケットやホストサービスの分離を保証したりしません。承認モードと YOLO はファイルシステムまたはネットワークポリシーを拡張しません。標準ストリームは明示的な呼び出し元提供のケイパビリティです。すでに接続済みのソケット、TTY、またはキャラクタデバイスは network: closed でも使用可能です。閉じたネットワークはそれらの既存のディスクリプタを取り消しません。不要なアクセスがある場合に、ホストサービス接続を stdin として提供しないでください。ホストバックのファイルおよび名前付き FIFO stdin は同梱の Linux x64/arm64 入力ヘルパーを必要とし、プライベートな Unix ストリームソケット経由でコピーされます（書き込み側はシャットダウンされています）。通常ファイルのオフセットはそのソケットから消費されたバイト数分のみ進行し、アイドル状態の FIFO ライターはコマンドの完了を遅延させません。fd 0 を直接読み取ってください。この入力は FIFO ではなくソケットであり、/dev/stdin または /proc/self/fd/0 経由で再オープンすることはサポートされていません。SIGINT/SIGTERM はコマンドをキャンセルしますが、受け付けられた stdout/stderr のバイトは引き続きドレインされます。閉じられた出力はそのストリームを終了コード 141 で停止しますが、もう一方の有効な出力はドレインされます。

Landlock は partial 強制と報告されます。これはパス名の読み取り、書き込み、ディレクトリ変更を制限しますが、PID またはネットワーク名前空間を作成せず、chmod、chown、拡張属性、タイムスタンプを含むすべてのメタデータ操作を現在のところ制限できないためです。Landlock コマンドはホストプロセスを参照でき、ホストネットワークを使用します。切り離された子孫は Landlock のファイルシステム制限を保持しますが、bwrap の PID 名前空間のライフタイム境界は取得しません。オープンされたファイルディスクリプタは既存のアクセスを保持します。Qwen Code はホストバックのファイルおよび名前付き FIFO stdin を、それらのディスクリプタをペイロードに渡す代わりにプライベートな読み取り専用ソケット経由でストリーミングします。ソケット、キャラクタデバイス、匿名パイプは共有できます。出力標準ストリームは呼び出し元の明示的な宛先のままです。実行状態ディスクリプタはペイロード exec 時にクローズされます。

Landlock はより狭い書き込み可能なデバイス表面も持ります。/dev/null への書き込みを許可しますが、bwrap のプライベートな /dev および /proc マウントを作成しません。/dev/full または /dev/tty を書き込み用にオープンすることや /dev/shm にファイルを作成することは拒否されるため、これらの操作を必要とするプログラムは失敗する場合があります。一時ファイルには TMPDIR、TMP、TEMP 経由で公開されるプライベートスクラッチディレクトリを使用してください。すでにオープンされている呼び出し元提供の標準ストリームは既存のアクセスを保持します。起動時の Landlock ポリシープローブには /usr/bin/true が必要です。これがないホストでは、カーネルが Landlock をサポートしていてもプローブに失敗します。

ワークスペース設定は、信頼されたプロジェクトであっても、このポリシーを有効化、無効化、変更できません。有効な優先順位は System > User > SystemDefaults で、完全なポリシーオブジェクトを選択します。値はリテラルでなければなりません。環境変数の置換、未知のフィールド、不完全なオブジェクトは拒否されます。--bare と --safe-mode はオペレーターの制限を保持します。変更には新しいランタイムが必要です。不正な形式または読み取り不能な SystemDefaults、User、System 設定ファイルは起動をブロックするようになりました（設定終了コード 52）。未知のポリシーを空の設定にサイレントにリセットする代わりに、エラーがファイルと修復操作を通知します。JSON オブジェクトを修復するか読み取りアクセスを復元してから再起動してください。User の .corrupted コピーは参照用です。元のオペレーターファイルがクリアされることはありません。オペレーターの制限なしでワークスペースのみの復旧が引き続き利用可能です。リンクされたワークスペース設定（リンクされた .qwen ディレクトリまたはハードリンクされたファイルを含む）の不正な形式は手動修復が必要です。自動復旧は、元または以前の破損コピーを変更する前に拒否します。有効なリンクされた JSON は読み取り可能です。

この初期のパブリックモードは、通常のヘッドレス CLI と両方のターミナル UI をサポートします。ACP、qwen serve、Web ターミナルは明示的に拒否します。MCP/LSP、実行可能なフック/拡張機能、ワークツリー/アリーナ管理、外部エージェント、投機的実行、ファイルチェックポイント、自動スキル/メモリ管理、および未移植のプロセスまたは変更ツールは無効化または拒否されます。通常の同一ワークスペース内プロセスエージェントは、フック、MCP サーバー、外部エグゼキューター、ワークツリー分離を追加できません。カスタムステータスコマンド、外部 Markdown/画像レンダラー、IDE 検出と接続、ファイル復元、ホスト Git diff プレビューは無効です。会話のみの rewind は利用可能です。

/doctor などの明示的なオペレーターの診断、/memory を通じたファイルやフォルダのオープンまたは編集、/skills を通じた設定変更は、信頼されたホストアクションのままです。これらの管理コマンドはモデルが呼び出し可能なコマンドとしては公開されていません。スキルを選択すると入力フィールドに入力されます。/skill-name を送信すると、引数の準備や使用レコードの更新前に、未サポートモードエラーが報告されます。スキルのコマンド実行とモデルの Skill ツールは、それらの準備書き込みが制限されるまで利用できません。自動メモリとスキルの管理は、保存された設定を変更しても、このランタイムでは無効のままです。

タスクを実行する前に、アクティブな境界を検査および検証してください。

qwen sandbox
qwen sandbox --verify
qwen sandbox -- sh -c 'printf "confined command\n"'
qwen -y -p "Update the project and run its tests"

リンクされた Git ワークツリーは、受け入れられたワークスペースに対してのみ書き込みアクセスを取得します。そのワークスペース外の Git 共通ディレクトリとワークツリーのメタデータは読み取り専用のままです。このモードは別のチェックアウトのリポジトリメタデータの変更を暗黙的に許可しません。それらの書き込みを必要とする操作は拒否される場合があります。

レポートにはツール境界、要求された/有効なバックエンド、強制レベル、該当する場合は Landlock ABI、ワークスペース、ファイルシステム、コマンドネットワークポリシーが記載されます。--verify はワークスペースへの書き込み、ホスト上で書き込み可能であることが知られているファイルに対する拒否、期待されるプライベートまたは共有 PID 名前空間のアイデンティティ、および選択されたネットワーク名前空間をチェックします。バックエンドプローブの合格は受け入れを確立するものであり、すべての継承された環境設定下での認証された完全セッションの実現可能性ではありません。その後、通常のタスクを実行して必要なツールとサービスをテストしてください。検証がホスト側の一時フィクスチャを作成できない場合は、TMPDIR とディレクトリ権限を確認してください。これは境界拒否とは別です。バックエンド設定エラーはペイロード実行前に失敗し、ホストでコマンドを再実行することはありません。単一コマンドのサブコマンドは、stdout と stderr をバイト単位で保持しながら、リテラル引数とリダイレクトされた stdin を転送します。インタラクティブ PTY コマンドにはターミナル ! を使用してください。

whole-CLI bwrap からの移行

--sandbox bwrap を置き換え、tools.sandbox: "bwrap"、QWEN_SANDBOX=bwrap、QWEN_SANDBOX_NET、QWEN_SANDBOX_PROXY_COMMAND を削除してから、上記のように tools.executionSandbox を設定してください。古いサンドボックスの外部のシェルから再起動してください。継承された SANDBOX=bwrap は拒否されます。proxied はサポートされたネットワークポリシーではありません。このモードを Docker、Podman、Seatbelt、または継承された whole-CLI サンドボックスマーカーと組み合わせないでください。古い bwrap 設定は明示的な移行エラーを生成します。

以下の Docker、Podman、macOS Seatbelt の方法は、引き続き既存の環境で CLI 全体を実行します。

前提条件

サンドボックスを使用する前に、Qwen Code をインストールしてセットアップする必要があります。

npm install -g @qwen-code/qwen-code

インストールを確認するには：

qwen --version

サンドボックスの概要

サンドボックスは、危険な操作（シェルコマンドやファイルの変更など）をホストシステムから隔離し、CLI と環境の間にセキュリティの壁を提供します。

サンドボックスの利点は次のとおりです。

  • セキュリティ: 偶発的なシステムの破損やデータの損失を防ぎます。
  • 隔離: ファイルシステムへのアクセスをプロジェクトディレクトリに制限します。
  • 一貫性: 異なるシステム間で再現可能な環境を保証します。
  • 安全性: 信頼できないコードや実験的なコマンドを扱う際のリスクを低減します。
Note

名前に関する注意: 一部のサンドボックス関連の環境変数は、歴史的に GEMINI_* プレフィックスを使用していた場合があります。新しい環境変数はすべて QWEN_* プレフィックスを使用します。

サンドボックスの方法

最適なサンドボックス方法は、ご利用のプラットフォームやお好みのコンテナソリューションによって異なります。

1. macOS Seatbelt（macOS のみ）

sandbox-exec を使用した軽量で組み込みのサンドボックス機能です。

デフォルトプロファイル: permissive-open - プロジェクトディレクトリ外への書き込みを制限しますが、その他のほとんどの操作とアウトバウンドネットワークアクセスを許可します。

最適な用途: 高速、Docker 不要、ファイル書き込みに対する強力なガードレール。

2. コンテナベース（Docker/Podman）

完全なプロセス分離を備えたクロスプラットフォームのサンドボックス機能です。

デフォルトでは、Qwen Code は公開されているサンドボックスイメージ（CLI パッケージで設定）を使用し、必要に応じてプルします。

コンテナサンドボックスは、ワークスペースと ~/.qwen ディレクトリをコンテナにマウントすることで、認証と設定が実行間で保持されます。

最適な用途: 任意の OS で強力な分離、既知のイメージ内での一貫したツール環境。

方法の選択

  • macOS の場合:
    • 軽量なサンドボックスが必要な場合は Seatbelt を使用（ほとんどのユーザーに推奨）。
    • 完全な Linux ユーザーランドが必要な場合（Linux バイナリを必要とするツールなど）は Docker/Podman を使用。
  • Linux/Windows の場合:
    • Docker または Podman を使用。

クイックスタート

# コマンドフラグでサンドボックスを有効化
qwen -s -p "コード構造を分析"
 
# または、シェルセッションでサンドボックスを有効化（CI / スクリプトに推奨）
export QWEN_SANDBOX=true   # true はプロバイダを自動選択（下記の注を参照）
qwen -p "テストスイートを実行"
 
# settings.json で設定
{
  "tools": {
    "sandbox": true
  }
}
Tip

プロバイダ選択に関する注意:

  • macOS では、QWEN_SANDBOX=true は通常、利用可能な場合 sandbox-exec（Seatbelt）を選択します。
  • Linux/Windows では、QWEN_SANDBOX=true を使用するには docker または podman がインストールされている必要があります。
  • プロバイダを強制するには、QWEN_SANDBOX=docker|podman|sandbox-exec を設定します。

設定

サンドボックスの有効化（優先順位順）

  1. 環境変数: QWEN_SANDBOX=true|false|docker|podman|sandbox-exec
  2. コマンドフラグ / 引数: -s、--sandbox、または --sandbox=<provider>
  3. 設定ファイル: settings.json の tools.sandbox（例: {"tools": {"sandbox": true}}）
Important

QWEN_SANDBOX が設定されている場合、CLI フラグと settings.json よりも優先されます。

--sandbox と -s はオプションの値を受け付けます。true、false、docker、podman、sandbox-exec です。プロンプト付きで自動選択するには、qwen --sandbox=true "query" または qwen --sandbox -p "query" を使用します。古いブール値のみのパーサーとは異なり、qwen --sandbox "query" は query をバックエンド値として扱い、未知のバックエンドを拒否するようになりました。-- より前のオプションは、位置語の後でも同じ文法を使用します。プロンプト内のリテラルオプションテキストには -p "..." を使用してください。-- はオプション解析を停止しますが、その後のトークンはデフォルトコマンドのプロンプトとして転送されません。セッションサンドボックスフラグは管理サブコマンドでは受け付けられません。その -s エイリアスはそれぞれの意味を保持します。

サンドボックスイメージの設定（Docker/Podman）

  • CLI フラグ: --sandbox-image <image>
  • 環境変数: QWEN_SANDBOX_IMAGE=<image>
  • 設定ファイル: settings.json の tools.sandboxImage（例: {"tools": {"sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1"}}）

優先順位（高い順）：

  1. --sandbox-image
  2. QWEN_SANDBOX_IMAGE
  3. tools.sandboxImage
  4. CLI パッケージに組み込まれたデフォルトイメージ（例: ghcr.io/qwenlm/qwen-code:<version>）

settings.env.QWEN_SANDBOX_IMAGE も、汎用的な env 注入メカニズムとして機能しますが、永続的な設定としては tools.sandboxImage が推奨されます。

カスタムイメージはユーザーが管理します。安全なアップデートの受け渡しを受けるには、最新の Qwen Code インストールで再ビルドしてください。古いイメージは、元のプロセス内アップデーターを引き続き使用する場合があります。

macOS Seatbelt プロファイル

組み込みプロファイル（SEATBELT_PROFILE 環境変数で設定）：

  • permissive-open（デフォルト）: 書き込み制限、ネットワーク許可
  • permissive-closed: 書き込み制限、ネットワークなし
  • permissive-proxied: 書き込み制限、プロキシ経由のネットワーク
  • restrictive-open: 厳格な制限、ネットワーク許可
  • restrictive-closed: 最大の制限
  • restrictive-proxied: 厳格な制限、プロキシ経由のネットワーク
Tip

最初は permissive-open で始め、ワークフローが問題なく動作する場合は restrictive-closed に厳格化してください。

カスタム Seatbelt プロファイル（macOS）

カスタム Seatbelt プロファイルを使用するには：

  1. プロジェクトに .qwen/sandbox-macos-<profile_name>.sb という名前のファイルを作成します。
  2. SEATBELT_PROFILE=<profile_name> を設定します。

カスタムサンドボックスフラグ

コンテナベースのサンドボックスでは、SANDBOX_FLAGS 環境変数を使用して docker または podman コマンドにカスタムフラグを注入できます。これは、特定のユースケースのセキュリティ機能を無効にするなど、高度な設定に役立ちます。

例（Podman）:

ボリュームマウントの SELinux ラベリングを無効にするには、次のように設定します。

export SANDBOX_FLAGS="--security-opt label=disable"

複数のフラグはスペース区切りの文字列として指定できます。

export SANDBOX_FLAGS="--flag1 --flag2=value"

ネットワークプロキシ（すべてのサンドボックス方法）

アウトバウンドネットワークアクセスを許可リストに制限したい場合は、サンドボックスと一緒にローカルプロキシを実行できます。

  • QWEN_SANDBOX_PROXY_COMMAND=<command> を設定します。
  • コマンドは :::8877 でリッスンするプロキシサーバーを起動する必要があります。

これは、*-proxied Seatbelt プロファイルと組み合わせて特に便利です。

動作する許可リスト形式のプロキシの例については、プロキシスクリプトの例 を参照してください。

Linux の UID/GID 処理

Linux では、Qwen Code はデフォルトで UID/GID マッピングを有効にして、サンドボックスがユーザーとして実行されるようにします（マウントされた ~/.qwen を再利用します）。次のように上書きできます。

export SANDBOX_SET_UID_GID=true   # ホストの UID/GID を強制
export SANDBOX_SET_UID_GID=false  # UID/GID マッピングを無効化

トラブルシューティング

よくある問題

“Operation not permitted”

  • 操作がサンドボックス外へのアクセスを必要としています。
  • macOS Seatbelt の場合: より寛容な SEATBELT_PROFILE を試してください。
  • Docker/Podman の場合: ワークスペースがマウントされていること、およびコマンドがプロジェクトディレクトリ外へのアクセスを必要としていないことを確認してください。

コマンドが見つからない

  • コンテナサンドボックス: .qwen/sandbox.Dockerfile または .qwen/sandbox.bashrc を使用して追加します。
  • Seatbelt: ホストのバイナリが使用されますが、サンドボックスによって一部のパスへのアクセスが制限される場合があります。

Docker サンドボックスで Java が利用できない

公式の Qwen Code Docker イメージは、イメージを小さく、安全に保ち、高速にプルできるように、意図的に最小限に構成されています。ユーザーによって必要な言語ランタイム（Java、Python、Node.js など）は異なり、すべての環境を1つのイメージにバンドルすることは現実的ではありません。したがって、Java は Docker サンドボックスにはデフォルトで含まれていません。

ワークフローに Java が必要な場合は、プロジェクトに .qwen/sandbox.Dockerfile を作成してベースイメージを拡張できます。

FROM ghcr.io/qwenlm/qwen-code:latest
 
RUN apt-get update && \
    apt-get install -y openjdk-17-jre && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

次に、サンドボックスイメージを再ビルドします。

QWEN_SANDBOX=docker BUILD_SANDBOX=1 qwen -s

サンドボックスのカスタマイズの詳細については、サンドボックス環境のカスタマイズ を参照してください。

ネットワークの問題

  • サンドボックスプロファイルがネットワークを許可していることを確認します。
  • プロキシ設定を確認します。

デバッグモード

DEBUG=1 qwen -s -p "デバッグコマンド"

注意: プロジェクトの .env ファイルに DEBUG=true がある場合、自動除外により CLI には影響しません。Qwen Code 固有のデバッグ設定には .qwen/.env ファイルを使用してください。

サンドボックスの検査

# 環境の確認
qwen -s -p "シェルコマンドを実行: env | grep SANDBOX"
 
# マウントの表示
qwen -s -p "シェルコマンドを実行: mount | grep workspace"

セキュリティに関する注意

  • サンドボックスはリスクを低減しますが、すべてのリスクを排除するわけではありません。
  • 作業が許可される最も制限の厳しいプロファイルを使用してください。
  • 最初のプル/ビルド後は、コンテナのオーバーヘッドは最小限です。
  • GUI アプリケーションはサンドボックス内で動作しない場合があります。

関連ドキュメント

Last updated on
常駐コンテキストコストi18n