qwencloud-text

Qwen Text Chat（OpenAI互換）

OpenAI互換APIを通じてQwenモデルを使用し、テキストの生成、会話、コードの作成、ツールの呼び出しを行います。 このスキルは qwencloud/qwencloud-ai の一部です。

スキルのディレクトリ

このスキルの内部ファイルを使用して、実行および学習を行います。デフォルトのパスが機能しない場合や詳細が必要な場合は、必要に応じてリファレンスファイルを読み込んでください。

場所	目的
scripts/text.py	デフォルトの実行方法 — チャット／補完リクエスト、ストリーミング、出力の保存
references/execution-guide.md	フォールバック：curl、Python SDK、関数呼び出し、思考モード
references/api-guide.md	APIの補足とコード例の全容
references/prompt-guide.md	プロンプトエンジニアリング：CO-STARフレームワーク、CoT、少数ショット、タスクの手順
references/sources.md	公式ドキュメントのURL（手動での参照のみ）

セキュリティ

APIキーや認証情報を平文で出力してはいけません。 常に変数参照を使用してください（シェルでは $QWENCLOUD_API_KEY、Pythonでは os.environ["QWENCLOUD_API_KEY"]）。スクリプトは QWENCLOUD_API_KEY、次に QWEN_API_KEY、最後に DASHSCOPE_API_KEY の順に受け付けます。認証情報の確認や検出は、必ず平文を使わずに行ってください。「設定済み」「未設定」「有効」「無効」などの状態のみを報告し、値を表示してはいけません。秘密情報が含まれている可能性のある .env ファイルや設定ファイルの内容は、決して表示しないでください。

APIキーが設定されていない場合、ユーザーに直接キーの提供を求めてはいけません。 代わりに、プレースホルダー（QWENCLOUD_API_KEY=sk-your-key-here）を含む .env ファイルの作成を支援し、実際のキーに置き換えるよう、QwenCloud Console からキーを取得するよう案内してください。実際のキー値を書き込むのは、ユーザーが明示的に依頼した場合に限ります。

互換性に関する重要事項

スクリプトは標準のQwenCloud APIキー（sk-...）とToken Planキー（sk-sp-...）の両方に対応しています。Token Planキーは自動的にToken Planエンドポイントにルーティングされます。対応モデルについては、Token Planモデルカタログを参照してください。CDNへのアクセスに失敗した場合は、ローカルの代替ファイルを使用してください。

Token Planではcurlを使用せず、必ず同梱のPythonスクリプトを使用してください。

Coding Planキーも sk-sp- で始まりますが、Coding Planサブスクリプションを通じて購入したキーは、対話型コーディングツール専用のため、これらのスクリプトでは使用できません。qwencloud-ops-authがインストールされている場合は、キーの種類、エンドポイントの対応関係、エラーコードについて references/codingplan.md を参照してください。

キーを公開せずにAPIキーの種類を検出します：

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qwencloud_lib import detect_api_key_type
print(detect_api_key_type('scripts/qwencloud_lib.py'))
"

出力	意味
token-plan	Token Planキーが検出されました（sk-sp-プレフィックス）
payg	標準のPAYGキーが検出されました
not-set	環境内にAPIキーが見つかりません

モデルの選択

🚫 重大 — ユーザーが指定したパラメーターを絶対に上書きしないでください。 ユーザーがプロンプトまたはリクエスト JSON でモデルを明示的に指定した場合は、必ずそのモデルをそのまま使用してください。次のことは禁止されています。

• 「より適している」モデルや新しいモデルに置き換えること（例：タスクが「推論のように見える」という理由で、ユーザーが指定した qwen3.7-max を思考モデルに変更する）
• ユーザーが求めていないパラメーターを追加すること（enable_thinking、enable_search、スタイルのヒントなど）
• ユーザーが明示的に選択した内容を「最適化」すること

以下の選択ガイダンスは、ユーザーがモデルを指定していない場合にのみ適用されます。

モデルを選択、推奨、またはデフォルト設定する前に、最新のQwenCloud テキストモデルカタログを取得して読んでください。カタログには、最近の Qwen 汎用モデル、基本情報、推奨事項、およびデフォルトモデルが記載されています。コーディング、翻訳、またはサードパーティのモデルファミリーについては、qwencloud-model-selector または QwenCloud CLI を参照してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

1. ユーザーがモデルを指定している → 必須：指定されたモデルをそのまま使用する — 置き換えたり、「最適化」したり、要求されていないパラメーターを追加したりしないでください。
2. モデルの選択が要件、シナリオ、または料金によって異なる場合は、qwencloud-model-selector スキルを参照してください。
3. 判断材料がなく、タスクが明確 → モデルカタログのデフォルトを使用します。

⚠️ 重要：モデルカタログは特定時点のスナップショットであり、古くなっている可能性があります。モデルの提供状況は頻繁に変わります。モデルを決定する前に、必ず最新情報を確認するための正式なカタログとして公式モデル一覧を確認してください。

モデルの詳細：特定のモデルについて詳しく知りたいユーザーには、その詳細ページを案内してください：https://www.qwencloud.com/models/<model-name>（<model-name> は正確なモデル ID に置き換えます。例：qwen3.6-plus → https://www.qwencloud.com/models/qwen3.6-plus）。URL 内のモデル名を変更したり、推測したりしないでください。

動的なモデル情報の照会：qwencloud-model-selector スキルまたは QwenCloud CLI（qwencloud models info <model>）が利用できる場合は、リアルタイムのモデル情報の取得に使用してください。CLI の使用には認証が必要です。ログイン手順については、qwencloud-usage スキルを参照してください。

実行

前提条件

• API キー：QWENCLOUD_API_KEY、QWEN_API_KEY、続いて DASHSCOPE_API_KEY を、平文を表示しない方法だけで確認してください（例：シェルで [ -n "$QWENCLOUD_API_KEY" ] を実行し、「設定済み」または「未設定」のみを報告する。キーの値は決して表示しない）。未設定の場合は、利用可能であれば qwencloud-ops-auth スキルを実行してください。利用できない場合は、QwenCloud Consoleでキーを取得し、.env ファイル（プロジェクトルートまたは現在のディレクトリで echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env を実行）または環境変数を使用して設定するようユーザーに案内してください。 スクリプトは、現在の作業ディレクトリとプロジェクトルートで .env を検索します。スキルは個別にインストールされている場合があるため、qwencloud-ops-auth が利用できるとは限りません。 注：スクリプトは、エクスポート済みの環境変数に加えて、現在のディレクトリとプロジェクトルートの .env を自動的に読み込みます。シェルの確認で $QWENCLOUD_API_KEY が「未設定」と表示されても、スクリプトが失敗するとは限りません。.env からキーを取得できる場合があります。シェルの確認結果は参考情報として扱い、キーがどこにも見つからない場合に明確なエラーを出して終了するスクリプトの実行結果を、唯一の確実な確認方法としてください。
• Python 3.9 以降（標準ライブラリのみ。スクリプトの実行に pip install は不要）

環境の確認

初回実行の前に、Python が利用できることを確認してください。

python3 --version  # must be 3.9+

python3 が見つからない場合は、python --version または py -3 --version を試してください。Python が利用できない場合、またはバージョンが 3.9 未満の場合、PAYG は **パス 2（curl）**を使用できますが、Token Plan では Python 3.9 以降をインストールする必要があります。

デフォルト：スクリプトを実行

スクリプトのパス：スクリプトは、このスキルのディレクトリ（この SKILL.md があるディレクトリ）内の scripts/ サブディレクトリにあります。最初にこのスキルのインストールディレクトリを特定し、その後、スクリプトの実行には必ず絶対パスを使用してください。 スクリプトが現在の作業ディレクトリにあると想定しないでください。実行前に cd でディレクトリを切り替えないでください。

実行に関する注意：すべてのスクリプトはフォアグラウンドで実行してください。stdout を待ち、バックグラウンドでは実行しないでください。

確認：まず python3 <this-skill-dir>/scripts/text.py --help を実行して、使用可能なすべての引数を確認してください。

python3 <this-skill-dir>/scripts/text.py \
  --request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.7-plus"}' \
  --output output/qwencloud-text/ --print-response

ストリーミングの場合（対話的な使用に推奨）：

python3 <this-skill-dir>/scripts/text.py \
  --request '{"messages":[{"role":"user","content":"Write a poem about the sea"}],"model":"qwen3.7-plus"}' \
  --stream --print-response

引数	説明
--request '{...}'	JSON リクエスト本文
--file path.json	ファイルからリクエストを読み込む（--request の代替）
--stream	ストリーミング出力を有効にする
--output path	応答 JSON をパスに保存する（.json の接尾辞がある場合はファイル、ない場合はディレクトリ）。上書きを避けるため、呼び出しごとに異なるファイル名を使用してください
--print-response	応答を stdout に出力する
--model ID	モデルを上書きする（リクエスト JSON でも設定可能）

結果を確認する

• 終了コードが 0 で、出力に choices フィールドを含む有効な JSON がある → 成功
• 終了コードが 0 以外、HTTP エラー、空の応答、または "code"／"message" エラーを含む JSON → 失敗
• エージェントが終了コードを読み取れない場合は、出力にエラーパターン（Error、Traceback、401、403）がないか確認する
• 実行後の確認：--output を使用した場合は、応答 JSON ファイルが存在し、choices が含まれていることを確認する
• 必須 — stderr シグナルの確認：結果を確認した後、コマンドの stderr 出力に [ACTION_REQUIRED] または [UPDATE_AVAILABLE] がないか確認してください。いずれかのシグナルがある場合は、ユーザーに応答する前に、以下の 更新の確認 の指示に必ず従ってください。

失敗した場合

スクリプトが失敗した場合は、エラー出力を以下の診断表と照合して、解決方法を確認してください。一致するものがない場合は、別の方法として、execution-guide.md の curl コマンド（パス 2）、Python SDK によるコード生成（パス 3）、自律的な解決（パス 5）を確認してください。

Python がまったく利用できない場合 → PAYG ではパス 2（curl）を使用できます。Token Plan では、execution-guide.md に従って Python 3.9 以降をインストールする必要があります。

エラーのパターン	診断	解決方法
command not found: python3	Python が PATH にありません	python または py -3 を試してください。見つからない場合は Python 3.9 以降をインストールしてください
Python 3.9+ required	スクリプトのバージョンチェックに失敗しました	Python を 3.9 以降にアップグレードしてください
SyntaxError near type hints	Python が 3.9 未満です	Python を 3.9 以降にアップグレードしてください
QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QwenCloud Console からキーを取得し、.env に追加してください：echo 'QWENCLOUD_API_KEY=sk-...' >> .env。または、利用可能な場合は qwencloud-ops-auth を実行してください
HTTP 401	キーが無効、または一致していません	qwencloud-ops-auth を実行してください（非平文チェックのみ）。キーが有効であることを確認してください
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題（プロキシ／社内ネットワーク）	macOS：Install Certificates.command を実行してください。それ以外の場合は SSL_CERT_FILE 環境変数を設定してください
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認してください。プロキシ経由の場合は HTTPS_PROXY を設定してください
HTTP 429	レート制限されています	待機してから、間隔を空けて再試行してください
HTTP 5xx	サーバーエラーです	間隔を空けて再試行してください
PermissionError	出力を書き込めません	--output を使って、書き込み可能なディレクトリを指定してください

クイックリファレンス

リクエストフィールド

フィールド	型	説明
prompt / messages	string | array	ユーザー入力またはメッセージのリスト
model	string	モデル ID（例：qwen3.7-plus）
system	string	システムプロンプト（省略可）
temperature	float	0～2。ランダム性を制御します
max_tokens	int	最大出力トークン数
tools	array	ツール呼び出し用の関数定義
stream	bool	ストリーミングを有効にします（対話形式での使用を推奨）
enable_thinking	bool	思考モードを上書きします。モデルごとにデフォルト設定が異なるため、上記のモデルカタログを確認してください。ユーザーからデフォルト設定の変更を明示的に求められない限り、このフィールドは設定しないでください。

レスポンスフィールド

フィールド	説明
text	生成されたテキストコンテンツ
model	使用されたモデル
usage	トークン使用量（prompt_tokens、completion_tokens）
tool_calls	関数呼び出しリクエスト（ツールを使用した場合）

高度な機能

これらは、リクエストパラメーターを通じてサポートされる API レベルの機能です。すべて同じ chat/completions エンドポイントを使用します。

機能	有効化方法	備考
構造化出力	response_format: {"type": "json_schema", "json_schema": {...}}	スキーマに準拠する JSON 出力を強制します
ウェブ検索	enable_search: true	リアルタイムのウェブ検索で拡張された応答
深い思考	enable_thinking: true	拡張推論。ユーザーからのリクエストがある場合のみ
関数呼び出し	tools: [...]	ツールで使用する関数を定義します
コンテキストキャッシュ	繰り返し使われるプレフィックスに対して自動適用、または明示的なセッションベース	繰り返し使われるコンテキストのコストを削減します
部分モード	partial_mode: "prefix"	プレフィックスを続ける、または完成させます
バッチ推論	JSONL 入力による非同期バッチ API	50％のコスト割引

各機能の詳細な使用方法については、api-guide.md と sources.md を参照してください。

エラー処理

エラー	原因	対応
401 Unauthorized	API キーが無効、または設定されていない	利用可能であれば qwencloud-ops-auth を実行します。それ以外の場合は、ユーザーにキーの設定を促します（平文でないことの確認のみ）
429 Too Many Requests	レート制限を超過	バックオフして再試行します
500 / 502 / 503	サーバーエラー	再試行し、ステータスページを確認します
Invalid model	モデル ID が見つからない	上記のモデルカタログで ID を確認します
Invalid parameter	リクエスト本文が不正	JSON とフィールドの型を検証します
TypeError: ...proxies	openai SDK と httpx の互換性がない	pip install --upgrade openai（>=1.55.0）を実行するか、スクリプト（標準ライブラリのみ）を使用します

使用量と請求：使用量、無料枠の上限、請求を直接確認するには、qwencloud-usage スキルを使用してください。または、ユーザーは QwenCloud コンソールにアクセスできます。 使用状況分析 | 従量課金制の請求 | コーディングプランの請求

**使用量／請求／コンソールの URL を決して捏造、推測、作成しないでください。**このスキルに記載されている正確なリンクのみを提供してください。ここに記載されていない URL は作成しないでください。

出力先

すべての出力には現在の作業ディレクトリを使用してください。--output を使う場合のデフォルトのサブディレクトリは次のとおりです。 ./output/qwencloud-text/.

書き込み禁止：このスキルのインストールディレクトリや、skills/ 階層には、絶対に出力ファイルを書き込まないでください。生成したコンテンツはすべて、現在の作業ディレクトリ配下の output/、またはユーザーが指定したパスに保存してください。

Token Plan のサポート

Token Plan キー（sk-sp-...）は完全にサポートされています。Token Plan キーが検出されると、スクリプトは自動的に Token Plan エンドポイント（token-plan.ap-southeast-1.maas.aliyuncs.com）に接続します。

サポート対象モデル

最新の Token Plan モデルカタログを取得して読み込み、一覧に記載されたテキスト対応モデルを正確に指定してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

動作

• Token Plan キー + サポート対象モデル → Token Plan エンドポイントに自動接続し、通常どおり実行します
• Token Plan キー + サポート対象外モデル → TP エンドポイントでリクエストが失敗する場合があります。上記のカタログを確認してから、サポート対象モデルへの切り替え、または PAYG キーの使用を提案してください
• Coding Plan キー → スクリプトはコーディングエージェントではないため、呼び出しは失敗します。代わりに、標準の PAYG キーまたは Token Plan キーを使用してください。

必須ヘッダー

User-Agent: qwencloud-skills は、すべてのリクエストに自動的に含まれます。

更新確認（実行後に必ず実施）

スクリプトの実行後、stderr にアクションを示すシグナルがないか確認してください。スクリプトは更新状況を自動で検出し、構造化されたシグナルを出力します。これらのシグナルには必ず対応してください。このセクションは、ユーザーが明示的に更新確認を依頼した場合にも適用されます。

シグナル：[ACTION_REQUIRED] qwencloud-update-check skill is not installed

stderr にこのシグナルが含まれている場合は、以下の選択肢をユーザーに提示し、処理を続行する前に回答を待ってください。黙ってスキップしてはいけません。

更新確認スキルがインストールされていません。このスキルは、qwencloud/qwencloud-ai の新機能やバグ修正についてお知らせします。

1. 今すぐインストール — インストールコマンドを実行します
2. 今回はスキップ — 今回は何もしません
3. 今後は通知しない — この確認を今後表示しないようにします

ユーザーの回答後：

• ユーザーが 1 を選択 → 次を実行します： npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y。次に、次を実行します： python3 <this-skill-scripts-dir>/gossamer.py --dismiss
• ユーザーが 2 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行してから、通常どおり続行します
• ユーザーが 3 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --never-install を実行してから、通常どおり続行します

シグナル：[UPDATE_AVAILABLE]

stderr にこのシグナルが含まれている場合は、バージョン情報と stderr に表示された更新コマンドを含む、簡潔な更新通知を必ず回答に追加してください。

stderr にシグナルがない場合

stderr に [ACTION_REQUIRED] も [UPDATE_AVAILABLE] も含まれていない場合、対応は不要です。スキルはインストール済みで最新の状態です（または24時間以内にキャッシュされています）。

ユーザーから明示的に依頼された場合

ユーザーが更新確認を明示的に依頼した場合（例：「更新を確認して」「バージョンを確認して」）：

1. 同階層のスキルディレクトリに qwencloud-update-check/SKILL.md があるか確認します。
2. 見つかった場合 — python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからない場合 — 上記のインストール विकल्पを提示します。

参考資料

• execution-guide.md — フォールバック手順（curl、SDK、自律実行）、関数呼び出し、思考モード
• api-guide.md — 完全なコード例を含む API 補足ガイド
• sources.md — 公式ドキュメントの URL