环境代理

适用条件

• 已提交工单，为当前阿里云账号开通环境代理。

• 自 2026 年 10 月起，需订阅高级版或旗舰版。

• 已在华北2（北京）或新加坡地域创建数字员工。

• 目标机器为 Linux（x86_64、ARM64 或 32 位 x86）或 macOS（Apple 芯片），且已安装 curl。

• 使用普通用户执行安装命令，无需 sudo。数字员工在该机器上执行任务时，默认使用该用户的身份和权限，建议使用权限合适的专用账号。

• 目标机器可以直接或通过 HTTP 代理访问数字员工所在地域的以下地址（端口 443）：机器可以访问公网时，使用公网地址；机器位于同地域的阿里云 VPC 内时，可以使用 VPC 地址，无需访问公网。

  地域	地域 ID	网络类型	下载地址	环境代理接入地址
  华北2（北京）	cn-beijing	公网	satellite-cli-cn-beijing.oss-cn-beijing.aliyuncs.com	cn-beijing.satellite.starops.aliyuncs.com
  华北2（北京）	cn-beijing	VPC	satellite-cli-cn-beijing.oss-cn-beijing-internal.aliyuncs.com	cn-beijing-internal.satellite.starops.aliyuncs.com
  新加坡	ap-southeast-1	公网	satellite-cli-ap-southeast-1.oss-ap-southeast-1.aliyuncs.com	ap-southeast-1.satellite.starops.aliyuncs.com
  新加坡	ap-southeast-1	VPC	satellite-cli-ap-southeast-1.oss-ap-southeast-1-internal.aliyuncs.com	ap-southeast-1-internal.satellite.starops.aliyuncs.com

操作步骤

f=$(mktemp) && trap 'rm -f "$f"' EXIT HUP INT TERM && curl -fsSL 'https://satellite-cli-<地域ID>.oss-<地域ID>.aliyuncs.com/satellited/latest/install.sh' -o "$f" && printf %s '<Bind Token>' | sh "$f" install --region '<地域ID>' --gateway '<地域ID>.satellite.starops.aliyuncs.com:443' --expect-account '<阿里云主账号ID>' --token-file - --enable-bash --bash-mode hil

f=$(mktemp) && trap 'rm -f "$f"' EXIT HUP INT TERM && curl -fsSL 'https://satellite-cli-<地域ID>.oss-<地域ID>-internal.aliyuncs.com/satellited/latest/install.sh' -o "$f" && printf %s '<Bind Token>' | sh "$f" install --region '<地域ID>' --network vpc --expect-account '<阿里云主账号ID>' --token-file - --enable-bash --bash-mode hil

export NO_PROXY="${NO_PROXY:+$NO_PROXY,}<地域ID>-internal.satellite.starops.aliyuncs.com"

export HTTPS_PROXY=http://<代理地址>:<端口>

6. 验证

建议按照以下步骤验证环境代理是否接入成功：

1. 在 环境代理 列表中，该环境代理的 机器（在线 / 绑定） 为 1 / 1，连接状态 为 在线。

2. 点击环境代理名称，在 机器 页签核对主机名、IP 和平台，在 能力 页签核对机器已上报的能力。

3. 在机器上执行 satellited status，查看绑定信息和服务运行状态。

声明能力

为保证安全，数字员工只能执行机器上 capabilities.json 中声明的能力。安装时开启 bash 内置能力，会自动写入 bash 能力的声明。

• 文件位置：~/.satellited/capabilities.json。以 root 用户安装时，文件位置为 /etc/satellited/capabilities.json。

• 文件保存后约 15 秒内自动生效，无需重启服务。

• 删除该文件表示本机不声明任何能力。重新安装或升级不会覆盖已修改过的文件。

• 单个文件最多声明 64 个能力，每个能力最多 32 个参数。

  示例：

  {
    "capabilities": [
      {
        "id": "disk_cleanup",
        "type": "script",
        "exec": "/opt/ops/disk_cleanup.sh",
        "description": "清理指定目录下的过期临时文件",
        "execution_mode": "auto",
        "timeout_s": 300,
        "params": [
          { "name": "target_dir", "type": "string", "required": true, "help": "要清理的目录绝对路径" },
          { "name": "keep_days", "type": "number", "default": "7", "help": "保留最近 N 天的文件" },
          { "name": "dry_run", "type": "boolean", "default": "true", "help": "true 时仅列出将删除的文件" }
        ]
      },
      {
        "id": "restart_service",
        "type": "script",
        "exec": "/opt/ops/restart_service.sh",
        "description": "重启指定服务（高危操作，执行前人工确认）",
        "execution_mode": "hil",
        "params": [
          { "name": "service", "type": "enum", "required": true, "enum": ["nginx", "mysqld", "redis"], "help": "要重启的服务名" }
        ]
      },
      {
        "id": "bash",
        "type": "bash",
        "execution_mode": "hil",
        "timeout_s": 3600
      }
    ]
  }

  字段	说明
  id	能力 ID，同一文件中不能重复。以小写字母开头，只能包含小写字母、数字、下划线（_）、短横线（-）和点（.），最多 64 个字符。bash 内置能力固定为 bash。
  type	能力类型。script 表示执行指定脚本，bash 表示执行 shell 命令。
  exec	脚本的绝对路径。仅 script 类型需要填写。
  description	能力说明。数字员工根据该说明判断何时使用该能力。
  execution_mode	执行方式。auto 表示直接执行，hil 表示执行前需人工确认。script 类型默认为 auto，bash 类型默认为 hil。
  timeout_s	执行超时时间，单位为秒。
  run_as	以指定用户执行脚本。仅当 satellited 以 root 用户运行时，才能指定其他用户。
  params	参数列表，仅 script 类型可以填写。每个参数包含 name、type（string、number、boolean 或 enum）、required、default、enum（type 为 enum 时必填）和 help。

script 类型的参数按声明校验后，通过环境变量 SATELLITE_PARAM_<参数名大写> 传给脚本。例如，参数 target_dir 对应环境变量 SATELLITE_PARAM_TARGET_DIR。参数名以小写字母开头，只能包含小写字母、数字和下划线，最多 32 个字符。

对话中使用

在对话输入框中输入 @，选择 环境代理 和目标环境代理，然后描述要执行的操作。数字员工会在该环境代理绑定的机器上执行对应的能力。

执行需人工确认的能力时，对话中会显示 在您的机器上执行能力 卡片，展示能力、目标机器和执行参数。你确认后，任务才会执行。

只有已创建环境代理的数字员工，才会在对话中加载环境代理技能，从而了解你有哪些环境代理，并在绑定的机器上执行能力。未创建环境代理的数字员工不会加载该技能，原有对话不受影响。

是否已创建的状态约每 1 分钟刷新一次：新建或删除环境代理后，最长约 1 分钟在对话中生效。

管理环境代理

satellited status     # 查看绑定信息和服务状态
satellited start      # 启动服务
satellited stop       # 停止服务
satellited restart    # 重启服务

curl -fsSL 'https://satellite-cli-<地域ID>.oss-<地域ID>.aliyuncs.com/satellited/latest/install.sh' -o install.sh
sh install.sh upgrade --region '<地域ID>'    # 升级到最新版本
sh install.sh uninstall                      # 卸载，保留配置和数据
sh install.sh uninstall --purge              # 卸载，并删除配置和数据

curl -fsSL 'https://satellite-cli-<地域ID>.oss-<地域ID>-internal.aliyuncs.com/satellited/latest/install.sh' -o install.sh
sh install.sh upgrade --region '<地域ID>' --network vpc

常见问题

和STAROps对话时他不知道环境代理（satellite）是什么

只有已创建环境代理的数字员工，才会在对话中加载环境代理技能。请确认当前对话使用的数字员工已经创建了环境代理：环境代理按数字员工隔离，在其他数字员工下创建的环境代理，当前数字员工无法使用。

是否已创建的状态约每 1 分钟刷新一次。刚创建环境代理时，请等待约 1 分钟后重新发送消息；仍未生效时，可新建对话重试。环境代理已创建但尚未接入机器时，数字员工可以查询到该环境代理，但无法执行能力，请先按操作步骤完成机器接入。

在连接器中找不到环境代理

环境代理目前受限使用，请确认已通过工单开通，且数字员工位于华北2（北京）或新加坡地域。自 2026 年 10 月起，还需订阅高级版或旗舰版。

页面一直显示“正在等待机器上线…”

请检查命令输出是否有报错，并确认机器可以访问 适用条件 中的两个地址。然后在机器上执行 satellited status，查看服务状态。

VPC 内的机器执行控制台命令时下载失败

控制台复制的命令需要访问公网。请按 通过 VPC 接入 中的命令，使用 VPC 地址下载和接入。

机器通过代理访问公网，但一直未上线

执行 satellited status 查看是否已记录代理。未记录时，请按 通过代理访问公网 设置代理后重新执行安装命令。安装命令提示不支持 https:// 代理时，请改用 http:// 代理地址。

提示找不到 satellited 命令

satellited 安装在 ~/.local/bin 目录。请将该目录加入 PATH，或使用完整路径 ~/.local/bin/satellited。

机器状态为“尚未上线”

机器已绑定，但 satellited 尚未连接成功。请检查服务是否正在运行，以及机器能否访问环境代理接入地址。

机器状态为“已停止”

satellited 服务已停止。请在机器上执行 satellited start。

机器状态为“离线（长时间无活动）”

机器长时间没有活动，可能是机器关机、网络中断或服务异常退出。请检查机器和网络，必要时执行 satellited restart。

连接状态为“状态暂不可用”

连接状态暂时未能更新，系统会自动重试。此时显示的结果不代表机器的当前状态，请稍后刷新页面。

提示“该机器尚未声明任何能力”

机器已上线，但数字员工暂时无法在该机器上执行任务。请编辑 capabilities.json 声明能力，或重新执行开启了 bash 内置能力的安装命令。

修改 capabilities.json 后能力没有变化

请检查 JSON 格式和字段是否正确。文件内容有误时，satellited 会继续使用上一次有效的声明。

重新执行安装命令后仍没有 bash 能力

如果你修改过 capabilities.json，安装命令不会改动该文件。请在文件的 capabilities 数组中手动添加 { "id": "bash", "type": "bash" }。

执行命令时提示环境代理已绑定机器

每个环境代理只能绑定一台机器。请先解绑原机器，或创建新的环境代理。

一台机器能否接入多个环境代理

可以。在该机器上执行其他环境代理的安装命令即可，已安装的 satellited 会直接完成绑定。一台机器上的 satellited 只能属于一个阿里云账号。

机器重启后环境代理离线

在容器等无法使用 systemd 用户服务的环境中，satellited 以后台进程运行，机器重启后不会自动启动。请执行 satellited start 或重新执行安装命令。

创建时提示数量已达上限

每个数字员工最多可以创建 20 个环境代理。请删除不再使用的环境代理后重试。