云服务器 ECS：安装并配置 Workbench CLI 凭证

使用限制

• 目标实例操作系统：Workbench CLI 仅支持连接 Linux 实例（通过 SSH 协议），不支持连接 Windows 实例。

• 本机操作系统：Workbench CLI 本身支持在 Linux、macOS（amd64 / arm64）、Windows（amd64）上运行。

• 网络连通性：本机需能访问 *.aliyuncs.com 及 Workbench 后端 WebSocket 端点。

步骤一：安装 Workbench CLI

根据本机操作系统选择安装命令。安装脚本会自动检测架构（amd64 / arm64），从 OSS CDN 下载二进制并校验 SHA256，安装到系统默认路径。

curl -fsSL https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.sh | bash

irm https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.ps1 | iex

workbench version

步骤二：准备具有 Workbench CLI 最小权限的 AccessKey

Workbench CLI 通过 AccessKey 调用阿里云 API。本步骤的目标是获得一个只具备 Workbench CLI 所需最小权限的 AccessKey，以便在下一步配置到本机 CLI。推荐流程为：创建 RAM 用户 → 授予最小权限 → 为该 RAM 用户创建 AccessKey。

1. 创建 RAM 用户。登录 RAM 控制台，前往 身份管理 > 用户 页面，单击 创建用户。在创建页面填写 登录名称、显示名称，然后单击 确定。

   此时先不创建 AccessKey，AccessKey 在步骤 4 授权完成后统一创建。

2. 创建自定义权限策略。在 RAM 控制台 权限管理 > 权限策略 页面，单击 创建权限策略，切换到 脚本编辑 模式，贴入以下 JSON，然后单击 确定。

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ecs-workbench:*"
         ],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "ecs:DescribeInstances",
           "ecs:DescribeCloudAssistantStatus",
           "ecs:StartTerminalSession"
         ],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "ram:CreateServiceLinkedRole",
         "Resource": "*",
         "Condition": {
           "StringEquals": {
             "ram:ServiceName": "workbench.ecs.aliyuncs.com"
           }
         }
       }
     ]
   }

   策略中各 Action 的用途如下：

   Action	用途
   ecs:DescribeInstances	workbench list ecs 查询实例列表。
   ecs:DescribeCloudAssistantStatus	检查目标实例的云助手 Agent 状态。
   ecs:StartTerminalSession	建立与 ECS 实例的终端会话。
   ecs-workbench:LoginECSInstance	通过 Workbench 通道免密登录（connect、exec、upload、download 使用）。
   ecs-workbench:ChatMessages	会话内 AI Agent 助手（/agent 模式）所需权限。
   ecs-workbench:EndSessions	关闭 Workbench 会话（session close 与会话自动清理时调用）。
   ram:CreateServiceLinkedRole	首次使用时创建 Workbench 服务关联角色，通过 Condition 限定仅允许创建 workbench.ecs.aliyuncs.com 服务的关联角色。

   上述策略默认授予所有实例的访问权限。如需收敛到指定实例，仅对支持实例级授权的操作使用实例 ARN（注意两类操作的 ARN 格式不同），并将它们拆分到独立 Statement 中修改 Resource：

   // ecs-workbench:LoginECSInstance
   "Resource": "acs:ecs:<region>:<account-id>:ecs/<instance-id>"
   
   // ecs:DescribeInstances / DescribeCloudAssistantStatus / StartTerminalSession
   "Resource": "acs:ecs:<region>:<account-id>:instance/<instance-id>"

   说明

   ecs-workbench:ChatMessages 与 ram:CreateServiceLinkedRole 不支持按实例 ARN 收敛，需保持 "Resource": "*"。

3. 将策略授予 RAM 用户。进入步骤 1 创建的 RAM 用户详情页，切换到 权限管理 页签，单击 新增授权，选择上一步创建的自定义策略并完成授权。具体操作请参见 管理 RAM 用户的权限。

4. 为 RAM 用户创建 AccessKey。在 RAM 用户详情页的 凭证管理 > AccessKey 页签，单击 创建 AccessKey。在弹出的页面选择 在 CLI 中使用 AccessKey，勾选 我确认必须创建 AccessKey，然后单击 继续创建。具体操作请参见 创建 AccessKey。

   重要

   AccessKey Secret 仅在创建时显示一次，关闭页面后无法再次查看。请立即将 AccessKey ID 与 Secret 保存到密码管理器或密钥库；如遗失，只能重新创建。

   AccessKey 属于长期凭证，一旦泄露即被长期滥用。生产环境建议在步骤三配置完成后立即切换为 RamRoleArn 等自动刷新的凭证模式，具体请参见本文档的更多配置方式章节。

步骤三：在本机 CLI 中配置 AccessKey

执行以下命令，按提示依次输入步骤二获得的 AccessKey ID 与 AccessKey Secret。

workbench config

配置完成后，凭证保存在 ~/.workbench/config.json，文件权限自动设置为 0600（仅当前用户可读写）。文件内容示例：

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    }
  }
}

执行以下命令验证链路是否打通（将 cn-hangzhou 替换为您的实际地域）：

workbench list ecs -r cn-hangzhou

正常情况下返回该地域下的实例列表。如果返回 InvalidAccessKeyId、NoPermission 等错误，请参见本文档的常见问题章节。

（可选）设置界面语言

Workbench CLI 支持中文（zh）与英文（en）界面语言，默认中文。执行以下命令切换：

workbench config set language en   # 切换到英文
workbench config set language zh   # 切换回中文

也可在 workbench config 交互式配置流程中设置，或直接编辑 ~/.workbench/config.json，在对应 Profile 内添加 language 字段：

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "language": "en"
    }
  }
}

修改后重新连接即生效，无需重启守护进程。

（可选）管理多个 Profile

如果您需要在多个阿里云账号或多套凭证之间切换，可使用 Profile 功能，无需反复重新配置。所有 Profile 都保存在同一个 ~/.workbench/config.json 中，由 current 字段标记当前活跃的 Profile。

workbench config --profile prod          # 创建或编辑名为 prod 的 Profile
workbench config list                    # 查看所有 Profile（* 标记当前活跃）
workbench config get --profile prod      # 查看指定 Profile 详情
workbench config switch --profile prod   # 切换当前活跃 Profile
workbench config delete --profile old    # 删除 Profile（不能删除当前活跃的 Profile）
workbench exec -i i-xxx -c "hostname" --profile prod   # 本次命令临时使用指定 Profile

config.json 的多 Profile 结构示例：

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    },
    "prod": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456:role/prod",
      "role_session_name": "workbench"
    }
  }
}

更多配置方式

静态 AccessKey 属于长期凭证，一旦泄露即被长期滥用。生产环境或有更严格安全要求时，建议切换为以下四种模式之一：

workbench config --mode StsToken

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "StsToken",
      "access_key_id": "STS.LTAI...",
      "access_key_secret": "...",
      "sts_token": "..."
    }
  }
}

workbench config --mode RamRoleArn

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456789:role/WorkbenchRole",
      "role_session_name": "workbench-session"
    }
  }
}

workbench config --mode CredentialsCmd

// 静态 AccessKey
{
  "mode": "AK",
  "access_key_id": "<AccessKeyID>",
  "access_key_secret": "<AccessKeySecret>"
}

// STS 临时凭证
{
  "mode": "StsToken",
  "access_key_id": "<AccessKeyID>",
  "access_key_secret": "<AccessKeySecret>",
  "sts_token": "<SecurityToken>"
}

workbench config --mode CredentialsURI

{
  "Code": "Success",
  "AccessKeyId": "<AccessKeyID>",
  "AccessKeySecret": "<AccessKeySecret>",
  "SecurityToken": "<SecurityToken>",
  "Expiration": "2026-01-01T12:00:00Z"
}

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "CredentialsURI",
      "credentials_uri": "http://localhost:8080/credentials"
    }
  }
}

升级 Workbench CLI

Workbench CLI 支持一键自升级。执行以下命令即可升级到最新版本：

workbench upgrade

升级过程会自动下载并校验最新版本的二进制文件，并替换当前版本。

卸载

Workbench CLI 不会注册系统服务或修改系统配置，卸载只需停止守护进程、删除二进制并（可选）删除本机配置目录。

workbench daemon stop
sudo rm -f /usr/local/bin/workbench
rm -rf ~/.workbench

workbench daemon stop
Remove-Item "$env:ProgramFiles\workbench" -Recurse -Force

# 删除云助手场景安装时创建的 shim
Remove-Item "$env:SystemRoot\System32\workbench.cmd" -Force -ErrorAction SilentlyContinue

Remove-Item "$env:USERPROFILE\.workbench" -Recurse -Force

# 清理安装脚本（远程桌面场景）添加到用户 PATH 的 workbench 路径
$path = [Environment]::GetEnvironmentVariable("Path", "User")
if ($path -match "workbench") {
    $cleaned = ($path -split ";" | Where-Object { $_ -notmatch "workbench" }) -join ";"
    [Environment]::SetEnvironmentVariable("Path", $cleaned, "User")
}

常见问题

chmod 600 ~/.workbench/config.json

相关文档

• 通过 Workbench CLI 连接实例：父节点，包含工具定位、能力矩阵与快速开始。

• 使用 Workbench CLI 管理 ECS 实例：各命令详解与常见场景。

• 在 AI Agent 中使用 Workbench CLI 操作 ECS 实例：将 Workbench CLI 集成到 AI 编程工具。

• 管理 RAM 用户的权限

• 创建 AccessKey

• 什么是 STS

• 安装云助手 Agent