alibabacloud-agent-toolkit-install

阿里云 Agent Toolkit — 安装

此技能会配置所有前置条件并安装阿里云 Agent Toolkit。 请按顺序执行每一步——后续步骤依赖前面的步骤。

安全策略

每一步都按风险等级分类。请严格遵循以下规则：

分类	Agent 行为
自动（只读检查）	无需询问，直接执行。
确认（本地安装 / CLI 插件安装）	向用户显示确切的命令，说明其作用，并在执行前等待用户明确批准。绝不可静默地将内容通过管道传给 shell。
仅限用户操作（交互式 / 基于浏览器）	显示操作说明，让用户在单独的终端中运行。请勿尝试执行。
确认云端操作（云端写入）	说明将创建的云资源，然后在执行前等待用户明确批准。

---

前置条件

预检查：需要 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 位小写十六进制会话 ID。在整个对话中，此技能都要复用该会话 ID；每个技能都必须使用不同的会话 ID。绝不可从文档、示例、其他技能或先前的对话中复制会话 ID，也绝不可发送字面量 {session-id} 占位符。切换技能或返回某个技能时，请重新读取该技能的清单；这两个值都不得跨技能复用。

规则：每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。

为简洁起见，Markdown 示例可以省略该标志。Agent 必须在每次实际执行时追加准确的标志，包括运行时生成或扩展的命令。

本地实用程序命令（例如 configure、plugin、version）不支持此标志，应予以排除。

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

---

检查清单概览

请依次完成以下步骤。如果某项检查已通过，请跳过对应步骤。

1. 检查 / 安装 uv — 确认
2. 检查 / 安装阿里云 CLI（aliyun） — 确认
3. 检查 CLI 身份验证 — 自动（检查）/ 仅限用户操作（登录）
4. 检查 / 安装 CLI 插件 — 确认
5. 检查 / 创建 MCP 服务核心 — 自动（检查）/ 确认云端操作（创建）
6. 检查 Bearer 令牌交换 — 自动（检查）
7. 安装阿里云 Agent Toolkit — 确认

步骤 1：uv {#step-1-uv}

uv 是启动 MCP 服务所需的 Python 包管理器。

检查（自动）

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"

**安全提示：**这些命令会将内容传递给 shell 执行。向用户展示命令， 由用户决定是否运行。未经明确同意，不要执行。

安装后，使用 uv --version 验证。如果 shell 找不到 uv， 请告知用户重启终端，或加载其 shell 配置文件（source ~/.bashrc、source ~/.zshrc 等）， 以使 PATH 更新生效。

---

步骤 2：阿里云 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)"

**安全提示：**这是一个将内容传递给 shell 执行的命令。向用户展示命令，由用户 决定是否运行。未经明确同意，不要执行。

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 的输出会告知你当前用户的身份。请将此信息 告知用户，以便他们确认正在使用正确的身份。

OAuth 登录（仅限用户操作 — 用户必须在单独的终端中运行）

OAuth 登录流程是交互式的，会打开浏览器。Agent 不得 尝试执行此流程。向用户显示以下说明：

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}

需要两个 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 Server Core {#step-5-mcp-server-core}

MCP Server Core 是云端资源，每个账户只能创建一次。

检查（自动）

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 Core 已存在。继续执行步骤 6。
• 未通过（totalCount 为 0） → 不存在 MCP Core。请在下方创建。
• 未通过（权限错误） → 用户的 RAM 身份缺少所需权限。 请参阅下方的权限错误。

创建（Confirm-cloud — 执行前询问用户）

这将在用户的阿里云账户中创建一个云端 MCP Server Core 资源（地域：cn-hangzhou）。请向用户说明此操作，并等待用户明确批准。

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 已存在（仅允许创建一个）	视为成功——Core 已完成配置
权限被拒绝 / 禁止访问	缺少 RAM 权限	见下文

权限错误 {#permission-error}

如果用户在列出或创建 MCP Core 时收到权限错误，需要为其 RAM 身份附加以下系统策略：

AliyunOpenAPIMCPServerStaticCredentialAccess

请指示用户（或其账户管理员）：

1. 前往 RAM 控制台
2. 找到正在使用的 RAM 用户或角色
3. 附加系统策略 AliyunOpenAPIMCPServerStaticCredentialAccess
4. 重新运行检查 / 创建命令

---

第 6 步：Bearer Token 交换 {#step-6-bearer-token-exchange}

此步骤用于验证 MCP Server Core 能否成功交换 bearer token；MCP 服务需要该 token 才能在运行时对 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 来“检查”token 交换能力——这些 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}"

• 通过 → 返回有效的 token 响应。所有前提条件均已满足。
• 失败（权限错误） → 见Token 权限错误。
• 失败（其他错误） → 见未安装 OAuth 应用。

Token 权限错误 {#token-permission-error}

如果错误表明权限不足（例如 Forbidden、NoPermission、 User not authorized），用户需要以下系统策略：

AliyunOpenAPIMCPServerStaticCredentialAccess

这是第 5 步所需的同一策略。如果已附加，请通过重新检查 aliyun sts get-caller-identity，确认该策略适用于当前 RAM 身份。

未安装 OAuth 应用 {#oauth-app-not-installed}

如果错误并非权限错误（例如 InvalidClient、AppNotFound，或因其他原因导致 token 交换失败），用户可能尚未安装 API MCP Server 官方 OAuth 应用，或尚未授权当前用户。

请指示用户：

1. 打开 RAM 应用控制台
2. 找到并安装 API MCP Server 官方应用
3. 授权当前 RAM 用户/角色使用该应用
4. 重新运行 token 交换检查

AK 模式用户 {#ak-mode-users}

如果用户在第 3 步中通过 AK 模式（AccessKey）完成身份验证，令牌交换无需 API MCP Server OAuth 应用也可能成功——AK 凭据可以直接交换令牌。

• 如果在未安装 OAuth 应用的情况下，AK 模式下的令牌交换成功， 请告知用户：如果他们只使用 AK 模式，且希望缩小应用权限范围，可以选择在 RAM Applications Console 中移除默认 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（确认——执行前询问用户）

安装以下三个插件套件：

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

将官方工具包克隆到临时目录，验证选定的插件包，然后将每个完整目录安装到 ${QODERCN_CONFIG_DIR:-$HOME/.qwenworkcn}/plugins-custom/ 下。QwenWork 会扫描此 位置并注册插件的 Skills、钩子和 .mcp.json；不要将插件 Skills 拆分到全局 skills/ 目录，也不要将 MCP 配置拆分到全局 mcp.json。

向用户展示仓库来源、目标位置和三个插件名称，说明将安装三个本地 QwenWork 插件，并等待用户明确批准。获得批准后：

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. 更改已安装的插件之前，验证准备好的全部三个包：每个清单都必须能解析为 JSON， 且具有预期的 name；每个声明的钩子文件或 MCP 文件都必须存在；并且不得残留 字面量 __PLUGIN_ROOT__。
6. 如有需要，创建目标父目录。将所有现有插件移至 plugins-custom 之外的带时间戳 备份目录，例如 ${QODERCN_CONFIG_DIR:-$HOME/.qwenworkcn}/plugin-backups/<name>-<timestamp>； 切勿永久删除或覆盖现有插件。
7. 将每个完整插件目录复制到其最终目标位置，使用能保留隐藏文件的命令，例如在移走 旧目标位置后运行 cp -R <source> <destination>。
8. 对三个目标位置重复进行包验证。然后请用户重启 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

显示命令，并在执行前等待批准。

所选分支完成后，工具包插件即已安装并可供使用。

---

完成

全部七个步骤通过后，报告摘要：

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 已准备就绪。