在安全管理模块开通 AgentSentry 服务后，新建的 ArkClaw 企业版实例会自动接入安全防护。如果你希望为存量 ArkClaw 企业版实例开启安全防护，或将 ArkClaw 实例安装的 AgentSentry 版本升级至最新，可以参考本文档操作。该操作适用于以下场景下的 ArkClaw 企业版实例： * 开通 AgentSentry 服务之前创建的 ArkClaw 企业版实例，即从未安装过防护插件。 * 开通 AgentSentry 服务之后创建的 ArkClaw 企业版实例，但希望升级到最新防护版本。 * 开通 AgentSentry 服务之后创建的 ArkClaw 企业版实例，手动卸载了插件，需要重新安装。 ## 注意事项 * 当前火山引擎 AgentSentry 最新插件版本为 **1.9.1**。 * 版本兼容性：兼容火山引擎 ArkClaw 1.2.0 或更新版本。如果为历史版本，需要先前往**批量运维 \> 版本管理**模块，执行 ArkClaw 实例升级。 ## 前提条件 * 管理员已在 ArkClaw 企业版控制台开通 AgentSentry 服务。详情请参考[开通安全防护](https://www.volcengine.com/docs/87732/2277773?lang=zh#2YZL9YZz)。 * 员工已创建 ArkClaw 实例。 * 执行升级操作的账号需具备以下权限 * **ArkClawFullAccess**：用于获取 ArkClaw 企业版读写权限 * **ClawSentryFullAccess**：用于获取 AgentSentry 读写权限 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_abeda783f71c25e02974a27ff12d9cc1.png) ## 操作步骤 1. 登录 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)。 2. 在左菜单栏，选择**运维管理 \> 批量运维**，单击**创建作业**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_23e9d4aa005ef6eee61a6c579a8213f2.png) 3. 配置作业相关信息。 1. 填写作业名称。 2. 将修改后的[代码示例](https://www.volcengine.com/docs/87732/2372697?lang=zh#tluZ17qW)粘贴到系统预设命令下方 **（自第 10 行开始），注意保留原有命令**。

注意

系统预设 Shell 内容无法修改，请从第 10 行开始输入。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9d6c0555023d76669dd92e08a2e573da.png) 3. 单击**添加**选择执行对象。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_43d6642281738ab332a424755a1b0e9e.png) 4. 选择目标执行对象，然后单击确定。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_659e260d1debbcadd0632b303ac840c5.png) 创建完成后，可以在作业列表中看到新创建的作业。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2c1cc6ff1d7f29981467cd0875ed16cb.png) 5. 待状态变为执行成功后，前往安全管理列表，查看升级的 Claw 实例版本。

说明

版本号为 1.9.1 则表示已经升级为最新。

## 代码示例以下代码用于批量运维作业中执行相关命令，请复制后替换对应参数值使用，参数获取方式请参考下文参数说明。

注意

注意替换代码中的参数值（6 至 12 行）。

### 代码详情 ```Bash # ======================================== # 请在此处填写配置（必填参数请填写！） # ======================================== # 火山引擎认证信息 VOLC_ACCESS_KEY_ID="your AK" # 必填：火山引擎 Access Key VOLC_SECRET_KEY="your SK" # 必填：火山引擎 Secret Key # Claw 配置 SPACE_ID="详见使用方式" # ArkClaw 空间 ID REGION="cn-beijing" # 区域，cn-beijing/cn-hongkong CONFIG_FILE="/root/.openclaw/openclaw.json" # OpenClaw 配置文件路径 TARGET_VERSION="1.9.1" # 目标版本 # 选填：需要修改单个助手在安全管理模块显示的名称和所属用户信息时，可以设置。批量升级多个 ArkClaw 助手时请勿配置，否则会覆盖多个助手的信息。 NAME="" # 选填：自定义设置 ArkClaw 助手名称 USER_UID="" # 选填：自定义设置所属用户的唯一标识符，即用户邮箱 #选填：使用临时密钥时需要配置 TOKEN="" # 选填：使用临时密钥时需要设置 # ======================================== # 从环境变量 OTEL_SERVICE_NAME 读取 ENV_FILE="/root/.openclaw/.env" if [[ -f "${ENV_FILE}" ]]; then set -a source "${ENV_FILE}" set +a fi ARK_CLAW_ID="${CLAW_INSTANCE_ID:OTEL_SERVICE_NAME}" # 调试信息 echo " ARK_CLAW_ID = '${ARK_CLAW_ID}'" echo "" # ======================================== set -euo pipefail export HOME="${HOME:-/root}" SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # Plugin names PLUGIN_NAME="agent-sentry" LEGACY_PLUGIN_NAME="claw-sentry" OLD_PLUGIN_NAME="ai-assistant-security-openclaw" EXTENSIONS_DIR="${HOME}/.openclaw/extensions" # TOS download settings「默认 cn-beijing」 CS_TOS_BASE_URL="https://claw-sentry.tos-cn-beijing.volces.com" CS_TEMP_DIR="/tmp/agent-sentry" # Go binary download settings「默认 cn-beijing」 GO_BINARY_URL="https://clawsentry-arkclaw-update.tos-cn-beijing.volces.com/clawsentry${TARGET_VERSION}/initgo_arkclaw_online" GO_BINARY_PATH="/tmp/initgo_arkclaw_online" # 根据 region 设置不同的下载地址 if [[ "$REGION" == "cn-hongkong" ]]; then echo "Using cn-hongkong region download addresses" CS_TOS_BASE_URL="https://claw-sentry-hongkong.tos-cn-hongkong.volces.com" GO_BINARY_URL="https://clawsentry-arkclaw-update-hongkong.tos-cn-hongkong.volces.com/clawsentry${TARGET_VERSION}/initgo_arkclaw_online" else echo "Using cn-beijing region download addresses" fi echo "=======================================" echo "agent-sentry configure (with Go binary)" echo "=======================================" echo "" echo "[1/5] Checking dependencies..." if ! command -v wget &>/dev/null; then echo "Error: wget not found" echo "Please install wget first" exit 1 fi echo "" echo "[2/5] Checking and removing old plugins..." # Remove old plugin (ai-assistant-security-openclaw) OLD_PLUGIN_DIR="${EXTENSIONS_DIR}/${OLD_PLUGIN_NAME}" if [[ -d "$OLD_PLUGIN_DIR" ]]; then echo "Old plugin found: $OLD_PLUGIN_NAME, uninstalling..." if command -v openclaw &>/dev/null; then echo "y" | openclaw plugins uninstall "$OLD_PLUGIN_NAME" 2>/dev/null || true else echo "openclaw command not found, skipping uninstall" fi # Double-check and force delete if directory still exists if [[ -d "$OLD_PLUGIN_DIR" ]]; then echo "Directory $OLD_PLUGIN_DIR still exists, force deleting..." rm -rf "$OLD_PLUGIN_DIR" fi fi # Remove existing agent-sentry plugin (will be reinstalled) NEW_PLUGIN_DIR="${EXTENSIONS_DIR}/${PLUGIN_NAME}" if [[ -d "$NEW_PLUGIN_DIR" ]]; then echo "Existing $PLUGIN_NAME plugin found, removing..." if command -v openclaw &>/dev/null; then echo "y" | openclaw plugins uninstall "$PLUGIN_NAME" 2>/dev/null || true else echo "openclaw command not found, skipping uninstall" fi # Double-check and force delete if directory still exists if [[ -d "$NEW_PLUGIN_DIR" ]]; then echo "Directory $NEW_PLUGIN_DIR still exists, force deleting..." rm -rf "$NEW_PLUGIN_DIR" fi fi LEGACY_PLUGIN_DIR="${EXTENSIONS_DIR}/${LEGACY_PLUGIN_NAME}" if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then echo "Legacy plugin found: $LEGACY_PLUGIN_NAME, uninstalling..." if command -v openclaw &>/dev/null; then echo "y" | openclaw plugins uninstall "$LEGACY_PLUGIN_NAME" 2>/dev/null || true else echo "openclaw command not found, skipping uninstall" fi if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then echo "Directory $LEGACY_PLUGIN_DIR still exists, force deleting..." rm -rf "$LEGACY_PLUGIN_DIR" fi fi echo "" echo "[3/5] Downloading and installing agent-sentry from TOS..." CS_TGZ_PATH="/tmp/agent-sentry-${TARGET_VERSION}.tgz" echo "Downloading from: ${CS_TOS_BASE_URL}/agent-sentry-${TARGET_VERSION}.tgz" if ! wget -q "${CS_TOS_BASE_URL}/agent-sentry-${TARGET_VERSION}.tgz" -O "$CS_TGZ_PATH"; then echo "Warning: Failed to download agent-sentry from TOS, will continue with Go binary" else echo "Extracting to: ${CS_TEMP_DIR}" rm -rf "$CS_TEMP_DIR" mkdir -p "$CS_TEMP_DIR" if ! tar -xzf "$CS_TGZ_PATH" -C "$CS_TEMP_DIR"; then echo "Warning: Failed to extract agent-sentry, will continue with Go binary" else echo "Installing from local package..." INSTALL_DIR="${CS_TEMP_DIR}/package" if command -v openclaw &>/dev/null; then if ! openclaw plugins install "$INSTALL_DIR" 2>/dev/null; then echo "Warning: Failed to install agent-sentry, will continue with Go binary" else echo "agent-sentry installed successfully" fi else echo "openclaw command not found, skipping installation" fi fi echo "Cleaning up TOS download..." rm -f "$CS_TGZ_PATH" rm -rf "$CS_TEMP_DIR" fi echo "" echo "[4/5] Downloading Go binary..." echo "Downloading from: $GO_BINARY_URL" if ! wget -q "$GO_BINARY_URL" -O "$GO_BINARY_PATH"; then echo "Error: Failed to download Go binary" exit 1 fi # Make it executable chmod +x "$GO_BINARY_PATH" echo "" echo "[5/5] Running Go binary..." # Set environment variables export VOLC_ACCESS_KEY_ID="$VOLC_ACCESS_KEY_ID" export VOLC_SECRET_KEY="$VOLC_SECRET_KEY" # Build command CMD_ARGS=() CMD_ARGS+=("-space_id" "$SPACE_ID") CMD_ARGS+=("-ark_claw_id" "$ARK_CLAW_ID") CMD_ARGS+=("-region" "$REGION") CMD_ARGS+=("-config_file" "$CONFIG_FILE") if [[ -n "$TOKEN" ]]; then CMD_ARGS+=("-token" "$TOKEN") fi if [[ -n "$NAME" ]]; then CMD_ARGS+=("-name" "$NAME") fi if [[ -n "$USER_UID" ]]; then CMD_ARGS+=("-user_uid" "$USER_UID") fi echo "Executing: $GO_BINARY_PATH ${CMD_ARGS[*]}" if ! "$GO_BINARY_PATH" "${CMD_ARGS[@]}"; then rc=$? echo "Error: failed to execute: $GO_BINARY_PATH ${CMD_ARGS[*]} (exit_code=${rc})" >&2 exit $rc fi echo "" echo "Checking openclaw version and setting hooks..." echo "=======================================" if command -v openclaw &>/dev/null; then # 获取 openclaw 版本 if version_output=$(openclaw --version 2>&1); then echo "Openclaw version command output: $version_output" # 使用正则表达式解析版本号 if [[ "$version_output" =~ OpenClaw[[:space:]]+([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then year=${BASH_REMATCH[1]} month=${BASH_REMATCH[2]} patch=${BASH_REMATCH[3]} echo "Openclaw version $year.$month.$patch detected" # 判断版本是否 >= 2026.4.27 should_set_hook=false if (( year > 2026 )); then should_set_hook=true elif (( year == 2026 )); then if (( month > 4 )); then should_set_hook=true elif (( month == 4 )) && (( patch >= 27 )); then should_set_hook=true fi fi if [ "$should_set_hook" = true ]; then echo "Setting allowConversationAccess hook..." openclaw config set plugins.entries.agent-sentry.hooks.allowConversationAccess true 2>/dev/null || echo "Warning: Failed to set hook configuration" else echo "Openclaw version $year.$month.$patch is older than 2026.4.27, skipping hook configuration" fi else echo "Could not parse openclaw version from: $version_output" fi else echo "Could not get openclaw version, skipping hook configuration" fi else echo "openclaw command not found, skipping hook configuration" fi echo "" echo "Cleaning up..." echo "=======================================" rm -f "$GO_BINARY_PATH" echo "Restarting OpenClaw gateway..." if command -v openclaw &>/dev/null; then openclaw gateway restart else echo "Warning: openclaw command not found, skipping gateway restart" fi echo "" echo "Done!" ``` ## 参数说明调用接口注册服务前，请先获取以下参数。 |**配置项** |**数据类型** |**是否必填** |**说明** | |---|---|---|---| |VOLC_SECRET_KEY |String |是 |* 已经开通 AgentSentry 服务账号拥有的 Secret Access Key 和 Access Key ID。

* **获取方式**：请参考 [API 访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。

说明

请使用主账号对应的 Secret Access Key 和 Access Key ID。

如需使用子账号配置，请授予 AgentSentryFullAccess和ArkClawFullAccess权限。授权操作方法请参见如何为子账号授予权限。

| |VOLC_ACCESS_KEY_ID |String |是 || |SPACE_ID |String |是 |* ArkClaw 企业版的空间 ID。

* **获取方式**：

1. 登录[火山引擎 ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise/)。

2. 在空间概览模块获取空间 ID，例如csi\-\*\*\*\*。

| |REGION |String |否 |* ArkClaw 所属地域。

* 华北2（北京）：cn\-beijing

* 华东2（上海）：cn\-shanghai

* **获取方式**：

1. 登录[火山引擎 ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise/)。

2. 在顶部菜单栏查看服务所属地域。

| |TARGET_VERSION |String |是 |* 需要升级的 AgentSentry 目标版本。 | |CONFIG_FILE |String |否 |* OpenClaw 配置文件（openclaw.json）所在路径，默认为`/root/.openclaw/openclaw.json`，不填则使用默认路径。

* **获取方式**：可以直接通过 AI 助手来获取详细路径，或在终端使用命令`find / -name openclaw.json`查找。 | |NAME |String |否 |* 保持留空。

* 需要自定义单个助手在安全管理模块显示的名称时，可以配置。

* 批量升级多个 ArkClaw 助手时请勿配置，否则会覆盖多个助手的名称信息。 | |USER_UID |String |否 |* 保持留空。

* 需要自定义单个助手在安全管理模块所属用户的唯一标识时，可以配置。

* 批量升级多个 ArkClaw 助手时请勿配置，否则会覆盖多个助手的所属用户信息。 | ## 常见问题 ### 如何确认 ArkClaw 的版本？ ArkClaw 的不同版本对应不同的 OpenClaw 框架版本，查看方式如下： 1. 登录 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)。 2. 在左侧导航栏中，选择**实例列表**。 3. 在**实例列表**中，查看 ArkClaw 实例对应的**当前版本**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_78eff9badfc2fb331c2cb53abc3abea3.png) ### 如何为子账号授予权限？ #### 为多个子账号批量授予同一权限 1. 使用主账号登录 [IAM 控制台](https://console.volcengine.com/iam/identitymanage/user)。 2. 在左侧导航栏中，选择**权限策略**。 3. 在搜索框中输入对应权限名称，并按下回车。 * **ArkClawFullAccess**：用于获取 ArkClaw 企业版读写权限 * **ClawSentryFullAccess**：用于获取 AgentSentry 读写权限 4. 在搜索结果中，单击策略对应的**授权**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_31f1e00f00e3a14753a709b140784fa2.png) 5. 勾选需要授权的子账号用户。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_29329795e6f6b1e8c0b333da106aff95.png) 6. 确认后，单击**提交**。授权后，该子账号的 AK 和 SK 可用于运维操作。 #### 为同一子账号批量授予多个权限 1. 使用主账号登录 [IAM 控制台](https://console.volcengine.com/iam/identitymanage/user)。 2. 在左侧导航栏中，选择**用户**。 3. 在搜索框中输入对应用户名称，并按下回车。 4. 在搜索结果中，单击用户对应的**添加权限**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c70b4b5d881ce477e89cd40e0e8d1be2.png) 5. 分别搜索以下权限名，并勾选。 * **ArkClawFullAccess**：用于获取 ArkClaw 企业版读写权限 * **AgentSentryFullAccess**：用于获取 AgentSentry 读写权限 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ab5e200ca0c608999ec1e3dea66c5f47.png) 6. 确认后，单击**提交**。授权后，该子账号的 AK 和 SK 可用于运维操作。 ### 运维作业执行成功，但助手版本没更新是什么原因？ * 原因：可能是因为执行升级的账号不具备相关权限。 * 排查： 1. 单击作业对应的执行结果。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_37d2e0da010439af06b04e55be108d9c.png) 2. 单击查看日志。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bc1b8061a067f8f107a86d4275743adc.png) 3. 查看失败报错信息。![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c1f95769cbd5916aac6dee2c68eac0f4.png) 如果提示“User is not authorized to perform: arkclaw:GetClawInstance on resource:”，则表示账号缺少**ArkClawFullAccess权限。** * 解决方案：请参考如何为子账号授予权限为账号添加**ArkClawFullAccess**权限。