qianwen-ops-auth

QianWen 認証の設定

QianWen API の認証を設定して確認します。 このスキルは QianWen-AI/qianwen-ai の一部です。

スキルのディレクトリ

このスキルの内部ファイルを参照して学習してください。ユーザーがコンソールやドキュメントへのリンクを必要とする場合にのみ、参照資料を読み込んでください。

場所	目的
references/tokenplan.md	Token Plan と標準キーの違い、対応モデルの CDN カタログへのリンク、Credits、ポリシー、エラーに関するガイダンス
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 を QianWen Console で取得した実際の API キーに置き換えてください。」
3. または、環境変数の設定方法を説明してください：export DASHSCOPE_API_KEY='sk-...' とコンソール URL を案内します。
4. ユーザーがエージェントに設定を明示的に強く求めた場合に限り、実際のキーの値を .env に書き込んでください。

認証情報の優先順位

認証情報は次の順序で読み込まれます（最初に一致したものが優先されます）。

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

環境変数

変数	目的
DASHSCOPE_API_KEY	API キー（必須）
QIANWEN_API_KEY	DASHSCOPE_API_KEY のエイリアスです。両方が設定されている場合は、QIANWEN_API_KEY が優先されます。
QWEN_BASE_URL	エンドポイントを上書きします（任意。カスタムデプロイやプラン固有の 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 認証情報（最小権限（oss:PutObject + oss:GetObject）の RAM ユーザーを使用してください）。未設定の場合は OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET にフォールバックします。

API キーの種類

QianWen の API キーには、相互に排他的な 2 種類があります。

キーの種類	形式	用途
標準（従量課金）	sk-ws-xxxxx（旧形式 sk-xxxxx）	スクリプト、アプリ、ツールからの API 呼び出し
Token Plan	sk-sp-xxxxx	インタラクティブな AI ツール、およびそれらが現在のユーザー向けに呼び出す Skill／Agent 拡張機能

同梱の実行 Skills は両方のキーの種類に対応しており、sk-sp- のリクエストを Token Plan エンドポイントにルーティングします。Token Plan のリクエストを送る前に、最新の Token Plan モデルカタログを取得して読み、サポート対象のモデルを正確に指定してください。モデルを試したり、自動的にフォールバックしたりしないでください。CDN にアクセスできない場合は、ローカルのフォールバックを使用してください。

キーの種類を判別する（平文を表示しない）

API キー全体を公開せずに呼び出しモードを判別するには、プレフィックス（先頭 6 文字）を確認します。

echo ${DASHSCOPE_API_KEY:0:6}

プレフィックスの出力	キーの種類	課金方式
sk-sp-	Token Plan	クレジット制。モデルカタログは限定されています
sk-ws- またはその他の sk-...	標準（従量課金）	トークンごとの課金。モデルカタログ全体を利用できます

シェルにアクセスできない場合は、キーが sk-sp- で始まるかどうかをユーザーに確認してください。

請求情報の確認

qianwen-usage スキルを使うと、使用状況、無料枠の残量、請求情報を直接照会できます。また、QianWen コンソールでも請求の詳細を確認できます。

キーの種類	請求ページ
標準（従量課金）	従量課金の請求
Token Plan	Token Plan サブスクリプション
使用状況の分析（従量課金）	使用状況の分析

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

API キーの取得

1. QianWen コンソールを開きます
2. QianWen アカウントでサインインします
3. API キー管理セクションで API キーを作成するか、コピーします
4. 従量課金キーは sk-ws-（旧形式は sk-）、Token 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

検証

明示的に別の指定がない限り、このスキルで言及するスクリプトやタスクはすべてフォアグラウンドで実行します。標準出力を待ち、バックグラウンドタスクとして実行しないでください。

簡単な curl リクエストで認証をテストします。

curl -sS -X POST "https://dashscope.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 が返されます。

認証エラーの処理

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

実行する条件

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

確認コマンド

認証を検証するため、軽量なリクエストを送信します。

curl -sS -o /dev/null -w "%{http_code}" \
  -X POST "https://dashscope.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 の場合：必須の対話による解決

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

手順 1 — キーの取得元を確認します：

Your API key failed authentication.

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

手順 2 — ユーザーの選択に従って対応します：

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

手順 3 — 検証を再実行します。

手順 4 — それでも 401 が返される場合、キー自体が無効です。QianWen コンソールから新しいキーを作成するようユーザーを案内してください。

検証

上記の curl 検証コマンドを実行してください。合格基準：choices と message.content を含む有効な JSON を伴う HTTP 200 レスポンスが返されること。証跡として、出力を output/qianwen-ops-auth/ に保存してください。

出力と証跡

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

出力先

現在の作業ディレクトリを優先してください。デフォルトのサブディレクトリ：./output/qianwen-ops-auth/。

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

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

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

1. qianwen-update-check を探します：兄弟スキルディレクトリ内で qianwen-update-check/SKILL.md を探します。
2. 見つかった場合 — python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。ユーザーが強制確認を求めた場合は --force を使用します。
3. 見つからない場合 — 以下の選択肢を必ず提示し、ユーザーの返答を待ちます：

更新確認スキルがインストールされていません。QianWen-AI/qianwen-ai の新機能やバグ修正について最新情報を確認できます。

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

ユーザーの返答後：

• ユーザーが 1 を選択 → npx skills add QianWen-AI/qianwen-ai --skill qianwen-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 を実行し、その後通常どおり続行します

参考資料

• tokenplan.md — Token Plan と標準キーの違い、CDN のモデルカタログへの参照、クレジットの請求、禁止されている使用方法、エラーコード
• custom-oss.md — 本番環境でのファイルアップロードに使用するカスタム OSS バケットの設定
• sources.md — 公式ドキュメントの URL（コンソール、認証ガイド）