qwencloud-ops-auth

QwenCloud 認証の設定

QwenCloud API の認証を設定して検証します。 このスキルは qwencloud/qwencloud-ai の一部です。

スキルディレクトリ

学習には、このスキルの内部ファイルを使用してください。コンソールまたはドキュメントへのリンクが必要な場合にのみ、参照ファイルを読み込んでください。

場所	目的
references/tokenplan.md	Token Plan、Coding Plan、PAYG の比較、CDN モデルカタログ、エンドポイントの対応付け、料金、User-Agent
references/codingplan.md	Coding Plan と標準キーの比較：モデル一覧、エンドポイントの対応付け、エラーコード、コスト上のリスク
references/custom-oss.md	本番環境のファイルアップロード向けカスタム OSS バケットの設定（一時ストレージの 48 時間制限を置き換えます）
references/sources.md	コンソール URL、認証ガイド（手動での参照のみ）

セキュリティ

API キーや OSS 認証情報を平文で絶対に出力しないでください。 これは DASHSCOPE_API_KEY とカスタム OSS AccessKey のペアの両方に適用されます。このスキルで認証情報を確認または検出する場合は、平文を使わず、「設定済み」／「未設定」、「有効」／「無効」、HTTP ステータスコードなどの状態のみを報告してください。キーの値は絶対に報告しないでください。

API キーの取り扱い（必須）

API キーが設定されていない場合や、スクリプトが認証情報の不足を報告した場合：

1. ユーザーに API キーを直接提供するよう絶対に求めないでください。「API キーを貼り付けてください」などと促さないでください。どのような形でもキーの値を要求しないでください。
2. プレースホルダーを含む .env ファイルの作成を支援し、ユーザー自身でキーを入力するよう案内してください：
   • 実行：echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
   • ユーザーに次のように伝えてください：「sk-your-key-here を QwenCloud Console で取得した実際の API キーに置き換えてください。」
3. または、環境変数の設定方法を説明してください：export DASHSCOPE_API_KEY='sk-...' とコンソール URL を案内します。
4. 実際のキーの値を .env に書き込んでよいのは、ユーザーがエージェントに代わりに設定するよう明示的に強く求めた場合に限ります。

認証情報の優先順位

認証情報は次の順序で読み込まれます（一致した最初のものが使用されます）：

1. 環境変数 — DASHSCOPE_API_KEY（または QWEN_API_KEY エイリアス）
2. .env ファイル — 現在の作業ディレクトリ、次にリポジトリのルート（.git または skills/ ディレクトリを使って検出）。既存の環境変数は上書きされません。

環境変数

変数	目的
DASHSCOPE_API_KEY	API キー（必須）
QWEN_API_KEY	DASHSCOPE_API_KEY のエイリアス。両方が設定されている場合は、QWEN_API_KEY が優先されます。
QWEN_BASE_URL	デフォルトのエンドポイントを上書きします（任意、カスタムデプロイ向け）
QWEN_TMP_OSS_BUCKET	ファイルアップロード用のカスタム OSS バケット（一時ストレージの 48 時間制限を置き換えます）。custom-oss.md を参照してください。
QWEN_TMP_OSS_REGION	OSS リージョン（QWEN_TMP_OSS_BUCKET が設定されている場合は必須）。
QWEN_TMP_OSS_AK_ID / AK_SECRET	OSS 認証情報（最小権限の RAM ユーザーを使用してください：oss:PutObject と oss:GetObject）。未設定の場合は、OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET にフォールバックします。

API キーの種類

QwenCloud には、相互に排他的なキー／プランの種類が 3 つあります。

キーの種類	形式	用途	エンドポイント
スタンダード（従量課金）	sk-xxxxx	スクリプト、アプリ、ツールからの API 呼び出し	dashscope-intl.aliyuncs.com
Token Plan	sk-sp-xxxxx	User-Agent ヘッダーを使用する対話型 AI ツール	token-plan.ap-southeast-1.maas.aliyuncs.com
Coding Plan	sk-sp-xxxxx	対話型 AI コーディングツール専用（Cursor、Claude Code、Qwen Code）	coding-intl.dashscope.aliyuncs.com

すべての qwencloud/qwencloud-ai スクリプトでは、スタンダードキー（sk-）が必要です。Coding Plan キー（sk-sp-）をスタンダードエンドポイントで使用すると、401 invalid_api_key が返されます。Token Plan キー（sk-sp-）は、スクリプトによって Token Plan エンドポイントに自動的にルーティングされます。Token Plan のリクエストを送信する前に、最新のToken Plan モデルカタログを取得して読み込み、一覧に記載されている正確なモデル名を指定してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。Coding Plan の詳細はこちらを参照してください。

ユーザーのキーが sk-sp- で始まる場合は、まず tokenplan.md で Token Plan の詳細を確認し、上記の CDN カタログでモデルの対応状況を確認してから、codingplan.md で Coding Plan の詳細を確認してください。プラン対象外のモデルを使用する必要がある場合は、以下のコンソールからスタンダードキーを取得するよう案内してください。

請求額の確認

qwencloud-usage スキルを使用すると、使用量、無料枠のクォータ、請求額を直接確認できます。または、QwenCloud コンソールで請求の詳細を確認できます。

キーの種類	請求ページ
スタンダード（従量課金）	従量課金の請求
Token Plan Personal	個人向け請求
Token Plan Team	チーム向け請求
Coding Plan	Coding Plan の請求
使用状況の分析（両方）	使用状況の分析

**使用状況、請求、コンソールの URL を捏造、推測、または組み立ててはいけません。**このスキルに記載されている正確なリンクのみを提示してください。ここに記載されていない URL を作成してはいけません。

API キーの取得

1. QwenCloud コンソールを開きます
2. QwenCloud アカウントでサインインします
3. API キー管理セクションで API キーを作成するか、コピーします
4. スタンダードキーは sk- で始まります（Coding Plan 専用の sk-sp- ではありません）

セキュリティのベストプラクティス

• API キーをハードコードしないでください。バージョン管理にコミットするソースコードや設定ファイルに記載してはいけません
• 環境変数または .env ファイルを使用してください（.env を .gitignore に追加してください）
• キーを定期的にローテーションし、漏えいしたキーは直ちに無効化してください
• 最小権限を適用してください。可能であれば、用途ごとに専用のキーを作成してください

.env の設定

プロジェクトのルートまたは現在の作業ディレクトリに .env ファイルを作成します。

echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env

スクリプトは、現在の作業ディレクトリとプロジェクトのルート（.git または skills/ ディレクトリから検出）にある .env を自動的に読み込みます。既存の環境変数は .env の値で上書きされません。

.gitignore の記述例

.env
.env.local
*.env

検証

特に明記されていない限り、このスキルで言及されるスクリプトやタスクはフォアグラウンドで実行されます。標準出力を待ってください。バックグラウンドタスクとして実行してはいけません。

**PAYG のみ：**簡単な curl リクエストで認証をテストしてください。Token Plan：curl は使用せず、対象スキルに同梱されている Python スクリプトで検証してください。

curl -sS -X POST "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-turbo","messages":[{"role":"user","content":"Hi"}]}'

成功すると、choices と message.content を含む JSON が返されます。

認証エラーの処理

QwenCloud API キーは QwenCloud コンソールに紐付けられています。無効なキーまたは一致しないキーを使用すると、401 Unauthorized が返されます。

トリガー条件

いずれかのサブスキルが 401 レスポンスを受け取り、平文ではない方法で確認してキーが設定されていることが分かった場合（例： [ -n "$DASHSCOPE_API_KEY" ]。キーの値は出力しないでください）。

プローブコマンド

PAYG では、認証を確認するために軽量なリクエストを送信します。Token Plan モードでは curl を使用せず、対象スキルに同梱された Python スクリプトを実行してください。

curl -sS -o /dev/null -w "%{http_code}" \
  -X POST "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-turbo","messages":[{"role":"user","content":"hi"}]}'

401 が発生した場合：必須の対話による解決

PAYG のプローブで 401 が返された場合は、次の手順を順番に実行してください。

ステップ 1 — キーの入手元を確認する：

Your API key failed authentication.

Please confirm:
1. Your key was created at home.qwencloud.com (QwenCloud console) → re-verify the key
2. My key may be invalid → create a new one at home.qwencloud.com/api-keys

ステップ 2 — ユーザーの選択に従って対応する：

ユーザーの回答	対応
キーは QwenCloud コンソールから取得した	キーが機能することを確認するため、検証を再実行する
キーが無効かもしれない	home.qwencloud.com/api-keys で新しいキーを作成するよう案内する

ステップ 3 — 検証を再実行する。

ステップ 4 — それでも 401 が返される場合、キー自体が無効です。QwenCloud コンソールで新しいキーを作成するよう案内してください。

検証

PAYG では、上記の curl による検証を実行します。Token Plan では、代わりに対象スキルに同梱された Python スクリプトを実行してください。 合格基準：有効な出力を伴う HTTP 200。証跡は output/qwencloud-ops-auth/ に保存してください。

出力と証跡

• 検証結果と診断出力があれば、それらを output/qwencloud-ops-auth/ に保存してください。
• トラブルシューティングに備えて、認証テストの成功記録を保管してください。

出力先

現在の作業ディレクトリを優先します。既定のサブディレクトリ：./output/qwencloud-ops-auth/。

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

更新の確認（実行後に必須）

ユーザーから更新の確認を依頼された場合（例：「更新を確認して」「バージョンを確認して」「新しいバージョンはありますか」「スキルを更新して」）：

1. qwencloud-update-check を探す：同じ階層にあるスキルディレクトリ内で qwencloud-update-check/SKILL.md を探します。
2. 見つかった場合 — 次を実行し、結果を報告します：python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response。ユーザーが強制確認を依頼した場合は --force を使用します。
3. 見つからなかった場合 — 次の選択肢を提示し、ユーザーの返答を待つ必要があります：

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

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

ユーザーの返答後：

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

参考資料

• tokenplan.md — Token Plan と標準キーの違い、CDN モデルカタログの参照先、Credits の課金、およびエンドポイントのガイダンス
• codingplan.md — Coding Plan との互換性とエラーに関するガイダンス
• custom-oss.md — 本番環境でのファイルアップロード向けカスタム OSS バケットの設定
• sources.md — 公式ドキュメントの URL（コンソール、認証ガイド）