alibabacloud-agent-toolkit-install

Alibaba Cloud Agent Toolkit — インストール

このスキルでは、前提条件をすべて整え、Alibaba Cloud Agent Toolkit をインストールします。 各ステップを順番に実行してください。後続のステップは先行するステップに依存します。

安全性ポリシー

各ステップはリスクレベルで分類されています。次のルールに厳密に従ってください。

分類	エージェントの動作
Auto（読み取り専用の確認）	確認を求めずに実行します。
Confirm（ローカルへのインストール／CLI プラグインのインストール）	正確なコマンドをユーザーに示し、実行内容を説明してから、実行前に明示的な承認を待ちます。許可なくパイプでシェルに渡して実行してはいけません。
User-only（対話式／ブラウザーベース）	ユーザーが別のターミナルで実行するための手順を表示します。実行を試みてはいけません。
Confirm-cloud（クラウド側への書き込み）	作成されるクラウドリソースを説明してから、実行前に明示的な承認を待ちます。

---

前提条件

事前確認：Aliyun CLI >= 3.3.3 が必要です

aliyun version を実行して、バージョンが 3.3.3 以上であることを確認します。未インストールの場合、またはバージョンが低い場合は、 /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/setup.sh)" を実行してインストールまたは更新します。

可観測性（すべての aliyun コマンドで必ず従うこと）

クラウド API を呼び出す前に、このスキルのルートにある references/manifest.json を読み込み、トップレベルの空でない文字列 version のみを {skill-version} として使用します。値がないか無効な場合は、停止してください。バージョンを捏造、推測、または別のスキルのバージョンを再利用してはいけません。

バージョンとセッションを、現在のスキル名およびスキルのルートに紐付けます。このスキルで会話中に初めてクラウド API を呼び出す前に、新しいランダムな 32 文字の小文字の 16 進数セッション ID を生成します。このスキルでは、会話中を通じてそのセッション ID を再利用します。各スキルは、それぞれ異なるセッション ID を使用する必要があります。ドキュメント、例、別のスキル、または以前の会話からコピーしてはいけません。また、{session-id} というプレースホルダーをそのまま送信してはいけません。スキルを切り替えた場合や戻った場合は、そのスキルのマニフェストを読み直してください。どちらの値もスキル間で再利用してはいけません。

ルール：クラウド API を呼び出すすべての aliyun CLI コマンドには、--user-agent フラグを含める必要があります。

Markdown の例では、簡潔さのためにフラグを省略する場合があります。エージェントは、実行時に生成または拡張したコマンドを含め、実際に実行するすべてのコマンドに正確なフラグを追加する必要があります。

ローカルユーティリティコマンド（例：configure、plugin、version）はこのフラグに対応していないため、対象から除外してください。

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agent-toolkit-install/{session-id} skill-version/{skill-version}"

---

チェックリストの概要

次のステップを順番に実行します。確認に合格しているステップはスキップしてください。

1. uv の確認／インストール — Confirm
2. Alibaba Cloud CLI（aliyun）の確認／インストール — Confirm
3. CLI 認証の確認 — Auto（確認）／User-only（ログイン）
4. CLI プラグインの確認／インストール — Confirm
5. MCP Server Core の確認／作成 — Auto（確認）／Confirm-cloud（作成）
6. Bearer トークン交換の確認 — Auto（確認）
7. Alibaba Cloud Agent Toolkit のインストール — Confirm

ステップ 1：uv {#step-1-uv}

uv は、MCP サーバーの起動に必要な Python パッケージマネージャーです。

確認（Auto）

uv --version

• 成功 → 出力にバージョン文字列（例：uv 0.6.x）が表示されます。ステップ 2 に進みます。
• 失敗 → command not found が表示されます。以下の手順でインストールしてください。

インストール（確認 — 実行前にユーザーに確認する）

適切なコマンドをユーザーに提示し、承認を待ちます。

プラットフォーム	コマンド
macOS / Linux	curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell)	powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

セキュリティに関する注意： これらはパイプでシェルに渡すコマンドです。コマンドをユーザーに提示し、 実行するかどうかはユーザーに判断してもらいます。明示的な同意なしに実行してはいけません。

インストール後、uv --version で確認します。シェルで uv が見つからない場合は、 PATH の更新を反映するため、ターミナルを再起動するか、シェルのプロファイルを読み込むようユーザーに 案内します（source ~/.bashrc、source ~/.zshrc など）。

---

ステップ 2：Alibaba Cloud CLI（aliyun）{#step-2-aliyun-cli}

確認（自動）

aliyun version

• 成功 → バージョン 3.3.3 以降が出力されます。ステップ 3 に進みます。
• 失敗 → command not found またはバージョンが 3.3.3 未満です。以下の手順でインストールまたは更新します。

インストール（確認 — 実行前にユーザーに確認する）

適切なコマンドをユーザーに提示し、承認を待ちます。

macOS / Linux

/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

セキュリティに関する注意： これはパイプでシェルに渡すコマンドです。コマンドをユーザーに提示し、 実行するかどうかはユーザーに判断してもらいます。明示的な同意なしに実行してはいけません。

Windows (PowerShell)

インストーラースクリプトは scripts/install-aliyun-cli-windows.ps1 にあります。

スクリプトをダウンロードまたはコピーしてから、次を実行するようユーザーに案内します。

powershell.exe -ExecutionPolicy Bypass -File .\install-aliyun-cli-windows.ps1

インストール後、aliyun version で確認します。コマンドが見つからない場合は、 更新された PATH を反映するため、新しいターミナルセッションを開くようユーザーに案内します。

---

ステップ 3：CLI 認証 {#step-3-cli-authentication}

確認（自動）

aliyun sts get-caller-identity --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agent-toolkit-install/{session-id} skill-version/{skill-version}"

• 成功 → AccountId、Arn、UserId を含む JSON が返されます。認証モード（AK または OAuth）を記録します。これはステップ 6 に影響します。ステップ 4 に進みます。
• 失敗 → エラーレスポンス（例：InvalidAccessKeyId、ERROR: ...、 または同様のエラー）が返されます。以下の OAuth ログインをユーザーに案内します。

注： aliyun sts get-caller-identity の出力から、現在のユーザーがわかります。 正しい ID が使用されていることを確認できるよう、この情報をユーザーと共有してください。

OAuth ログイン（ユーザーのみ — ユーザーは別のターミナルで実行する必要があります）

OAuth ログインフローは対話型で、ブラウザーが開きます。エージェントはこれを実行してはいけません。 次の手順をユーザーに表示します。

Please run this command in a separate terminal:

    aliyun configure --mode OAuth --profile <ProfileName>

Replace <ProfileName> with a name of your choice (e.g. "default", "myprofile").
This will open a browser for Alibaba Cloud login. Follow the prompts to complete authentication.

ユーザーが OAuth フローを完了したと確認したら、プロファイルを現在のものに設定し、 確認コマンドを再実行します。

aliyun configure set --current <ProfileName>
aliyun sts get-caller-identity --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agent-toolkit-install/{session-id} skill-version/{skill-version}"

それでも失敗する場合は、プロファイルを確認するようユーザーに提案します。

aliyun configure list

---

ステップ 4：CLI プラグイン {#step-4-cli-plugins}

2 つの CLI プラグインが必要です。それぞれを確認し、インストールされていないものがあればインストールします。

確認（自動）

aliyun plugin show --name openapiexplorer
aliyun plugin show --name sts

• すべて成功 → それぞれのプラグインのメタデータが出力されます。ステップ 5 に進みます。
• いずれかが失敗 → plugin not found またはエラーが返されます。以下の手順で不足しているプラグインをインストールします。

インストール（確認 — 実行前にユーザーに確認する）

不足しているプラグインだけをインストールします。コマンドを表示し、承認を待ちます。

aliyun plugin install --name openapiexplorer
aliyun plugin install --name sts

インストール後、確認コマンドを再実行して検証します。

---

ステップ 5：MCP サーバーコア {#step-5-mcp-server-core}

MCP サーバーコアはクラウド側のリソースで、アカウントごとに一度だけ作成できます。

確認（自動）

aliyun openapiexplorer list-api-mcp-server-cores --region cn-hangzhou --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agent-toolkit-install/{session-id} skill-version/{skill-version}"

• 成功 → レスポンスに "totalCount": 1 が含まれます。MCP コアはすでに存在します。ステップ 6 に進みます。
• 失敗（totalCount 0） → コアが存在しません。以下の手順で作成します。
• 失敗（権限エラー） → ユーザーの RAM ID に必要な権限がありません。 以下の権限エラーを参照してください。

作成（Confirm-cloud — 実行前にユーザーに確認）

これにより、ユーザーの Alibaba Cloud アカウント（リージョン：cn-hangzhou）にクラウド側の MCP Server Core リソースが作成されます。このことをユーザーに説明し、明示的な承認を待ってください。

aliyun openapiexplorer create-api-mcp-server-core --region cn-hangzhou --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agent-toolkit-install/{session-id} skill-version/{skill-version}"

想定される結果：

結果	意味	対応
成功（200）	Core が作成されました	チェックを再実行し、totalCount: 1 を確認します
クォータ超過エラー	Core はすでに存在します（作成できるのは 1 つのみ）	成功として扱います — Core はすでにプロビジョニングされています
権限拒否／Forbidden	RAM 権限がありません	以下を参照してください

権限エラー {#permission-error}

MCP Core の一覧表示または作成時に権限エラーが発生した場合、ユーザーは次のシステムポリシーを RAM ID にアタッチする必要があります。

AliyunOpenAPIMCPServerStaticCredentialAccess

ユーザー（またはアカウント管理者）に、次の操作を行うよう案内してください。

1. RAM Console に移動します
2. 使用中の RAM ユーザーまたはロールを見つけます
3. システムポリシー AliyunOpenAPIMCPServerStaticCredentialAccess をアタッチします
4. チェック／作成コマンドを再実行します

---

ステップ 6：ベアラートークンの交換 {#step-6-bearer-token-exchange}

このステップでは、MCP Server Core がベアラートークンを正常に交換できることを確認します。これは、MCP サーバーが実行時に API 呼び出しを認証するために必要です。

チェック（自動）

重要 — 以下のコマンドを正確に使用してください。変更や置き換えはしないでください。

aliyun RamOAuth GenerateAccessToken は標準仕様外の aliyun CLI 呼び出しです。 通常の aliyun <product> <action> パターンには従わず、aliyun help、製品一覧、OpenAPI メタデータにも表示されません。製品名の RamOAuth、アクションの GenerateAccessToken、--version、--ClientId、 --Scope、--endpoint、--method の各フラグはすべてハードコードされた値であり、 そのまま使用する必要があります。

次のことはしないでください。

• 代替コマンドの特定や構築を試みる（例：aliyun auth ...、 aliyun ram ...、aliyun sts ...）
• トークン交換機能を「確認」するために RAM／STS／IMS API を呼び出す — これらの API は 異なる目的で使用されます
• このステップを省略したり、別の検証方法に置き換えたりする

以下に記載されたコマンドをそのままコピーして実行してください。

aliyun RamOAuth GenerateAccessToken \
  --version 2026-04-21 \
  --ClientId 4071151845732613353 \
  --Scope "/internal/acs/openapi" \
  --force \
  --endpoint ramoauth.aliyuncs.com \
  --method POST \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agent-toolkit-install/{session-id} skill-version/{skill-version}"

• 成功 → 有効なトークン応答が返されます。すべての前提条件が満たされています。
• 失敗（権限エラー） → トークン権限エラーを参照してください。
• 失敗（その他のエラー） → OAuth アプリケーションがインストールされていない場合を参照してください。

トークン権限エラー {#token-permission-error}

エラーが権限不足を示している場合（例：Forbidden、NoPermission、 User not authorized）、ユーザーには次のシステムポリシーが必要です。

AliyunOpenAPIMCPServerStaticCredentialAccess

これはステップ 5 で必要なものと同じポリシーです。すでにアタッチされている場合は、aliyun sts get-caller-identity を再確認し、現在の RAM ID に適用されていることを確認してください。

OAuth アプリケーションがインストールされていない場合 {#oauth-app-not-installed}

エラーが権限エラーではない場合（例：InvalidClient、AppNotFound、その他の理由でトークン交換に失敗する場合）、ユーザーはAPI MCP Server の公式 OAuth アプリケーションをインストールしていないか、現在のユーザーを認可していない可能性があります。

ユーザーに次の操作を行うよう案内してください。

1. RAM Applications Console を開きます
2. 公式アプリケーション API MCP Server を見つけてインストールします
3. 現在の RAM ユーザー／ロールに、アプリケーションの使用を許可します
4. トークン交換チェックを再実行します

AK モードユーザー {#ak-mode-users}

ユーザーがステップ 3 で AK モード（AccessKey）を使用して認証した場合、ベアラートークンの交換は API MCP Server の OAuth アプリケーションがなくても動作します。AK 認証情報でトークンを直接交換できます。

• OAuth アプリケーションをインストールせずに AK モードでのトークン交換が成功した場合、AK モードのみを使用しており、アプリケーションの対象範囲を縮小したいのであれば、RAM アプリケーションコンソールでデフォルトの OAuth アプリケーションを削除してもよいことをユーザーに伝えてください。
• AK モードでのトークン交換が失敗した場合、問題は AliyunOpenAPIMCPServerStaticCredentialAccess ポリシーにある可能性があります。トークン権限エラーを参照してください。

---

ステップ 7：Alibaba Cloud Agent Toolkit をインストールする {#step-7-install-toolkit}

前提条件はすべて満たされています。次に、ツールキット自体をインストールします。

QwenWork を検出する（自動）

インストーラーを選択する前に、現在のプロセス環境を確認してください。

if [ "${QODER_WORK_INTEGRATION_PRODUCT:-}" = "qwenworkcn" ] || \
   { [ "${QODERCN_CLI:-}" = "1" ] && [ "${QODERWORK_IS_CN:-}" = "true" ]; }; then
  echo qwenworkcn
else
  echo other
fi

• qwenworkcn → 以下の QwenWork の手順を使用します。openplugin は実行しないでください。
• other → 以下の既存の openplugin の手順を使用します。

QwenWork のインストール（確認 — 実行前にユーザーに確認）

次の 3 つのプラグインスイートをインストールします。

• alibabacloud-core
• alibabacloud-spec-ops
• alibabacloud-ecs-ops

公式ツールキットを一時ディレクトリにクローンし、選択したプラグインパッケージを検証したうえで、各完全ディレクトリを ${QODERCN_CONFIG_DIR:-$HOME/.qwenworkcn}/plugins-custom/ の下にインストールします。QwenWork はこの場所をスキャンして、プラグインの Skills、フック、.mcp.json を登録します。プラグインのスキルをグローバルな skills/ に分けたり、MCP の設定をグローバルな mcp.json に分けたりしないでください。

リポジトリのソース、インストール先、3 つのプラグイン名をユーザーに示し、QwenWork のローカルプラグインを 3 つインストールすることを説明して、明示的な承認を待ってください。承認後、次の手順を実行します。

1. 一時ディレクトリを作成し、https://github.com/aliyun/alibabacloud-agent-toolkit.git をそこにクローンします。
2. alibabacloud-core と alibabacloud-spec-ops の .qoder-plugin/plugin.json を検証します。
3. alibabacloud-ecs-ops/.qoder-plugin/plugin.json がない場合は、親ディレクトリを作成し、その .claude-plugin/plugin.json から有効な JSON 互換マニフェストを生成して、次の項目を追加します。
   • "displayName": "Alibaba Cloud ECS Ops"
   • "hooks": "./hooks/qoderwork-hooks.json"
   • "mcpServers": "./.mcp.json"
4. 選択した各プラグインの一時的な hooks/qoderwork-hooks.json 内にある、リテラル文字列 __PLUGIN_ROOT__ のすべての箇所を、そのプラグインの最終的な絶対インストール先パスに置き換えます。QwenWork 自体が ${QODER_PLUGIN_ROOT} を解決するため、このランタイム変数は変更しないでください。
5. インストール済みプラグインを変更する前に、準備した 3 つすべてのパッケージを検証します。各マニフェストが JSON として解析でき、期待される name を持つこと、宣言されたフックファイルまたは MCP ファイルがすべて存在すること、リテラル文字列 __PLUGIN_ROOT__ が残っていないことを確認します。
6. 必要に応じてインストール先の親ディレクトリを作成します。既存のプラグインはすべて、たとえば ${QODERCN_CONFIG_DIR:-$HOME/.qwenworkcn}/plugin-backups/<name>-<timestamp> のように、plugins-custom の外にあるタイムスタンプ付きバックアップディレクトリへ移動します。恒久的に削除したり、上書きしたりしないでください。
7. 移動後の元のインストール先に、隠しファイルを保持するコマンド（cp -R <source> <destination> など）を使って、各完全プラグインディレクトリを最終的なインストール先にコピーします。
8. 3 つすべてのインストール先で、パッケージの検証を繰り返します。その後、QwenWork に再スキャンと新しいプラグインの登録をさせるため、ユーザーに再起動を依頼します。

QODERCN_CONFIG_DIR が設定されている場合は、そこから QwenWork の設定ディレクトリの絶対パスを解決してください。設定されていない場合に限り、$HOME/.qwenworkcn を使用します。この手順では ~/.qoderwork を使用しないでください。

その他のクライアント：openplugin（確認 — 実行前にユーザーに確認）

重要 — QwenWork 以外では、以下に示すとおり、正確に npx openplugin を使用してください。

このツールキットは openplugin レジストリを通じて配布されています。PyPI、npm、または aliyun plugin では利用できません。

次の操作は行わないでください：

• pip / uv pip install でインストールする（例：alibabacloud-mcp-server やその他の PyPI パッケージ。これらは別のパッケージです）
• npm install でインストールする
• aliyun plugin install でインストールする
• 代替のパッケージ名やインストール方法を検索する

npx openplugin aliyun/alibabacloud-agent-toolkit

コマンドを表示し、実行前に承認を待ってください。

選択した分岐が完了すると、ツールキットのプラグインがインストールされ、使用できる状態になります。

---

完了

7 つすべてのステップが成功したら、概要を報告してください：

Installation complete:
  ✓ uv installed
  ✓ Alibaba Cloud CLI installed
  ✓ CLI authenticated (as <AccountId / UserName>)
  ✓ CLI plugins installed (openapiexplorer, sts)
  ✓ MCP Server Core provisioned
  ✓ Bearer token exchange verified
  ✓ Alibaba Cloud Agent Toolkit installed

Alibaba Cloud Agent Toolkit は使用できる状態です。