前提条件

用户必须具备以下条件：

1. 一个 阿里云账号
2. 凭证 — AccessKey ID + Secret（需具备 AliyunOTSFullAccess 权限），或 ECS RAM Role（在 ECS 上推荐使用）
3. 一个 阿里云百炼 API Key（用于 Qwen 大语言模型和向量嵌入）
4. 可选：已有的 Tablestore 实例 endpoint + 实例名称（否则将自动创建）
5. 可选：用于自动配置的 region ID（默认为 cn-hangzhou）

📋 RAM 权限说明：所需 API 权限的完整列表，请参见 references/ram-policies.md。

完成标准

以下所有条件均满足前，本任务视为未完成：

1. 用户已提供有效凭证
2. 插件已安装（版本 0.8.2）
3. openclaw.json 已正确配置
4. OpenClaw 已重启
5. 配置已验证通过（插件加载无报错）

接入流程

步骤 0 — 收集凭证

[AGENT] 向用户提问：

为配置 Tablestore Mem0，我需要以下信息：

必填项：

1. 阿里云 AccessKey ID
2. 阿里云 AccessKey Secret
3. 阿里云百炼 API Key

可选项（若您已有 Tablestore 实例）：
4. Tablestore endpoint（例如：https://my-instance.cn-hangzhou.ots.aliyuncs.com）
5. Tablestore 实例名称

若您不提供 endpoint 和实例名称，我将为您自动创建一个新的 Tablestore 实例。此时，我还需要：
6. Region ID（例如：cn-hangzhou、cn-shanghai）

继续向用户提问：

问题 1 — 认证方式：您希望采用哪种认证方式？

• 选项 A：ECS RAM Role（ECS 上推荐）—— 请提供 角色名称。
• 选项 B：AccessKey —— 请提供 AccessKey ID 和 Secret。

问题 2 — Tablestore 实例：您是否已拥有 Tablestore 实例？

• 是 → 请提供 endpoint 和实例名称。
• 否 → 请提供用于自动配置的 region ID。

⚠️ 高风险操作 — 预检确认：

若用户回答 否，代理必须执行以下操作：

1. 明确确认：

   ⚠️ 此配置过程将在您的阿里云账号中新建一个 Tablestore 实例。

   • 实例类型：VCU（按量付费，通常低于 ¥1/月）
   • 地域：按您指定的 region 执行
     是否确认？（yes/no）

2. 二次核验：

   请前往 Tablestore 控制台（https://ots.console.aliyun.com/）确认当前账号下无已有实例。

在用户明确确认前，不得继续执行后续步骤。

若用户缺少必要凭证，请引导其访问以下链接：

• 阿里云注册页：https://account.alibabacloud.com/register/intl_register.htm
• AccessKey 创建页：https://ram.console.aliyun.com/manage/ak
• 阿里云百炼 API Key 管理页：https://dashscope.console.aliyun.com/apiKey

配置 ECS RAM Role（如用户选择选项 A）

1. 为 ECS 实例绑定 RAM 角色 —— 参考文档
2. 为该角色授予 AliyunOTSFullAccess 权限 —— 参考文档

步骤 1 — 安装插件

插件版本：0.8.2

⚠️ 外部包安装提示：

本技能将从 npm 仓库安装 @tablestore/openclaw-mem0@0.8.2。继续执行即表示您同意安装第三方软件包。
是否同意？（yes/no）

等待用户确认后，执行以下命令：

NPMJS_TIME="$(curl -o /dev/null -sS --connect-timeout 2 --max-time 6 -w '%{time_total}' https://registry.npmjs.org/@tablestore%2fopenclaw-mem0 || echo timeout)"
MIRROR_TIME="$(curl -o /dev/null -sS --connect-timeout 2 --max-time 6 -w '%{time_total}' https://registry.npmmirror.com/@tablestore%2fopenclaw-mem0 || echo timeout)"

if [ "$MIRROR_TIME" != "timeout" ] && { [ "$NPMJS_TIME" = "timeout" ] || awk "BEGIN { exit !($NPMJS_TIME > 2 && $MIRROR_TIME < $NPMJS_TIME) }"; }; then
  echo "Using China npm mirror"
  NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @tablestore/openclaw-mem0@0.8.2
else
  openclaw plugins install @tablestore/openclaw-mem0@0.8.2
fi

若出现 extract tar timed out 错误，则回退至手动安装：

cd /tmp && npm pack @tablestore/openclaw-mem0@0.8.2
mkdir -p /tmp/openclaw-mem0-install
tar xzf /tmp/tablestore-openclaw-mem0-*.tgz -C /tmp/openclaw-mem0-install --strip-components=1
openclaw plugins install /tmp/openclaw-mem0-install

步骤 2 — 检测 OpenClaw 版本

openclaw --version

• 版本 >= 2.2.0 → 使用 步骤 3A
• 版本 < 2.2.0 → 使用 步骤 3B（移除 .plugins.allow 行）

步骤 3 — 配置 openclaw.json

检测配置文件路径：

OPENCLAW_CONFIG="$(openclaw config file 2>/dev/null | head -1)"
OPENCLAW_CONFIG="${OPENCLAW_CONFIG/#~/$HOME}"
echo "Config file: $OPENCLAW_CONFIG"

⚠️ 凭证安全（强制要求）：

始终优先使用环境变量：

export TABLESTORE_ACCESS_KEY_ID=""
export TABLESTORE_ACCESS_KEY_SECRET=""
export DASHSCOPE_API_KEY=""

⚠️ 输入校验（强制要求）：

⚠️ Embedder / LLM 提供方必须设为 "openai"，且 baseURL 必须为 "https://dashscope.aliyuncs.com/compatible-mode/v1"，不可使用 "dashscope"。

步骤 3A — OpenClaw ≥2.2.0

模板（AccessKey 认证 + 自动创建）：

jq '
  .plugins.slots.memory = "openclaw-mem0" |
  .plugins.entries["openclaw-mem0"] = {
    enabled: true,
    config: {
      mode: "open-source",
      oss: {
        vectorStore: {
          provider: "tablestore",
          config: {
            accessKeyId: "${TABLESTORE_ACCESS_KEY_ID}",
            accessKeySecret: "${TABLESTORE_ACCESS_KEY_SECRET}",
            regionId: "cn-hangzhou"
          }
        },
        embedder: {
          provider: "openai",
          config: {
            apiKey: "${DASHSCOPE_API_KEY}",
            model: "text-embedding-v3",
            baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
          }
        },
        llm: {
          provider: "openai",
          config: {
            apiKey: "${DASHSCOPE_API_KEY}",
            model: "qwen-plus",
            baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
          }
        }
      }
    }
  } |
  .plugins.allow = ((.plugins.allow // []) + ["openclaw-mem0"] | unique)
' "$OPENCLAW_CONFIG" > /tmp/openclaw-tmp.json && mv /tmp/openclaw-tmp.json "$OPENCLAW_CONFIG"

对于 已有实例：将 regionId 替换为 endpoint 和 instanceName。
对于 ECS RAM Role：将 accessKeyId/accessKeySecret 替换为 roleName。

步骤 3B — OpenClaw <2.2.0

与步骤 3A 相同，但需移除 .plugins.allow 行。

步骤 4 — 重启 OpenClaw

openclaw gateway restart

等待约 1 分钟，确保网关完成重启。

步骤 5 — 验证配置

openclaw mem0 stats

成功标志：插件加载无报错，并显示当前 mode 和 memory 数量。

步骤 6 — 交付确认

✅ Tablestore Mem0 已就绪。

您的记忆数据现已由阿里云 Tablestore 持久化存储。
插件将在每次对话开始前自动召回相关记忆，并在每次对话结束后自动提取关键事实。

常用指令：“remember this” / “what do you know about me?” / “forget that”

配置详情：Tablestore 向量存储 + 阿里云百炼 text-embedding-v3 + Qwen-Plus

实例：<自动创建或用户指定>

安全建议：ECS 环境下优先使用 ECS RAM Role；切勿将凭证提交至版本控制系统。

配置参考

*当 roleName 已设置时，此项非必需。

自动配置说明

当未提供 endpoint/instanceName 时，将创建一个 VCU 实例，具体配置如下：

• VCU=0（按量付费）
• 若 VPC 不可达，插件将自动启用公网访问能力

故障排查

更新说明

请勿设置自动更新。仅在用户明确要求时才执行更新操作。