Elastic Compute Service:Workbench CLI のインストールと認証情報の設定

制限事項

• 接続先インスタンスのオペレーティングシステム：Workbench CLI は、Linux インスタンスへの接続 (SSH プロトコル経由) のみをサポートしています。Windows インスタンスへの接続はサポートしていません。

• ローカルマシンのオペレーティングシステム：Workbench CLI 自体は、Linux、macOS (amd64 / arm64)、および Windows (amd64) で実行できます。

• ネットワーク接続：ローカルマシンは *.aliyuncs.com および Workbench バックエンドの WebSocket エンドポイントにアクセスできる必要があります。

ステップ 1: 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

ステップ 2: Workbench CLI 用の最小権限を持つ AccessKey の準備

Workbench CLI は、AccessKey を使用して Alibaba Cloud API を呼び出します。このステップの目標は、Workbench CLI が必要とする最小権限のみを持つ AccessKey を取得し、次のステップでローカル CLI に設定できるようにすることです。推奨されるプロセスは次のとおりです：RAM ユーザーの作成 → 最小権限の付与 → RAM ユーザー用の AccessKey の作成。

1. RAM ユーザーの作成。RAM コンソールにログインし、[ID] > [ユーザー] ページに移動し、 [ユーザーの作成] をクリックします。作成ページで、 [ログイン名] と [表示名] を入力し、 [OK] をクリックします。

   この時点では AccessKey を作成しないでください。AccessKey は、権限を付与した後、ステップ 4 で作成します。

2. カスタム権限ポリシーの作成。RAM コンソールの [権限] > [ポリシー] ページで、 [ポリシーの作成] をクリックし、 [JSON] タブに切り替え、次の JSON を貼り付けて、 [OK] をクリックします。

   {
     "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	接続先インスタンスのクラウドアシスタントエージェントのステータスを確認します。
   ecs:StartTerminalSession	Elastic Compute Service (ECS) インスタンスとのターミナルセッションを確立します。
   ecs-workbench:LoginECSInstance	Workbench チャネル経由でのパスワードレスログインを有効にします (connect、exec、upload、download で使用)。
   ecs-workbench:ChatMessages	セッション内の AI エージェントアシスタント (/agent モード) に必要な権限。
   ecs-workbench:EndSessions	Workbench セッションを閉じます (session close および自動セッションクリーンアップで呼び出されます)。
   ram:CreateServiceLinkedRole	初回使用時に Workbench サービスリンクロールを作成します。Condition は、作成を workbench.ecs.aliyuncs.com サービスのサービスリンクロールのみに制限します。

   デフォルトでは、ポリシーはすべてのインスタンスへのアクセスを許可します。特定のインスタンスに絞り込むには、インスタンスレベルでの認可をサポートするアクションにのみインスタンス ARN を適用します。それらを別々の Statement ブロックに分割し、 Resource を変更します。

   "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 を作成するしかありません。

   AccessKey は長期的な認証情報です。一度漏洩すると、長期間にわたって悪用される可能性があります。本番環境では、ステップ 3 での設定完了後、すぐに RamRoleArn などの自動更新される認証情報モードに切り替えることを推奨します。詳細については、本ドキュメントの「その他の設定方法」セクションをご参照ください。

ステップ 3: ローカル CLI での AccessKey の設定

次のコマンドを実行し、プロンプトに従ってステップ 2 で取得した 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 を直接編集して対応するプロファイルに language フィールドを追加することもできます。

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

変更は次回の接続時に有効になります。デーモンを再起動する必要はありません。

(オプション) 複数プロファイルの管理

複数の Alibaba Cloud アカウントや複数の認証情報セットを切り替える必要がある場合は、プロファイル機能を使用して、再設定を繰り返す手間を省くことができます。すべてのプロファイルは同じ ~/.workbench/config.json ファイルに保存され、 current フィールドがアクティブなプロファイルを示します。

workbench config --profile prod          # prod という名前のプロファイルを作成または編集
workbench config list                    # すべてのプロファイルを一覧表示 (* はアクティブなプロファイルを示す)
workbench config get --profile prod      # 特定のプロファイルの詳細を表示
workbench config switch --profile prod   # アクティブなプロファイルを切り替え
workbench config delete --profile old    # プロファイルを削除 (アクティブなプロファイルは削除不可)
workbench exec -i i-xxx -c "hostname" --profile prod   # このコマンドのみ特定のプロファイルを使用

config.json 内の複数プロファイル構造の例を次に示します。

{
  "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 は長期的な認証情報であり、一度漏洩すると長期間にわたって悪用される可能性があります。本番環境や、より厳しいセキュリティ要件がある場合は、以下の 4 つのモードのいずれかに切り替えることを推奨します。

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

# クラウドアシスタントベースのインストール中に作成されたシムを削除
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 エージェントで Workbench CLI を使用した ECS インスタンスの操作：Workbench CLI を AI プログラミングツールに統合します。

• RAM ユーザーへの権限付与

• AccessKey ペアの作成

• STS とは

• クラウドアシスタントエージェントのインストール