Shell ツール (`run_shell_command`)

このドキュメントでは、Qwen Code 用の run_shell_command ツールについて説明します。

説明

run_shell_command を使用して、基盤となるシステムと対話したり、スクリプトを実行したり、コマンドライン操作を行ったりできます。run_shell_command は指定されたシェルコマンドを実行します。また、tools.shell.enableInteractiveShell の設定が true に設定されている場合、ユーザー入力が必要なインタラクティブなコマンド（例: vim、git rebase -i）も実行できます。

Windows では、コマンドは cmd.exe /c で実行されます。他のプラットフォームでは、bash -c で実行されます。

引数

run_shell_command は以下の引数を取ります：

command (string, 必須): 実行する正確なシェルコマンド。
description (string, 任意): コマンドの目的に関する簡単な説明で、ユーザーに表示されます。
directory (string, 任意): コマンドを実行するディレクトリ（プロジェクトルートからの相対パス）。指定しない場合、コマンドはプロジェクトルートで実行されます。
is_background (boolean, 必須): コマンドをバックグラウンドで実行するかどうか。このパラメータは、コマンド実行モードについて明示的な判断を行うために必須です。開発サーバーやウォッチャー、デーモンなど、継続的に動作させる必要があり、他のコマンドの実行をブロックすべきではない長時間実行プロセスには true を設定します。完了まで待機してから次に進む一時的なコマンドには false を設定します。

`run_shell_command` の使い方 (Qwen Code で)

run_shell_command を使用する際、コマンドはサブプロセスとして実行されます。is_background パラメータを使用するか、明示的にコマンドに & を追加することで、コマンドをバックグラウンドまたはフォアグラウンドで実行するかを制御できます。このツールは、以下を含む実行に関する詳細情報を返します：

必須のバックグラウンドパラメータ

is_background パラメータは、すべてのコマンド実行において必須です。この設計により、LLM（およびユーザー）は各コマンドをバックグラウンドで実行するか、フォアグラウンドで実行するかを明示的に判断することが求められ、意図的かつ予測可能なコマンド実行の動作が促進されます。このパラメータを必須とすることで、長時間実行されるプロセスを扱う際に後続の操作をブロックしてしまうような、意図しないフォアグラウンド実行へのフォールバックを防ぎます。

バックグラウンド実行 vs フォアグラウンド実行

このツールは、明示的な選択に基づいてバックグラウンド実行とフォアグラウンド実行を適切に処理します：

バックグラウンド実行（is_background: true）を使用するケース：

長時間実行される開発サーバー：npm run start、npm run dev、yarn dev
ビルドウォッチャー：npm run watch、webpack --watch
データベースサーバー：mongod、mysql、redis-server
Webサーバー：python -m http.server、php -S localhost:8000
手動で停止されるまで無期限に実行し続けるコマンド

フォアグラウンド実行（is_background: false）を使用するケース：

一度限りのコマンド：ls、cat、grep
ビルドコマンド：npm run build、make
インストールコマンド：npm install、pip install
Git操作：git commit、git push
テスト実行：npm test、pytest

実行情報

ツールは、実行に関する詳細情報を返します。これには以下が含まれます：

Command: 実行されたコマンド。
Directory: コマンドが実行されたディレクトリ。
Stdout: 標準出力ストリームからの出力。
Stderr: 標準エラーストリームからの出力。
Error: サブプロセスによって報告されたエラーメッセージ。
Exit Code: コマンドの終了コード。
Signal: コマンドがシグナルによって終了された場合のシグナル番号。
Background PIDs: 起動されたバックグラウンドプロセスの PID のリスト。

使用方法：


run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false)

注: is_background パラメータは必須であり、すべてのコマンド実行で明示的に指定する必要があります。

`run_shell_command` の例

現在のディレクトリのファイルを一覧表示:


run_shell_command(command="ls -la", is_background=false)

特定のディレクトリでスクリプトを実行:


run_shell_command(command="./my_script.sh", directory="scripts", description="カスタムスクリプトを実行", is_background=false)

バックグラウンドで開発サーバーを起動（推奨アプローチ）:


run_shell_command(command="npm run dev", description="バックグラウンドで開発サーバーを起動", is_background=true)

バックグラウンドでサーバーを起動（明示的な & を使用した代替方法）:


run_shell_command(command="npm run dev &", description="バックグラウンドで開発サーバーを起動", is_background=false)

フォアグラウンドでビルドコマンドを実行:


run_shell_command(command="npm run build", description="プロジェクトをビルド", is_background=false)

複数のバックグラウンドサービスを起動:


run_shell_command(command="docker-compose up", description="すべてのサービスを起動", is_background=true)

設定

run_shell_command ツールの動作は、settings.json ファイルを編集するか、Qwen Code で /settings コマンドを使用することで設定できます。

インタラクティブコマンドの有効化

インタラクティブコマンドを有効にするには、tools.shell.enableInteractiveShell の設定を true に設定する必要があります。これにより、シェルコマンドの実行に node-pty が使用され、インタラクティブなセッションが可能になります。node-pty が利用できない場合、インタラクティブコマンドをサポートしない child_process 実装にフォールバックします。

settings.json の例:


{
  "tools": {
    "shell": {
      "enableInteractiveShell": true
    }
  }
}

出力でのカラー表示

シェル出力にカラーを表示するには、tools.shell.showColor の設定を true に設定する必要があります。注: この設定は、tools.shell.enableInteractiveShell が有効になっている場合にのみ適用されます。

settings.json の例:


{
  "tools": {
    "shell": {
      "showColor": true
    }
  }
}

ページャの設定

シェル出力用にカスタムページャを設定するには、tools.shell.pager 設定を変更します。デフォルトのページャは cat です。注：この設定は tools.shell.enableInteractiveShell が有効になっている場合にのみ適用されます。

例 settings.json:


{
  "tools": {
    "shell": {
      "pager": "less"
    }
  }
}

インタラクティブコマンド

run_shell_command ツールは、擬似端末（pty）を統合することでインタラクティブコマンドをサポートするようになりました。これにより、テキストエディタ（vim、nano）、ターミナルベースのUI（htop）、インタラクティブなバージョン管理操作（git rebase -i）など、リアルタイムでのユーザー入力が必要なコマンドを実行できるようになります。

インタラクティブコマンドが実行されている間、Qwen Code からそのコマンドへ入力を行うことができます。インタラクティブシェルにフォーカスを当てるには、ctrl+f を押してください。複雑なTUIを含むターミナル出力も正しく描画されます。

重要な注意点

セキュリティ: 特にユーザー入力から構築されたコマンドを実行する際は、セキュリティ脆弱性を防ぐために注意が必要です。
エラーハンドリング: コマンドが正常に実行されたかどうかを判断するために、Stderr、Error、およびExit Codeフィールドを確認してください。
バックグラウンドプロセス: is_background=trueの場合やコマンドに&が含まれる場合、ツールは即座に戻り値を返し、プロセスはバックグラウンドで継続して実行されます。Background PIDsフィールドにはバックグラウンドプロセスのプロセスIDが格納されます。
バックグラウンド実行の選択肢: is_backgroundパラメータは必須であり、実行モードを明示的に制御できます。手動でバックグラウンド実行を行うためにコマンドに&を追加することも可能ですが、それでもis_backgroundパラメータを指定する必要があります。このパラメータにより意図が明確になり、バックグラウンド実行のセットアップが自動的に処理されます。
コマンドの説明: is_background=trueを使用する場合、コマンドの説明には実行モードを明確に示すための[background]インジケータが含まれます。

環境変数

run_shell_command がコマンドを実行する際、サブプロセスの環境に QWEN_CODE=1 環境変数を設定します。これにより、スクリプトやツールが CLI 内から実行されているかどうかを検出できます。

コマンド制限

run_shell_command ツールで実行可能なコマンドを制限するには、設定ファイルの tools.core および tools.exclude 設定を使用します。

tools.core: run_shell_command を特定のコマンドセットに制限するには、tools カテゴリの core リストに run_shell_command(<command>) 形式のエントリを追加します。たとえば、"tools": {"core": ["run_shell_command(git)"]} とすると、git コマンドのみが許可されます。一般的な run_shell_command を含めるとワイルドカードとして機能し、明示的にブロックされていないすべてのコマンドが許可されます。
tools.exclude: 特定のコマンドをブロックするには、tools カテゴリの exclude リストに run_shell_command(<command>) 形式のエントリを追加します。たとえば、"tools": {"exclude": ["run_shell_command(rm)"]} とすると、rm コマンドがブロックされます。

検証ロジックは、セキュアかつ柔軟性を持つように設計されています：

コマンドチェーンの無効化: ツールは自動的に &&、||、または ; で連結されたコマンドを分割し、各部分を個別に検証します。チェーン内のいずれかの部分が許可されていない場合、コマンド全体がブロックされます。
プレフィックスマッチング: ツールはプレフィックスマッチングを使用します。たとえば、git を許可すると、git status や git log を実行できます。
ブロックリストの優先順位: tools.exclude リストは常に最初にチェックされます。コマンドがブロックされたプレフィックスに一致する場合、tools.core の許可されたプレフィックスにも一致していても拒否されます。

コマンド制限の例

特定のコマンドプレフィックスのみを許可

git および npm コマンドのみを許可し、他のすべてをブロックする場合：


{
  "tools": {
    "core": ["run_shell_command(git)", "run_shell_command(npm)"]
  }
}

git status: 許可
npm install: 許可
ls -l: ブロック

特定のコマンドプレフィックスをブロック

rm をブロックし、他のすべてのコマンドを許可する場合：


{
  "tools": {
    "core": ["run_shell_command"],
    "exclude": ["run_shell_command(rm)"]
  }
}

rm -rf /: ブロック
git status: 許可
npm install: 許可

ブロックリストが優先される

コマンドプレフィックスが tools.core と tools.exclude の両方に含まれている場合、それはブロックされます。


{
  "tools": {
    "core": ["run_shell_command(git)"],
    "exclude": ["run_shell_command(git push)"]
  }
}

git push origin main: ブロック
git status: 許可

すべてのシェルコマンドをブロック

すべてのシェルコマンドをブロックするには、run_shell_command ワイルドカードを tools.exclude に追加します：


{
  "tools": {
    "exclude": ["run_shell_command"]
  }
}

ls -l: ブロック
any other command: ブロック

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

run_shell_command における excludeTools のコマンド固有の制限は、単純な文字列マッチングに基づいており、簡単に回避される可能性があります。この機能はセキュリティメカニズムではないため、信頼できないコードを安全に実行するために依存すべきではありません。実行可能なコマンドを明示的に選択するには、coreTools を使用することを推奨します。

Shell ツール (run_shell_command)

説明

引数

run_shell_command の使い方 (Qwen Code で)