Qwen Code SDK の小さな API と承認経路

Qwen Code リポジトリにおける SDK の役割

リポジトリ QwenLM/qwen-code は、ターミナルで動作するオープンソースの AI コーディングエージェントとして説明されています。packages/sdk-typescript の README は、そのエージェントへのプログラムアクセスを提供する TypeScript SDK である @qwen-code/sdk を文書化しています。この SDK は最小かつ実験的とされています。リポジトリのメタデータには 26,713 スターと 2,786 フォークが示されていますが、README は採用状況、ベンチマーク、本番利用については触れていません。SDK は、開発者が独自の TypeScript アプリケーションからクエリセッションを開始し、権限を制御し、メッセージを処理できるようにすることに焦点を当てています。

インストールとバージョン要件

この SDK には Node.js バージョン 22.0.0 以上が必要です。README に記載されているインストールコマンドは npm install @qwen-code/sdk です。バージョン 0.1.1 以降、CLI は SDK にバンドルされているため、Qwen Code を個別にインストールする必要はありません。バージョン 0.1.0 では要件が異なり、Qwen Code バージョン 0.4.0 以上を個別にインストールし PATH に含める必要があり、推奨コマンドは npm install -g @qwen-code/qwen-code@latest でした。README は現在のバージョンや 0.1.1 のリリース時期を明記していません。

query() 関数とそのオプション

主要なエントリポイントは query(config) で、Qwen Code とのクエリセッションを作成します。prompt は単一ターンのクエリにはプレーンな文字列、複数ターンの会話には SDKUserMessage の非同期反復子を使用できます。options オブジェクトは、cwd、model、pathToQwenExecutable、permissionMode、canUseTool、env、systemPrompt、mcpServers、abortController、debug、maxSessionTurns、coreTools、excludeTools、allowedTools、authType、agents、includePartialMessages、resume、sessionId を受け入れます。model オプションは OPENAI_MODEL および QWEN_MODEL 環境変数より優先されます。canUseTool、mcpRequest、controlRequest、streamClose のデフォルトタイムアウトは 1 分で、timeout オプションで上書きできます。README は返されたメッセージを反復処理し、isSDKAssistantMessage や isSDKResultMessage などの型ガードを使用する方法を示しています。

権限モードと承認チェーン

ツール実行を制御する権限モードは、default、plan、auto-edit、auto、yolo の 5 つです。default モードでは、書き込みツールは canUseTool コールバックまたは allowedTools で承認されない限り拒否され、読み取り専用ツールは確認なしで実行されます。plan モードはすべての書き込みツールをブロックし、AI にまず計画を提示するよう求めます。auto-edit は edit、write_file、notebook_edit などの編集ツールを自動承認しますが、その他のツールは確認が必要です。auto は組み込みの分類器を使用して安全な呼び出しを承認し、リスクのある呼び出しをブロックし、繰り返しのブロックや分類器の障害後は手動承認にフォールバックします。yolo はすべてのツールを自動承認します。決定優先チェーンは、excludeTools または permissions.deny、permissions.ask、plan、yolo、allowedTools または permissions.allow、auto、canUseTool、そしてデフォルトの動作の順です。最初に一致するルールが優先されます。

MCP サーバー、システムプロンプト、セッション制御

この SDK は、stdio、SSE、HTTP を介した外部 MCP サーバーと、同じプロセス内で実行される SDK 組み込みサーバーをサポートしています。tool() ヘルパーは、名前、説明、Zod 入力スキーマ、ハンドラーを持つツールを定義し、createSdkMcpServer() はツールをサーバーインスタンスにバンドルします。systemPrompt オプションは、組み込みプロンプトを完全に上書きする文字列、または追加の指示を追加するプリセットオブジェクトにできます。Query インスタンスのメソッドには、getSessionId()、isClosed()、interrupt()、setPermissionMode()、setModel()、getContextUsage()、close() があります。実験的な DaemonSessionClient は、HTTP と SSE を介して実行中の qwen serve デーモンに接続し、オフラインのトランスクリプト投影ヘルパーは、ファイルやネットワークアクセスなしで ChatRecord 値をブロックモデルに変換します。

エラー処理、バージョン FAQ、Apache-2.0 ライセンス

この SDK は、中止されたクエリを検出するために AbortError と isAbortError をエクスポートし、abortController オプションで呼び出し元がセッションをキャンセルできます。README の FAQ セクションはバージョン 0.1.0 の要件を取り上げています。Qwen Code 0.4.0 以上を個別にインストールする必要があり、0.1.1 からは CLI がバンドルされています。このプロジェクトは Apache-2.0 ライセンスで、リポジトリのメタデータと LICENSE ファイルに示されています。ライセンスは、複製、派生作品の作成、公開表示、実行、再ライセンス、頒布の権利を付与し、特許付与も含みます。保証やサポートは提供されません。README は、サポート保証、セキュリティ体制、本番対応について言及していません。

SDK を組み込む際の焦点は、モデルの回答品質よりもプロセス境界と権限の扱いです。README の query() 例は入力を送り、応答を受け取る流れを示しますが、作業ディレクトリの変更やシェル操作をどの段階で許可するかは権限モードの設定に依存します。MCP を加えると外部ツールの説明と結果もセッションに入るため、サーバーごとの能力、環境変数、ログの扱いを分けて監査する必要があります。エラー処理は呼び出し側で実装し、途中終了と再試行を同一視しない設計が必要です。

編集部の結論

既存の TypeScript サービスから Qwen Code のターミナルエージェントを呼びたい開発者に向きます。導入前には SDK と CLI のバージョン、query() のストリーム終了条件、権限モードの承認動作、MCP サーバーへ渡る入力を固定して確認してください。README は実験的なラッパーの説明で、CLI 全体の仕様書ではありません。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes