通过Agent Skill对接RDS AI助手-云数据库 RDS(RDS)-阿里云帮助中心

背景信息

云数据库RDS AI助手是阿里云提供的一款智能化数据库服务，能够帮助用户完成SQL优化、实例诊断、性能分析、故障排查、数据查询等多种数据库管理任务。

alibabacloud-rds-copilot是RDS AI助手的官方Agent Skill。Agent Skill是AI客户端加载的能力扩展包，声明触发词后，Agent会自动识别用户意图并调用对应的工具能力。安装本Skill后，即可在支持的Agent客户端对话中通过自然语言驱动RDS AI助手。

当前alibabacloud-rds-copilot支持以下Agent客户端：

Claude Code
Qoder
Cursor
Codex
Gemini CLI
Qwen Code
GitHub Copilot
OpenClaw

工作原理：用户在Agent对话中通过自然语言提出需求，Agent识别到RDS Copilot触发词后，调用aliyun rdsai chat-messages命令请求RDS AI助手OpenAPI，并将返回结果以自然语言呈现给用户。

前提条件

已开通云数据库RDS AI助手专业版。
已创建RAM用户，并授予该用户rdsai:ChatMessages权限。具体操作，请参见查看RAM用户的AccessKey信息。
已为该RAM用户创建并获取AccessKey ID和AccessKey Secret。为安全起见，建议使用RAM用户的AccessKey。
本地环境已安装Node.js（版本≥18），用于通过npx命令安装Skill。若未安装，请前往Node.js官方网站下载并安装。
已安装并可正常运行至少一个支持的Agent客户端（如Claude Code、Qoder、Cursor等，详见背景信息章节）。

说明

阿里云CLI（版本≥3.3.3）与rdsai插件由Agent在首次调用Skill时自动安装，通常无需手动准备。若自动安装失败，可参考步骤二手动安装。

操作步骤

步骤一：安装alibabacloud-rds-copilot Skill

请从以下3种安装方式中任选其一。安装完成后，请重启Agent客户端以加载Skill。

方式一：通过Skills CLI一键安装（推荐）

Skills CLI是通用安装工具，支持主流Agent客户端。请根据Agent客户端和安装范围，选择下方对应标签页中的命令执行。

安装范围：当前项目仅当前项目可用，团队可共享；全局安装所有项目均可使用。

当前项目安装

Claude Code

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent claude-code -y --full-depth

Qoder

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent qoder -y --full-depth

Cursor

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent cursor -y --full-depth

Codex

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent codex -y --full-depth

Gemini CLI

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent gemini-cli -y --full-depth

Qwen Code

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent qwen-code -y --full-depth

GitHub Copilot

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent github-copilot -y --full-depth

OpenClaw

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent openclaw -y --full-depth

全局安装

Claude Code

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent claude-code -g -y --full-depth

Qoder

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent qoder -g -y --full-depth

Cursor

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent cursor -g -y --full-depth

Codex

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent codex -g -y --full-depth

Gemini CLI

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent gemini-cli -g -y --full-depth

Qwen Code

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent qwen-code -g -y --full-depth

GitHub Copilot

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent github-copilot -g -y --full-depth

OpenClaw

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-rds-copilot --agent openclaw -g -y --full-depth

方式二：通过ClawHub CLI安装（OpenClaw生态专属）

若使用OpenClaw生态工具，可执行以下命令安装：

npx clawhub install alibabacloud-rds-copilot

方式三：下载ZIP包手动安装

若您的环境无法访问外网或无法使用npx命令，可通过下载Skill文件手动放置到Agent目录。

访问alibabacloud-rds-copilot skill官网，依次点击【安装引导】>【下载安装】>【下载 ZIP 包】。
将下载的ZIP文件解压到任意目录，得到alibabacloud-rds-copilot文件夹。

根据您使用的Agent客户端，将该文件夹复制到对应的Skill目录：

Agent客户端	Skill 目录
Claude Code	`~/.claude/skills/`
Qoder	`~/.qoder/skills/`
Cursor	`~/.cursor/skills/`
Codex	`~/.codex/skills/`
Gemini CLI	`~/.gemini/skills/`
Qwen Code	`~/.qwen-code/skills/`
GitHub Copilot	`~/.github-copilot/skills/`
OpenClaw	`./skills/`（项目当前目录）

示例（以Claude Code为例）：

macOS或Linux

mkdir -p ~/.claude/skills/
cp -r alibabacloud-rds-copilot ~/.claude/skills/

Windows(PowerShell)

New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\skills\" -Force
Copy-Item -Recurse "alibabacloud-rds-copilot" "$env:USERPROFILE\.claude\skills\"

步骤二：配置阿里云CLI与访问凭证

访问凭证是调用RDS AI助手的必要条件。阿里云CLI和rdsai插件可在Agent首次调用Skill时自动安装，但访问凭证必须手动配置。请在验证Skill前完成本步骤，否则调用会失败。

2.1 安装或升级阿里云CLI（版本≥3.3.3）

macOS（推荐使用Homebrew）
```
brew install aliyun-cli
```

Linux（或macOS一键脚本）

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

Windows：下载并安装安装/更新 CLI。

安装完成后，执行以下命令验证：

aliyun version

2.2 启用插件自动安装并安装rdsai插件

aliyun configure set --auto-plugin-install true
aliyun plugin install --names rdsai

安装完成后，执行以下命令验证：

aliyun rdsai --help

2.3 配置访问凭证

执行以下命令，通过交互式方式配置阿里云AccessKey凭证。此步骤必须手动完成。

aliyun configure --mode AK --profile rdsai

根据提示依次输入：

Access Key Id：您的AccessKey ID。
Access Key Secret：您的AccessKey Secret。
Default Region Id：默认地域，推荐cn-hangzhou。若您的RDS实例在其他地域，请填写对应的地域ID（如cn-beijing）。

配置完成后，执行以下命令查看已配置的凭证信息：

aliyun configure list

重要

安全提示：请使用aliyun configure命令配置凭证，凭证信息会存储在阿里云CLI的凭证库中，避免在环境变量或命令行历史中泄露。请勿将AccessKey Secret直接暴露在日志或聊天记录中。

步骤三：验证Skill已加载

重启Agent客户端后，在对话框中输入以下触发词，验证Skill是否成功加载：

用 RDS Copilot 查一下杭州有多少个 RDS 实例

如果Agent能识别请求并尝试调用aliyun rdsai chat-messages 命令，则表示Skill已成功加载。

结果验证

完成上述步骤后，可在Agent对话中通过自然语言测试RDS AI助手是否可正常调用。以下以Claude Code为例：

在终端中启动Claude Code。
```
claude
```
在对话框中输入测试指令，例如查询您在华东1（杭州）地域的RDS实例列表：
```
/alibabacloud-rds-copilot 我在杭州有多少实例？
```

查看返回结果。如果配置成功，您将看到类似如下的输出：

[查询] 查询杭州地域的 RDS 实例列表
[地域] cn-hangzhou | [语言] zh-CN
============================================================
[RDS Copilot 回答]
<RDS Copilot 的实际回答内容>
[会话ID] conv-xxxx-xxxx-xxxx

看到[RDS Copilot 回答]部分包含您的真实实例信息，即表示集成成功。

Claude Code v2.1.15
qwen3-max · API Usage Billing
~/code/claude-code-test
/model to try Opus 4.5
/alibabacloud-rds-copilot 杭州有多少实例
● 我将使用阿里云 RDS Copilot 来查询杭州地域的实例数量。首先，我会检查依赖是否已安装，然后调用脚本执行查询。
● Bash(cd /Users/cnwenf/.claude/skills/alibabacloud-rds-copilot && python3 scripts/call_rds_ai.py
    "杭州有多少实例" --region cn-hangzhou)
  └ 查询杭州地域的RDS实例总数
    杭州地域共有7个RDS实例。
  +4 lines (ctrl+o to expand)
  └ Shell cwd was reset to /Users/cnwenf/code/claude-code-test
● 根据阿里云 RDS Copilot 的查询结果，杭州地域（cn-hangzhou）共有 7个 RDS 实例。
● 如果您需要了解更多关于这些实例的详细信息（如实例类型、规格、状态等），或者需要对这些实例进行其他操作（如
性能分析、参数优化等），请告诉我，我可以帮您进一步查询。
❯

如何使用

安装并验证成功后，您可以在Agent对话中通过自然语言向RDS AI助手提问，以执行数据库管理任务。

示例1：查询实例信息

您：查询杭州地域有哪些 MySQL 实例？
Agent：[调用 RDS Copilot 并返回结果]

示例2：进行SQL优化

您：针对实例 rm-bp1xxxxxxxxxxxx，帮我分析和优化这条 SQL:SELECT * FROM users WHERE status=1 ORDER BY created_at
Agent：[调用 RDS Copilot 获取 SQL 优化建议]

示例3：故障排查

您：RDS 实例 rm-bp1xxxxxxxxxxxx 连接报 Too many connections 错误，帮我排查。实例在杭州地域。
Agent：[调用 RDS Copilot 分析问题并给出排查建议]

常见问题

1. 提示"No valid order found"

问题现象：调用RDS Copilot时，返回结果中包含No valid order found错误。
问题原因：当前阿里云账号未开通RDS AI助手专业版。
解决方案：前往RDS AI助手专业版开通页面完成开通，然后重试。

2. 提示"未找到阿里云访问凭证"或凭证无效

问题现象：执行时提示凭证未找到，或出现InvalidAccessKeyId、SignatureDoesNotMatch等错误。
解决方案：
1. 执行aliyun configure list检查是否已配置凭证以及凭证是否有效。
2. 若未配置或已失效，请参考步骤二的2.3小节重新执行aliyun configure --mode AK --profile rdsai配置凭证。
3. 确认RAM用户已授予rdsai:ChatMessages权限，且AccessKey状态为启用。

3. Agent未识别或加载Skill

问题现象：在Agent对话中无法触发或使用alibabacloud-rds-copilot Skill。
解决方案：请按以下步骤排查。
1. 检查目录结构：确认alibabacloud-rds-copilot文件夹已完整复制到您所用Agent客户端的Skill目录下（参见步骤一方式三的目录对照表）。
2. 检查核心文件：确保Skill目录下存在SKILL.md文件，这是Agent识别Skill的入口文件。
3. 重启客户端：完全退出并重新启动Agent客户端，使其重新扫描Skill目录。
4. 使用触发词：在对话中显式提及RDS Copilot、RDS AI助手等关键词，帮助Agent识别调用意图。

4. 提示"aliyun: command not found"或CLI版本过低

问题现象：调用Skill时提示aliyun: command not found，或提示plugin不是有效命令。
问题原因：未安装阿里云CLI，或CLI版本低于3.3.3（旧版本不支持plugin子命令）。
解决方案：参考步骤二的2.1小节安装或升级阿里云CLI至3.3.3及以上版本。请勿在旧版本CLI上重复运行aliyun plugin命令，应先升级CLI。

5. 通过npx安装Skill失败

问题现象：执行npx skills add ...或npx clawhub install ...时报错，如命令找不到、网络超时、模块下载失败等。
解决方案：
1. 检查Node.js版本是否≥18：执行node -v确认。
2. 检查网络是否可访问npm仓库，如有代理请正确配置HTTP_PROXY/HTTPS_PROXY。
3. 若网络受限，可改用方式三：下载ZIP包手动安装。