> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen Code CLI
Qwen Code CLI は、ターミナルから直接複数のエージェントロールを利用できる、AI を活用したコーディングアシスタントです。本ガイドでは、SambaNova の LLM を Qwen Code CLI に接続し、開発ワークフローにおけるコーディング、デバッグ、アーキテクチャ設計のタスクを効率化する手順を解説します。
## 前提条件
作業を始める前に、以下の環境を準備してください。
* [SambaCloud](https://cloud.sambanova.ai/apis) アカウントと API キー。キーは `SAMBANOVA_API_KEY` としてエクスポートしておきます。
```bash theme={}
export SAMBANOVA_API_KEY="your-api-key"
```
* Node.js 22 以降のインストール済み環境
## Node.js のインストール
Node.js 22 以降がインストールされていない場合は、[nodejs.org](https://nodejs.org/en/download) からインストーラーをダウンロードするか、[nvm](https://github.com/nvm-sh/nvm) などのバージョンマネージャーを使用してください。
インストールを確認します。
```bash theme={}
node -v
npm -v
```
## セットアップ
### 1. Qwen Code CLI のインストール
npm を使用して Qwen Code をグローバルにインストールします。
```bash theme={}
npm install -g @qwen-code/qwen-code
```
インストールを確認します。
```bash theme={}
qwen --version
```
Qwen Code を起動します。
```bash theme={}
qwen
```
Enter キーを押すと、デフォルトテーマがユーザー設定に適用されます。続いて、認証の設定を求められます。
### 2. SambaNova 連携の設定
**オプション A: 対話形式での設定**
SambaNova は組み込みプロバイダーではないため、カスタム経由で選択します。`/auth` を実行して **Custom Provider** を選択し、SambaNova の認証情報を入力します。これらはターミナルのプロンプトでありシェル変数を展開しないため、変数名ではなくキーそのものを入力してください。
```text theme={}
API_KEY > your-api-key
BASE_URL > https://api.sambanova.ai/v1
MODEL > DeepSeek-V3.1
```
3 つの値を入力したら、Enter キーを押すと CLI の利用を開始できます。
**オプション B: 環境変数**
代わりに、これらの値を環境変数として設定することもできます。
```bash theme={}
export OPENAI_API_KEY=$SAMBANOVA_API_KEY
export OPENAI_BASE_URL="https://api.sambanova.ai/v1"
export OPENAI_MODEL="DeepSeek-V3.1"
```
Qwen Code はこれらの変数を起動時に読み取るため、`qwen` を起動する前にエクスポートしてください。前のステップですでに起動している場合は、いったん終了して同じシェルから `qwen` を再実行してください。そうしないと、実行中のプロセスは新しい値を認識しません。
3 つの変数はすべて揃っている必要があります。Qwen Code が OpenAI 互換プロバイダーを選択するのは、キー、ベース URL、モデルのすべてが空でない値で設定されている場合のみです。いずれか 1 つでも欠けているとプロバイダー自体が選択されず、表示されるエラーにはキーもモデルも言及されないため、たった 1 つのタイポが無関係な障害のように見えてしまいます。`OPENAI_MODEL` の代わりに `QWEN_MODEL` も使用できます。
### 対話 UI を使わない単発プロンプトの実行
`-p` を指定すると、1 つのプロンプトを実行して終了します。スクリプトや CI ジョブに適した実行方法です。
```bash theme={}
qwen -p "Summarize the architecture of this repository" --output-format text
```
このリポジトリのアーキテクチャを要約してください。
`--output-format` には `json` と `stream-json` も指定できます。非対話モードの実行でも同じ 3 つの環境変数を使用します。フォールバックできる入力プロンプトがないため、ここでは環境変数が唯一の認証手段です。
`OPENAI_MODEL` には、[SambaCloud モデル](/docs/ja/models/sambacloud-models) にある任意のモデル ID を指定できます。Qwen Code は、ツール呼び出しを通じてファイルの読み取り・編集やコマンド実行を行うエージェント型のコーディングツールであるため、選択するモデルは [Function calling](/docs/ja/features/function-calling) に対応している必要があります。`DeepSeek-V3.1` は対応しており、コンテキストウィンドウは 128k トークンです。これが、Qwen が一度に考慮できるコードベースの量の上限になります。大規模なリポジトリでは、ツリー全体について尋ねるのではなく、`@app.py` のように `@` でプロンプトの対象を特定のファイルに絞ってください。
## ワークフローの例
このセクションでは、Qwen Code CLI を実際の GitHub プロジェクトでどのように活用できるかを紹介します。よく構成されたいくつかのプロンプトを与えるだけで、Qwen はコードベースの把握、パフォーマンスの最適化、機能の拡張、ドキュメント作成の効率化を支援します。
以下の例を通じて、次の方法を学べます。
* コードベース全体のアーキテクチャを分析する
* メモリ効率を高めるために関数を最適化する
* 新しいコンポーネントを組み込んで機能を拡張する
* バージョン管理された更新を GitHub に直接プッシュする
* すべての更新を明確で構造化された changelog に記録する
それでは、各ステップを順に見ていきましょう。
### 1. コードベースの探索と理解
サンプルリポジトリをクローンし、プロジェクトディレクトリに移動します。
```bash theme={}
git clone https://github.com/AashiDutt/Voxtral_with_vLLM.git
cd Voxtral_with_vLLM
```
Qwen Code CLI を起動します。
```bash theme={}
qwen
```
認証情報をまだ設定していない場合は、上記の [セットアップ](#セットアップ) を参照してください。その後、プロジェクトのアーキテクチャを分析します。
```text theme={}
> Explain the architecture of this codebase.
```
このコードベースのアーキテクチャを説明してください。
Qwen CLI は `app.py`、`config.py`、`requirements.txt` などのファイルを自動的にスキャンし、次のステップの提案とともに、アーキテクチャの概要を生成します。
### 2. コードの最適化とテスト
改善の余地をいくつか特定したら、最も効果の大きい変更のひとつである `transcribe_audio` 関数のメモリ使用量の最適化に取り組みます。このファイルを対象にするには、次のプロンプトを使用します。
```text theme={}
> Optimize the code in transcribe_audio in @app.py
```
@app.py の transcribe\_audio のコードを最適化してください。
Qwen は、メモリ効率、コードの簡潔さ、保守性を網羅した、構造化された改善案を返します。問題点の指摘にとどまらず、具体的なコード修正案も提示します。
Qwen は次の改善を適用します。
1. すべてのチャンクを事前に収集するのではなく、文字起こし結果を直接ストリーミングすることで、メモリ使用量を削減し応答性を向上
2. 文字起こしの完了時にのみ進捗バーを 100% に更新するよう、進捗管理を簡素化
3. エラー発生時にも UI 要素をクリーンアップし、進捗バーとステータステキストが適切にクリアされることを保証
### 3. 新機能の追加
アプリケーションの機能を広げるため、Qwen CLI に YouTube 動画のサポートを追加するよう依頼します。
```text theme={}
> Extend the current example to support YouTube videos. When a user provides a YouTube URL, extract the audio from the video and pass it to the Voxtral model for processing. Keep the rest of the pipeline and components unchanged.
```
現在のサンプルを、YouTube 動画に対応するよう拡張してください。ユーザーが YouTube の URL を指定したら、動画から音声を抽出して Voxtral モデルに渡して処理します。パイプラインとコンポーネントのそれ以外の部分は変更しないでください。
Qwen は `app.py`、`config.py`、`requirements.txt` を分析し、`yt-dlp` と `pydub` がすでにプロジェクトの依存関係として記載されていることを特定します。
Qwen は `app.py` を編集して、既存のファイルアップロードと並ぶ YouTube URL フィールドを追加し、抽出した音声を文字起こしパイプラインにルーティングし、残りの作業をタスクリストとして管理します。送信すると、アプリは音声を抽出し、既存のパイプラインで処理します。
### 4. 変更の GitHub へのプッシュ
`transcribe_audio` の最適化が完了したら、Qwen CLI を使用して更新をバージョン管理し、プッシュします。
```text theme={}
> Create a new branch on GitHub and commit and push the updated code as a second version with the message: "v2: Optimized transcribe_audio for memory usage".
```
GitHub に新しいブランチを作成し、更新後のコードを第 2 バージョンとして、メッセージ "v2: Optimized transcribe\_audio for memory usage" でコミット・プッシュしてください。
Qwen は、git コマンドを代わりに実行することで Git のフロー全体を自動化します。1 つのプロンプトで、次の操作を実行できます。
1. 新しいブランチの作成
2. 変更のステージングとコミット
3. コミットのプッシュの試行
プッシュ自体は、書き込みアクセス権を持つリポジトリに対してのみ成功します。上記のサンプルリポジトリは他者の所有であるため、プッシュするとスクリーンショットのとおり `403` と `Permission to ... denied` のメッセージが返されます。ブランチとコミットはローカルに作成されているため、失われるものはありません。このステップを完了するには、先に [リポジトリをフォーク](https://github.com/AashiDutt/Voxtral_with_vLLM/fork) してフォークの方をクローンするか、ご自身のリポジトリでこのワークフローを実行してください。
### 5. 更新内容のドキュメント化
最後に、Qwen CLI にプロフェッショナルな形式でドキュメントを生成するよう依頼します。
```text theme={}
> Document these changes in CHANGELOG.md following semantic versioning.
```
これらの変更を、セマンティックバージョニングに従って CHANGELOG.md に記録してください。
Qwen は WriteFile ツールを使用して、セマンティックバージョニングのベストプラクティスに従い、バージョン v0.2.0 として `CHANGELOG.md` にエントリを書き込みます (プロジェクトにファイルがない場合は新規作成します)。また、いったん処理を開始すると重複した更新を避けるため、トークンを節約しつつ、簡潔で重複のないドキュメントを維持できます。
## まとめ
SambaNova モデルを Qwen Code CLI に接続することで、開発ワークフローを効率化できます。反復的なコーディング作業にかかる時間を削減し、コンテキストの切り替えを減らし、柔軟なエージェントロールによってさまざまなプロジェクトのニーズに素早く対応できます。
## トラブルシューティング
Node.js 20 以前を使用しています。この場合、npm は失敗も警告もせず、`engines` フィールドがお使いの Node バージョンを許容する範囲で最新のリリースを黙ってインストールします。そのためインストールは成功と報告され、CLI も起動し、バージョンが古いことには何も気づけません。`0.16.0` 以降のすべてのリリースは Node.js 22 を必要とするため、Node.js 20 のマシンでは `0.15.10` に解決されます。両者を比較します。
```bash theme={}
qwen --version
npm view @qwen-code/qwen-code version
```
両者が異なる場合は、`node -v` を確認し、Node.js 22 以降にアップグレードしてから再インストールしてください。
`OPENAI_API_KEY` が空文字列に解決されています。これは、`qwen` を実行したシェルで `SAMBANOVA_API_KEY` がエクスポートされていない場合に発生します。`echo $SAMBANOVA_API_KEY` で確認してください。`export` は実行したシェルにのみ適用されるため、新しいターミナルでは再度実行する必要があります。
キーは API に届きましたが、有効ではありませんでした。最も多い原因は、`API_KEY >` プロンプトにリテラル文字列 `$SAMBANOVA_API_KEY` を入力してしまうことです。これらのプロンプトはシェル変数を展開しません。キーそのものを入力してください。
モデル ID は大文字と小文字が区別され、プロバイダーのプレフィックスは付けません。`DeepSeek-V3.1` は動作しますが、`deepseek-v3.1` は 404 を返します。最新の ID を [SambaCloud モデル](/docs/ja/models/sambacloud-models) で確認し、使用したいものを `OPENAI_MODEL` に設定してください。
Qwen Code は起動時に `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL` を読み取るため、実行中のプロセスは起動後にエクスポートされた変数を認識しません。`qwen` を終了し、`echo $OPENAI_BASE_URL` で値を確認してから、同じシェルで再起動してください。
`qwen -p` の実行時に、変数のセットが不完全でした。OpenAI 互換プロバイダーが選択されるのは、キー、ベース URL、モデルのすべてが空でない値で存在する場合のみです。そのため、`OPENAI_API_KEY` が空だったり `OPENAI_MODEL` が未設定だったりすると、認証エラーではなくこのメッセージが表示されます。3 つすべてを出力して再実行してください。
```bash theme={}
echo "${OPENAI_API_KEY:?unset}" "${OPENAI_BASE_URL:?unset}" "${OPENAI_MODEL:?unset}"
```
Qwen はブランチとコミットの作成には成功していますが、書き込みアクセス権のないリポジトリにはプッシュできません。上記のサンプルのように他者のリポジトリをクローンした場合に想定される動作です。リポジトリをフォークし、リモートをフォークに向けたうえで、Qwen に再度プッシュを依頼してください。コミットはすでにローカルに存在するため、やり直しは不要です。
SambaNova は Qwen Code の組み込みプロバイダーではありません。設定は OpenAI 互換の設定を通じて行います。上記のベース URL・キー・モデルの値がまさにその設定です。SambaNova を名前で探すのではなく、これらの値を設定してください。
## 参考情報
詳細は以下をご覧ください。
* [Qwen Code ドキュメント](https://github.com/QwenLM/qwen-code) – CLI の完全なリファレンス、エージェントロール、高度な設定
* [SambaCloud モデル](/docs/ja/models/sambacloud-models) – `OPENAI_MODEL` に設定できるモデル ID
* [SambaNova API リファレンス](/docs/ja/api-reference/overview) – エンドポイントとパラメータ
* [SambaCloud サインアップ](https://cloud.sambanova.ai/apis) – 無料の SambaNova API キーを取得