alibabacloud-tablestore-openclaw-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prerequisites

前置要求

The user must have:

An Alibaba Cloud account
Credentials — AccessKey ID + Secret (with
```
AliyunOTSFullAccess
```
permission) or ECS RAM Role (recommended on ECS)
An 阿里云百炼 API Key (for Qwen LLM and embedding)
Optional: existing Tablestore instance endpoint + instance name (otherwise auto-created)
Optional: region ID for auto-provisioning (defaults to
```
cn-hangzhou
```
)

📋 RAM Permissions: See references/ram-policies.md for the complete list of required API permissions.

用户必须具备：

一个阿里云账号
凭证 — 拥有
```
AliyunOTSFullAccess
```
权限的AccessKey ID + Secret 或 ECS RAM角色（ECS环境下推荐使用）
阿里云百炼API Key（用于Qwen大模型和向量嵌入）
可选：已有的Tablestore实例endpoint + 实例名称（否则将自动创建）
可选：自动创建实例所需的区域ID（默认值为
```
cn-hangzhou
```
）

📋 RAM权限： 完整的API权限要求请参考references/ram-policies.md

Definition of Done

完成标准

This task is NOT complete until all of the following are true:

User has provided credentials
Plugin is installed (version 0.8.2)
```
openclaw.json
```
is configured correctly
OpenClaw is restarted
Setup is verified (plugin loads without errors)

只有满足以下所有条件时，该任务才算完成：

用户已提供所需凭证
插件已安装（版本0.8.2）
```
openclaw.json
```
配置正确
OpenClaw已重启
配置已验证（插件加载无报错）

Onboarding

配置流程

Step 0 — Collect credentials

步骤0 — 收集凭证

[AGENT]

Ask the user:

To set up Tablestore Mem0, I need:

Required:

Alibaba Cloud AccessKey ID

Alibaba Cloud AccessKey Secret

阿里云百炼 API Key
Optional (if you have an existing Tablestore instance): 4. Tablestore endpoint (e.g.
https://my-instance.cn-hangzhou.ots.aliyuncs.com
) 5. Tablestore instance name
If you don't provide an endpoint and instance name, I'll automatically create a new Tablestore instance. In that case, I need: 6. Region ID (e.g.
cn-hangzhou
,
cn-shanghai
)

Ask the user:

Question 1 — Authentication: How would you like to authenticate?

Option A: ECS RAM Role (recommended on ECS) — Provide the role name.

Option B: AccessKey — Provide AccessKey ID and Secret.

Question 2 — Tablestore instance: Do you already have a Tablestore instance?

Yes → Provide endpoint and instance name.

No → Provide region ID for auto-provisioning.

⚠️ HIGH-RISK OPERATION — Pre-flight Confirmation:

If the user answers No, the agent MUST:

Explicit Confirmation:
⚠️ This setup will create a new Tablestore instance in your Alibaba Cloud account.
- Instance type: VCU (pay-as-you-go, typically under ¥1/month)
- Region: as specified Do you confirm? (yes/no)
Double-check:
Please verify in Tablestore Console (
```
https://ots.console.aliyun.com/
```
) that you don't have existing instances.

Do NOT proceed until the user explicitly confirms.

If the user is missing credentials, point them to:

Alibaba Cloud sign-up:

https://account.alibabacloud.com/register/intl_register.htm

AccessKey creation:

https://ram.console.aliyun.com/manage/ak

阿里云百炼 API Key:

https://dashscope.console.aliyun.com/apiKey

[AGENT]

向用户询问以下信息：

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

必填项：

阿里云AccessKey ID

阿里云AccessKey Secret

阿里云百炼API Key
可选项（如果您已有现成的Tablestore实例）： 4. Tablestore endpoint（例如
https://my-instance.cn-hangzhou.ots.aliyuncs.com
） 5. Tablestore 实例名称
如果您未提供endpoint和实例名称，我将自动创建一个新的Tablestore实例，此时我还需要： 6. 区域ID（例如
cn-hangzhou
、
cn-shanghai
）

再向用户确认以下问题：

问题1 — 身份验证方式： 您希望使用哪种方式进行身份验证？

选项A：ECS RAM角色（ECS环境下推荐）——请提供角色名称。

选项B：AccessKey——请提供AccessKey ID和Secret。

问题2 — Tablestore实例： 您是否已有现成的Tablestore实例？

是 → 请提供endpoint和实例名称。

否 → 请提供用于自动创建实例的区域ID。

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

如果用户回答否，Agent必须执行以下操作：

明确确认：
⚠️ 该配置将在您的阿里云账号中创建一个新的Tablestore实例。
- 实例类型：VCU（按量付费，通常每月费用低于¥1）
- 区域：您指定的区域 您是否确认？（是/否）
二次核查：
请您在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

Setting up ECS RAM Role (if the user chose Option A)

配置ECS RAM角色（如果用户选择选项A）

Attach a RAM role to the ECS instance — Documentation
Grant the role
AliyunOTSFullAccess
— Reference

为ECS实例绑定RAM角色 — 文档指引
为角色授予
AliyunOTSFullAccess
权限 — 参考指引

Step 1 — Install plugin

步骤1 — 安装插件

Plugin version:
0.8.2

⚠️ External Package Installation Notice:

This skill will install
@tablestore/openclaw-mem0@0.8.2
from npm registry. By proceeding, you acknowledge installing an external package. Do you consent? (yes/no)

Wait for user confirmation, then:

bash

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

, fallback to manual install:

bash

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

插件版本：
0.8.2

⚠️ 外部包安装提示：

该技能将从npm仓库安装
@tablestore/openclaw-mem0@0.8.2
，继续操作即表示您同意安装外部包。 您是否同意？（是/否）

等待用户确认后，执行以下操作：

bash

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

错误，回退到手动安装：

bash

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

Step 2 — Detect OpenClaw version

步骤2 — 检测OpenClaw版本

bash

openclaw --version

Version
```
>= 2.2.0
```
→ use Step 3A
Version
```
< 2.2.0
```
→ use Step 3B (remove
```
.plugins.allow
```
line)

bash

openclaw --version

版本
```
>= 2.2.0
```
→ 执行步骤3A
版本
```
< 2.2.0
```
→ 执行步骤3B（删除
```
.plugins.allow
```
配置行）

Step 3 — Configure openclaw.json

步骤3 — 配置openclaw.json

Detect config file path:

bash

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

⚠️ Credential Security (REQUIRED):

ALWAYS prefer environment variables:

bash

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>"

⚠️ Input Validation (REQUIRED):

Input	Validation Rule
AccessKey ID	Regex: `^LTAI[Nt][A-Za-z0-9]{12,20}$`
AccessKey Secret	Alphanumeric, ~30 chars
Region ID	Regex: `^cn-[a-z]+(-[0-9]+)?$` or `^[a-z]+-[a-z]+-[0-9]+$`
Endpoint	Regex: `^https://[a-z0-9-]+\.[a-z0-9-]+\.ots\.aliyuncs\.com$`
Instance Name	Regex: `^[a-z][a-z0-9-]{0,19}$`

⚠️ Embedder/LLM provider MUST be
"openai"
with baseURL
"https://dashscope.aliyuncs.com/compatible-mode/v1"
, NOT
"dashscope"
.

检测配置文件路径：

bash

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

⚠️ 凭证安全（必填要求）：

优先使用环境变量存储凭证：

bash

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个字符
区域ID	正则规则： `^cn-[a-z]+(-[0-9]+)?$` 或 `^[a-z]+-[a-z]+-[0-9]+$`
Endpoint	正则规则： `^https://[a-z0-9-]+\.[a-z0-9-]+\.ots\.aliyuncs\.com$`
实例名称	正则规则： `^[a-z][a-z0-9-]{0,19}$`

⚠️ 向量嵌入/大模型提供商必须设置为
"openai"
，baseURL设置为
"https://dashscope.aliyuncs.com/compatible-mode/v1"
，不得使用
"dashscope"
。

Step 3A — OpenClaw ≥2.2.0

步骤3A — OpenClaw ≥2.2.0

Auth method	Has existing instance?	`vectorStore.config` fields
AccessKey	No	`accessKeyId` , `accessKeySecret` , `regionId`
AccessKey	Yes	`accessKeyId` , `accessKeySecret` , `endpoint` , `instanceName`
ECS RAM Role	No	`roleName` , `regionId`
ECS RAM Role	Yes	`roleName` , `endpoint` , `instanceName`

Template (AccessKey auth + auto-create):

bash

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"

For existing instance: replace

regionId

with

endpoint

and

instanceName

. For ECS RAM Role: replace

accessKeyId

accessKeySecret

with

roleName

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

模板（AccessKey验证 + 自动创建实例）：

bash

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

。

Step 3B — OpenClaw <2.2.0

步骤3B — OpenClaw <2.2.0

Same as Step 3A but remove the

.plugins.allow

line.

与步骤3A操作一致，但移除

.plugins.allow

配置行。

Step 4 — Restart OpenClaw

步骤4 — 重启OpenClaw

bash

openclaw gateway restart

Wait ~1 minute for the gateway to restart.

bash

openclaw gateway restart

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

Step 5 — Verify setup

步骤5 — 验证配置

bash

openclaw mem0 stats

Success criteria: plugin loads without errors, shows mode and memory count.

bash

openclaw mem0 stats

成功标准：插件加载无报错，显示运行模式和记忆条数。

Step 6 — Handoff

步骤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.

✅ Tablestore Mem0已配置完成。

您的记忆现在由阿里云Tablestore提供支持。
插件会在每次会话前自动召回相关记忆，并在每次会话结束后捕获关键信息。

手动命令："remember this" / "what do you know about me?" / "forget that"

配置信息：Tablestore向量存储 + 阿里云百炼text-embedding-v3 + Qwen-Plus
实例：<自动创建或用户提供的实例>

安全提示：ECS环境下优先使用ECS RAM角色，切勿将凭证提交到版本控制系统。

Configuration Reference

配置参考

Parameter	Required	Default	Description
`accessKeyId`	No*	—	AccessKey ID (or env `TABLESTORE_ACCESS_KEY_ID` )
`accessKeySecret`	No*	—	AccessKey Secret (or env `TABLESTORE_ACCESS_KEY_SECRET` )
`roleName`	No*	—	ECS RAM Role name (or env `TABLESTORE_ROLE_NAME` )
`endpoint`	No	Auto-created	Tablestore instance endpoint
`instanceName`	No	Auto-created	Tablestore instance name
`regionId`	No	`cn-hangzhou`	Region for auto-provisioning
`tableName`	No	`mem0_vectors`	Data table name
`dimension`	No	`1024`	Vector dimension

*Required unless

roleName

is set.

参数	是否必填	默认值	描述
`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

，否则为必填项。

Auto-provisioning

自动创建规则

When

endpoint

instanceName

not provided, creates VCU instance with:

VCU=0 (pay-as-you-go)
Auto-enables public internet access if VPC unreachable

当未提供

endpoint

instanceName

时，将按以下配置创建VCU实例：

VCU=0（按量付费）
如果VPC网络不可达，将自动开启公网访问权限

Troubleshooting

问题排查

Symptom	Fix
Plugin not loading	Check `slots.memory = "openclaw-mem0"` and `enabled = true`
`AccessKeyId is invalid`	Verify AccessKey is correct and account is active
Auto-provisioning fails	Ensure AccessKey has `AliyunOTSFullAccess`
Embedding errors	Verify `DASHSCOPE_API_KEY` is set
VPC endpoint unreachable	Plugin auto-enables public access; verify `AliyunOTSFullAccess`
`extract tar timed out`	Use manual fallback: `npm pack` + system `tar`
Provider shows `dashscope`	Change provider to `"openai"` with correct baseURL

现象	解决方案
插件未加载	检查 `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` 命令
提供商显示为 `dashscope`	将提供商修改为 `"openai"` 并配置正确的baseURL

Update

版本更新

Do not set up automatic updates. Only update when explicitly requested.

不要设置自动更新，仅在用户明确要求时再进行更新。