全部产品
Search

搜索本产品

    云服务器 ECS：在 AI Agent 中使用 Workbench CLI 操作 ECS 实例

    文档中心

    云服务器 ECS：在 AI Agent 中使用 Workbench CLI 操作 ECS 实例

    更新时间：Jul 28, 2026

    在悟空、Qoder、opencode 等 AI 编程工具中加载 Workbench CLI Skill，用自然语言驱动 Agent 完成 ECS 实例查询、命令执行与文件传输；借助结构化 JSON 输出与命令退出码透传，让 Agent 自主判断结果并链式调用后续操作。

    为什么 AI Agent 适合使用 Workbench CLI

    相比于其他 ECS 连接方式，Workbench CLI 在设计上天然适合 AI Agent 调用：

    • 结构化 JSON 输出：所有命令都支持 --output json，返回可预测的字段结构（例如 exec 返回 output、stderr、exit_code），Agent 无需正则解析文本输出。

    • 退出码透传：workbench exec 透传远程命令的退出码（与 SSH 一致），Agent 可据此判断远程命令是否成功；命令失败时 --output json 会输出结构化错误信息，便于 Agent 解析后决定重试或报错。

    • 无状态执行环境：workbench exec 每次调用都在独立环境中执行，无 shell 状态延续，Agent 无需维护会话上下文，也不会因遗留状态导致命令行为不可预期。

    • 命令语义直观：list / exec / upload / download 等命令的命名与常见运维动作一一对应，Agent 通过 --help 即可自主学习使用。

    前置准备

    • 已在本机安装 Workbench CLI 并完成凭证与最小 RAM 权限配置。具体操作，请参见 安装并配置 Workbench CLI 凭证。

    • 已在本机安装目标 AI 编程工具（悟空、opencode 或其他支持执行 shell 命令的 AI 工具）。

    • 建议先阅读 使用 Workbench CLI 管理 ECS 实例，熟悉各 workbench 子命令的用法，以便更好地判断 Agent 的输出。

    加载 Workbench CLI Skill 到 AI 工具

    阿里云官方已发布 Workbench CLI Skill，收录了所有子命令的用法、参数说明、退出码含义与典型工作流。将该 Skill 加载到 AI 编程工具后，Agent 即可在您用自然语言下达运维意图时自主调用 workbench 命令。以下按 Qoder、悟空、opencode 的顺序介绍加载方式。

    Qoder

    在 Qoder 所在的终端执行以下命令，通过 skills CLI 一键加载官方 Skill。

    npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-workbench-cli --agent qoder -y --full-depth

    加载完成后，在 Qoder 中可尝试以下对话验证：

    您：把本地 app.jar 部署到实例 i-bp1a2b3c4d5e6f 的 /opt/app 目录
Agent：（依次调用 workbench upload、workbench exec 完成部署，并逐步汇报结果）

    悟空

    悟空暂不支持 skills CLI 一键加载，需手动下载 Skill 包并导入：

    1. 访问 Workbench CLI Skill 页面，下载 Skill 的 ZIP 包。

    2. 在悟空中导入下载的 ZIP 包。

    3. 导入后启用（加载）该 Skill。

    加载完成后，在悟空中可尝试以下对话验证：

    您：用 workbench 查一下华东1运行中的实例
Agent：（自动执行 workbench list ecs -r cn-hangzhou --status Running --output json 并汇总结果）

    opencode

    在 opencode 所在的终端执行以下命令，通过 skills CLI 一键加载官方 Skill。

    npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-workbench-cli --agent opencode -y --full-depth

    加载完成后，在 opencode 中可尝试以下对话验证：

    您：连接到实例 i-bp1a2b3c4d5e6f 并查看磁盘使用情况
Agent：（自动执行 workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json 并解释结果）

    更多 AI 工具的加载方式，请访问 Workbench CLI Skill 页面。

    通用方法：让 Agent 从 --help 学习

    如果您使用的 AI 工具不支持阿里云官方 Skill，或希望快速验证，可以直接让 Agent 通过阅读 --help 输出自主学习。适用于任何能执行 shell 命令的 Agent。

    请阅读 workbench --help 的输出，学习使用 workbench 工具来管理和操作我的阿里云 ECS 实例。

    Agent 会自动执行 workbench --help、workbench <子命令> --help 逐层理解所有子命令的用法，然后通过 --output json 获取结构化结果进行后续处理。

    说明

    与显式加载 Skill 相比，通用方法在每次新会话中都需要重新读取 help 输出、占用较多上下文，且没有 Skill 中沉淀的最佳实践与错误处理建议。建议长期使用时优先采用显式 Skill 加载。

    典型对话场景

    场景一：查询运行中的实例

    用户 prompt：

    查一下华东1有哪些运行中的实例

    Agent 执行：

    workbench list ecs -r cn-hangzhou --status Running --output json

    简化返回：

    {
  "instances": [
    { "instance_id": "i-bp1a2b3c...", "instance_name": "web-prod-01", "status": "Running", "private_ip": "172.16.0.10" },
    { "instance_id": "i-bp2x4y5z...", "instance_name": "api-prod-02", "status": "Running", "private_ip": "172.16.0.11" }
  ]
}

    Agent 汇总：华东1（cn-hangzhou）当前有 2 台运行中的实例：web-prod-01（i-bp1a2b3c...）与 api-prod-02（i-bp2x4y5z...）。

    场景二：执行远程命令并分析结果

    用户 prompt：

    看看 i-bp1a2b3c4d5e6f 上磁盘空间够不够

    Agent 执行：

    workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json

    简化返回：

    {
  "output": "Filesystem      Size  Used Avail Use% Mounted on\n/dev/vda1        40G   36G  4.0G  90% /\n/dev/vdb1       100G   20G   80G  20% /data\n",
  "stderr": "",
  "exit_code": 0
}

    Agent 分析：根实例 / 分区已用 90%，剩余 4.0G，接近瓶颈，建议清理日志或扩容根盘；/data 分区使用率 20%，容量充足。

    场景三：传输文件

    用户 prompt：

    把 ./app-2.0.tar.gz 部署到 i-bp1a2b3c4d5e6f 的 /opt/deploy 目录，解压后验证

    Agent 执行（依次调用）：

    workbench upload ./app-2.0.tar.gz /opt/deploy/app-2.0.tar.gz -i i-bp1a2b3c4d5e6f
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/deploy && tar xzf app-2.0.tar.gz" --output json
workbench exec -i i-bp1a2b3c4d5e6f -c "ls -lh /opt/deploy/app-2.0/" --output json

    Agent 汇总：文件上传成功；解压完成，退出码 0；目录内包含 bin/、config/、app.jar（120M），部署完成。

    权限与安全建议

    • 为 AI Agent 使用独立的 RAM 用户或角色：与人工使用的凭证分离，便于在审计日志中区分"人工操作"与"Agent 操作"，出问题时可快速定位。

    • 用最小策略并按 Resource 收敛：只授予 Agent 需要的 Action，并通过实例 ARN 将 Resource 收敛到指定实例，避免误操作扩散到其他实例。

    • 启用人机确认（HITL）：workbench connect 内建 Agent 模式默认在执行任何命令前要求 Y/n 确认；外部 AI 工具建议同样启用命令执行前的用户确认。

    • 生产环境优先 RamRoleArn：Agent 场景往往长期运行、频繁使用凭证，静态 AK 一旦泄露风险高。优先使用 RamRoleArn 或 CredentialsURI 让凭证自动刷新。

    常见问题

    Agent 加载 Skill 后仍报 command not found 如何排查

    原因：AI 工具执行子进程时使用的 shell 环境未继承用户 shell 的 PATH，找不到 workbench 二进制。

    解决方案：

    • 使用绝对路径 /usr/local/bin/workbench（Linux/macOS）或 C:\Program Files\workbench\workbench.exe（Windows）。

    • 在 Skill 定义或 system prompt 中显式声明二进制路径。

    • 检查 AI 工具的启动方式，是否继承了用户的 shell profile（~/.bashrc、~/.zshrc）。

    Agent 循环重试导致大量会话如何限制

    原因：Agent 遇到错误反复重试，每次都新建会话，累计占用服务端资源。

    解决方案：

    • 在 Skill 或 prompt 中约束 Agent：遇到认证失败、实例不存在等不可重试的错误时（依据 --output json 的 message 字段判断）立即向用户报错，不自动重试。

    • 会话在空闲约 30 分钟后自动回收；无需长期保持时，让 Agent 用完即以 /exit 关闭会话。

    • 定期执行 workbench session close --all 或 workbench daemon stop 清理残留会话。

    如何强制 Agent 只使用 --output json

    原因：Agent 默认可能使用文本输出，导致解析不稳定。

    解决方案：在 Skill 定义或 system prompt 中明确要求 Agent 在所有 workbench 命令调用中附加 --output json，并按 JSON schema 解析结果——成功时字段为 output、stderr、exit_code，失败时输出 {code, message}。

    相关文档