alibabacloud-tablestore-openclaw-memory

前置条件

用户必须拥有：

1. 一个 Alibaba Cloud 账号
2. 凭证 — AccessKey ID + Secret（具有 AliyunOTSFullAccess 权限）或 ECS RAM 角色（在 ECS 上推荐）
3. 一个 阿里云百炼 API Key（用于 Qwen 大模型和嵌入）
4. 可选：现有 Tablestore 实例的端点和实例名称（否则将自动创建）
5. 可选：用于自动配置的区域 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. Alibaba Cloud AccessKey ID
2. Alibaba Cloud AccessKey Secret
3. 阿里云百炼 API Key

可选（如果你已有 Tablestore 实例）： 4. Tablestore 端点（例如 https://my-instance.cn-hangzhou.ots.aliyuncs.com） 5. Tablestore 实例名称

如果你不提供端点和实例名称，我将自动创建一个新的 Tablestore 实例。在这种情况下，我需要： 6. 区域 ID（例如 cn-hangzhou、cn-shanghai）

询问用户：

问题 1 — 身份验证： 你希望如何进行身份验证？

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

问题 2 — Tablestore 实例： 你已经有 Tablestore 实例了吗？

• 是 → 提供端点和实例名称。
• 否 → 提供用于自动配置的区域 ID。

⚠️ 高风险操作 — 执行前确认：

如果用户回答否，Agent 必须：

1. 明确确认：

   ⚠️ 此设置将在你的 Alibaba Cloud 账号中创建一个新的 Tablestore 实例。

   • 实例类型：VCU（按量付费，通常低于 ¥1/月）
   • 区域：按指定设置 确认吗？（是/否）

2. 再次核实：

   请在 Tablestore 控制台（https://ots.console.aliyun.com/）中确认你没有现有实例。

在用户明确确认之前，不要继续操作。

如果用户缺少凭证，请引导其前往：

• 注册 Alibaba Cloud 账号：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 角色（如果用户选择了选项 A）

1. 将 RAM 角色附加到 ECS 实例 — 文档
2. 为该角色授予 AliyunOTSFullAccess 权限 — 参考

步骤 1 — 安装插件

插件版本：0.8.2

⚠️ 外部软件包安装须知：

此技能将从 npm 注册表安装 @tablestore/[email protected]。继续操作即表示你确认安装此外部软件包。 你同意吗？（是/否）

等待用户确认，然后：

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/[email protected]
else
  openclaw plugins install @tablestore/[email protected]
fi

如果出现 extract tar timed out，则回退到手动安装：

cd /tmp && npm pack @tablestore/[email protected]
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="<your-access-key-id>"
export TABLESTORE_ACCESS_KEY_SECRET="<your-access-key-secret>"
export DASHSCOPE_API_KEY="<your-dashscope-api-key>"

⚠️ 输入验证（必需）：

输入	验证规则
AccessKey ID	正则表达式：^LTAI[Nt][A-Za-z0-9]{12,20}$
AccessKey Secret	字母数字字符，约 30 个
Region ID	正则表达式：^cn-[a-z]+(-[0-9]+)?$ 或 ^[a-z]+-[a-z]+-[0-9]+$
Endpoint	正则表达式：^https://[a-z0-9-]+\.[a-z0-9-]+\.ots\.aliyuncs\.com$
Instance Name	正则表达式：^[a-z][a-z0-9-]{0,19}$

⚠️ Embedder/LLM 提供商必须设为 "openai"，baseURL 必须设为 "https://dashscope.aliyuncs.com/compatible-mode/v1"，不能设为 "dashscope"。

步骤 3A — OpenClaw ≥2.2.0

认证方式	是否已有实例？	vectorStore.config 字段
AccessKey	否	accessKeyId、accessKeySecret、regionId
AccessKey	是	accessKeyId、accessKeySecret、endpoint、instanceName
ECS RAM 角色	否	roleName、regionId
ECS RAM 角色	是	roleName、endpoint、instanceName

模板（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 角色：将 accessKeyId/accessKeySecret 替换为 roleName。

步骤 3B — OpenClaw <2.2.0

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

步骤 4 — 重启 OpenClaw

openclaw gateway restart

等待约 1 分钟，让网关重启。

步骤 5 — 验证设置

openclaw mem0 stats

成功标准：插件加载无错误，并显示模式和记忆数量。

步骤 6 — 移交

✅ Tablestore Mem0 is ready.

Your memory is now backed by Alibaba Cloud Tablestore.
The plugin will automatically recall relevant memories before each conversation
and capture key facts after each conversation.

Manual commands: "remember this" / "what do you know about me?" / "forget that"

Configuration: Tablestore vector store + 阿里云百炼 text-embedding-v3 + Qwen-Plus
Instance: <auto-created or user-provided>

Security: Prefer ECS RAM Role on ECS. Never commit credentials to version control.

---

配置参考

参数	必需	默认值	说明
accessKeyId	否*	—	AccessKey ID（或环境变量 TABLESTORE_ACCESS_KEY_ID）
accessKeySecret	否*	—	AccessKey Secret（或环境变量 TABLESTORE_ACCESS_KEY_SECRET）
roleName	否*	—	ECS RAM 角色名称（或环境变量 TABLESTORE_ROLE_NAME）
endpoint	否	自动创建	Tablestore 实例 Endpoint
instanceName	否	自动创建	Tablestore 实例名称
regionId	否	cn-hangzhou	用于自动配置资源的地域
tableName	否	mem0_vectors	数据表名称
dimension	否	1024	向量维度

*除非设置了 roleName，否则为必需项。

自动配置资源

未提供 endpoint/instanceName 时，会创建 VCU 实例，并进行以下设置：

• VCU=0（按量付费）
• 如果 VPC 不可达，则自动启用公网访问

---

故障排除

症状	解决方法
插件未加载	检查 slots.memory = "openclaw-mem0" 和 enabled = true
AccessKeyId is invalid	确认 AccessKey 正确且账户处于有效状态
自动配置资源失败	确保 AccessKey 具有 AliyunOTSFullAccess 权限
嵌入错误	确认已设置 DASHSCOPE_API_KEY
VPC Endpoint 无法访问	插件会自动启用公网访问；确认具有 AliyunOTSFullAccess 权限
extract tar timed out	使用手动备用方案：npm pack + 系统 tar
Provider 显示为 dashscope	将 Provider 改为 "openai"，并设置正确的 baseURL

---

更新

不要设置自动更新。仅在明确提出请求时才更新。