Setnamefeat(memory): refine compact mechanism runtime state

OpenClaw + oGMemory 一键安装部署指南

概述

本部署方案采用 Docker 容器化部署，包含以下组件：

组件	容器名称	端口	说明
openGauss	opengauss	15432	向量数据库（可选）
oGMemory	ogmem	8090	记忆服务 HTTP API
OpenClaw Gateway	openclaw_ogmem	18789	Web 界面入口

⚠️ 架构说明： 本项目提供的 Docker 镜像仅支持 ARM64 (鲲鹏) 架构，不支持 x86_64。请确保部署环境为 ARM 服务器（如华为云鲲鹏实例）。

环境要求

系统要求

操作系统: Linux (推荐 Ubuntu 20.04+, CentOS 7+, openEuler)
CPU 架构: ARM64 (鲲鹏) — 镜像仅支持 ARM，不支持 x86_64
内存: 至少 8GB (推荐 16GB+)
磁盘: 至少 20GB 可用空间

软件要求

Docker: 20.10+
curl: 用于下载脚本

检查 Docker 是否安装：

docker --version

确认当前系统为 ARM64 架构：

uname -m
# 输出应为 aarch64

如未安装 Docker，请参考 Docker 官方文档安装。

网络要求

确保能访问以下地址：
- 华为云 SWR 镜像仓库: swr.cn-north-4.myhuaweicloud.com
- LLM API 服务地址（如华为云、火山引擎、阿里云等）

快速开始

远程一键安装

curl -fsSL https://raw.gitcode.com/opengauss/oGMemory/raw/dev/deploy/install.sh | bash

执行后会下载以下文件到 ./ogmem-deploy/ 目录：

deploy.env: 配置文件（OpenClaw + 基础设施配置）
ogmemory.example.yaml: oGMemory 服务配置模板
deploy.sh: 部署脚本

配置说明

配置文件结构

本部署方案使用 两个配置文件，各司其职：

文件	职责	内容
`deploy.env`	OpenClaw + 基础设施	LLM 共享配置、openGauss、容器名/镜像、部署参数
`ogmemory.yaml`	oGMemory 业务配置	LLM、Embedding、向量数据库、身份认证、缓存等

关键机制：ogmemory.yaml 支持 ${ENV_VAR} 语法引用 deploy.env 中的变量，避免重复配置。

职责边界更新：

deploy.sh 不再从 ogmemory.yaml 反向推导 OpenClaw 默认认证参数。
单实例模式下，OpenClaw 认证参数只按 OG_AUTH_API_KEY -> OG_ROOT_API_KEY、OG_AUTH_ACCOUNT_ID -> OG_ACCOUNT_ID 回退。
openclaw.json 由 OpenClaw 容器入口脚本托管；升级后如果检测到缺少关键字段，会先备份旧文件，再按当前模板重建。

推荐做法：

把共享配置统一放在 deploy.env，例如 OG_ROOT_API_KEY、OG_ACCOUNT_ID、OG_USER_ID、OG_AGENT_ID。
ogmemory.yaml 默认通过 ${ENV_VAR} 引用这些值，不再手工重复填写相同内容。
只有在 oGMemory 需要和 OpenClaw 使用不同身份或不同认证策略时，才在 ogmemory.yaml 里单独覆盖。

deploy.env                    ogmemory.yaml
┌──────────────────┐          ┌────────────────────────┐
│ LLM_API_KEY=sk-xxx│──────→  │ api_key: "${LLM_API_KEY}" │
│ LLM_BASE_URL=... │──────→  │ base_url: "${LLM_BASE_URL}"│
│ LLM_MODEL=qwen3  │──────→  │ model: "${LLM_MODEL}"      │
│ OG_ROOT_API_KEY= │──────→  │ root_api_key: "${OG_ROOT...│
│ OG_ACCOUNT_ID=   │──────→  │ account_id: "${OG_ACCOUNT..│
│ ...              │          │ ...                      │
└──────────────────┘          └────────────────────────┘

共享配置：ogmemory.yaml 中写 ${LLM_API_KEY} 等占位符，自动使用 deploy.env 的值
oGMemory 专用：将 ${...} 替换为硬编码值即可覆盖

第一步：编辑 deploy.env

cd ogmem-deploy  # 或 cd oGMemory/deploy
vim deploy.env

第二步：创建 ogmemory.yaml

cp ogmemory.example.yaml ogmemory.yaml
vim ogmemory.yaml

💡 提示： 默认模板中 LLM/Embedding 配置已使用 ${...} 引用，大多数情况下只需修改 Embedding 模型名称和向量维度即可。

deploy.env 环境变量列表

💡 重要提示：

LLM_PROVIDER、LLM_API_KEY、LLM_BASE_URL、LLM_MODEL 这四个变量同时供 OpenClaw 和 oGMemory 使用（通过 ogmemory.yaml 中的 ${...} 引用）。如果 oGMemory 需要不同的配置，请在 ogmemory.yaml 中将对应字段改为硬编码值。

OPENCLAW_HOST_IP 建议填写宿主机实际 IP 地址（而非 127.0.0.1），以便其他机器或容器能够访问服务。

必填环境变量

变量名	说明	示例值	适用服务
`LLM_PROVIDER`	LLM 提供商标识	`dashscope`	OpenClaw + oGMemory 共用
`LLM_API_KEY`	LLM API 密钥	`sk-xxxxx`	OpenClaw + oGMemory 共用
`LLM_BASE_URL`	LLM API 基础地址	`https://dashscope.aliyuncs.com/compatible-mode/v1`	OpenClaw + oGMemory 共用
`LLM_MODEL`	LLM 模型名称	`qwen3.6-plus`	OpenClaw + oGMemory 共用
`ENABLE_OPENGAUSS`	是否启用 openGauss	`true` / `false`	openGauss
`OG_HOST_PORT`	openGauss 宿主机端口（启用 openGauss 时必填）	`15432`	openGauss
`OPENGAUSS_HOST_IP`	openGauss 数据库宿主机 IP 地址	`127.0.0.1`	openGauss
`OPENCLAW_HOST_IP`	OpenClaw 宿主机 IP 地址（建议填写宿主机实际 IP）	`192.168.1.100`	OpenClaw + oGMemory

可选环境变量 — OpenClaw 连接配置

变量名	说明	默认值	适用服务
`GATEWAY_PORT`	OpenClaw Gateway 端口	`18789`	OpenClaw
`OPENCLAW_GATEWAY_TOKEN`	前端配对密码	`ogmem-default-token`	OpenClaw
`OPENCLAW_BIND_MODE`	绑定模式（`lan` / `localhost`）	`lan`	OpenClaw
`OGMEM_URL`	oGMemory API 地址（供 OpenClaw 连接）	`http://127.0.0.1:8090`	OpenClaw
`OG_AUTH_API_KEY`	OpenClaw 连接 oGMemory 的认证 API Key	回退至 `OG_ROOT_API_KEY`	OpenClaw
`OG_AUTH_ACCOUNT_ID`	OpenClaw 连接 oGMemory 的账户 ID	回退至 `OG_ACCOUNT_ID`	OpenClaw

说明： 单实例模式默认不需要额外配置 OG_AUTH_API_KEY / OG_AUTH_ACCOUNT_ID，脚本会分别回退到 OG_ROOT_API_KEY / OG_ACCOUNT_ID。只有当 OpenClaw 需要使用不同于默认值的认证身份时，才建议单独覆盖。

可选环境变量 — 多租认证配置

启用多租认证后，所有数据路由和管理路由都需要 API Key 认证。启用后需要同时配置 OG_ROOT_API_KEY 或 OG_ADMIN_API_KEYS。

变量名	说明	默认值	适用服务
`OG_ROOT_API_KEY`	Root API Key（超级管理员密钥，拥有全局最高权限）	无	oGMemory
`OG_ADMIN_API_KEYS`	Admin API Keys（账户管理员密钥，逗号分隔）	无	oGMemory
`OG_ACCOUNT_ID`	默认租户标识，同时也是单实例模式下 OpenClaw 默认访问账户	`acct-demo`	oGMemory / OpenClaw
`OG_USER_ID`	默认用户标识	`u-alice`	oGMemory
`OG_AGENT_ID`	默认 Agent 标识	`main`	oGMemory

推荐： 单实例或共享默认身份场景下，只需要在 deploy.env 里配置一次 OG_ROOT_API_KEY、OG_ACCOUNT_ID、OG_USER_ID、OG_AGENT_ID；默认模板中的 ogmemory.yaml 会直接复用这些值。

OG_ADMIN_API_KEYS 格式说明：

绑定账户格式：account_id:key（只能管理指定账户）
全局格式：key（绑定到 OG_ACCOUNT_ID 对应的默认账户）
多个 key 用逗号分隔

# 示例：两个账户各一个 Admin Key
OG_ADMIN_API_KEYS="acct-company-a:admin-key-for-a,acct-company-b:admin-key-for-b"

# 示例：全局 Admin Key（绑定到 OG_ACCOUNT_ID）
OG_ADMIN_API_KEYS="global-admin-key"

OG_AUTH_API_KEY 说明：

默认使用 OG_ROOT_API_KEY（ROOT 权限，可访问所有账户数据）
也可设置为 Admin Key（限定账户权限），此时需填写 account_id:key 中的 key 部分
当 OG_AUTH_API_KEY 是 Admin Key 时，OG_AUTH_ACCOUNT_ID 必须与 Key 绑定的账户一致

可选环境变量 — 数据持久化配置

变量名	说明	默认值	适用服务
`AGFS_DATA_DIR`	AGFS 数据存储目录（持久化记忆文件）	无（不挂载）	oGMemory
`OPENCLAW_HOME_DIR`	OpenClaw 状态目录（避免重复配对）	无（不挂载）	OpenClaw

💡 推荐： 设置 AGFS_DATA_DIR 以持久化记忆数据，设置 OPENCLAW_HOME_DIR 以避免重复配对。

可选环境变量 — 容器配置

变量名	说明	默认值	适用服务
`OGMEM_CONTAINER_NAME`	ogmemory 容器名称	`ogmem`	容器
`OPENCLAW_CONTAINER_NAME`	openclaw-ogmemory 容器名称	`openclaw_ogmem`	容器
`OGMEM_IMAGE`	ogmemory 镜像地址	见 deploy.env	容器
`OPENCLAW_IMAGE`	openclaw-ogmemory 镜像地址	见 deploy.env	容器

可选环境变量 — openGauss 容器配置

变量名	说明	默认值	适用服务
`OG_CONTAINER_NAME`	openGauss 容器名称	`opengauss`	openGauss
`OG_PORT`	openGauss 容器内端口	`5432`	openGauss
`OG_NODE_NAME`	openGauss 节点名称	`gaussdb`	openGauss
`OG_USERNAME`	openGauss 用户名	`gaussdb`	openGauss
`OG_DB_NAME`	openGauss 数据库名	`postgres`	openGauss
`OG_IMAGE_REPO`	openGauss 镜像仓库	见 deploy.env	openGauss
`OG_IMAGE_TAG`	openGauss 镜像标签	`0328`	openGauss
`OG_CPUSET_CPUS`	CPU 亲和性	无	openGauss
`OG_WAIT_TIMEOUT`	启动超时时间（秒）	`120`	openGauss

可选环境变量 — 部署控制

变量名	说明	默认值	适用服务
`AUTO_HEALTH_CHECK`	是否自动健康检查	`true`	部署控制
`SKIP_PULL`	是否跳过镜像拉取	`false`	部署控制

ogmemory.yaml 配置字段

完整字段说明请参考 ogmemory.example.yaml 中的注释。

YAML 字段与环境变量的对应关系

下面这张表结合了 OGMEMORY_ENV.md 和当前代码默认值，方便直接查询字段映射、默认值和可选值。

YAML 字段	对应环境变量	默认值	常见可选值 / 格式	说明
`llm.provider`	`CONTEXTENGINE_PROVIDER`	代码默认 `mock`；部署时通常直接复用 `LLM_PROVIDER`	`mock` / `openai` / `openai-cached`，以及 `dashscope`、`volcengine`、`zhipu` 等兼容 OpenAI 协议的提供商标识	LLM 提供商
`llm.api_key`	`LLM_API_KEY`	空	API Key 字符串	部署模板通常复用 OpenClaw 的 `LLM_API_KEY`
`llm.base_url`	`LLM_BASE_URL`	空	兼容接口地址	部署模板通常复用 OpenClaw 的 `LLM_BASE_URL`
`llm.model`	`OGMEM_LLM_MODEL` 或模板中的 `LLM_MODEL`	`gpt-4o-mini`	任意可用模型名，如 `qwen3-max`、`gpt-4o-mini`、`glm-4.5`	部署模板默认直接引用 `LLM_MODEL`
`llm.temperature`	`LLM_TEMPERATURE`	`0.7`	通常 `0.0` 到 `2.0`	数值越低越稳定
`llm.max_tokens`	`LLM_MAX_TOKENS`	`4096`	正整数	单次生成最大 token 数
`embedding.provider`	`EMBEDDING_PROVIDER`	空，回退到 `llm.provider`	`openai` / `st` / `volcengine` / `mock`	Embedding 提供商
`embedding.model`	`OGMEM_EMBEDDING_MODEL`	`text-embedding-ada-002`	你的 Embedding 模型名，如 `text-embedding-v4`	需要和向量维度匹配
`embedding.base_url`	`OGMEM_EMBEDDING_BASE_URL`	空，回退到 `llm.base_url`	兼容接口地址	Embedding API 地址
`embedding.api_key`	`OGMEM_EMBEDDING_API_KEY`	空，回退到 `llm.api_key`	API Key 字符串	Embedding API Key
`embedding.multimodal`	`OGMEM_EMBEDDING_MULTIMODAL`	`false`	`true` / `false`	仅多模态 Embedding 端点时设为 `true`
`embedding.st_model`	`ST_MODEL`	`BAAI/bge-large-en-v1.5`	任意 Sentence Transformer 模型名	仅 `embedding.provider=st` 时通常有意义
`vector_db.type`	`VECTOR_DB_TYPE`	代码默认 `chroma`；部署模板默认写的是 `opengauss`	`memory` / `opengauss` / `chroma`	向量数据库类型
`vector_db.connection_string`	—	空	`host=... port=... dbname=... user=... password=...`	启用 openGauss 时由 `deploy.sh` 自动替换
`vector_db.dimension`	`OPENGAUSS_DIMENSION`	`1024`	正整数，如 `1024` / `1536` / `3072`	必须与 Embedding 模型维度一致
`vector_db.table_name`	`OPENGAUSS_TABLE_NAME`	`vector_index`	任意合法表名	openGauss 向量表名
`vector_db.pool_size`	`OPENGAUSS_POOL_SIZE`	`5`	正整数	openGauss 连接池大小
`vector_db.chroma_persist_dir`	`CHROMA_PERSIST_DIR`	`.chroma_data`	目录路径	使用 Chroma 持久化时生效
`vector_db.chroma_collection`	`CHROMA_COLLECTION`	`contextengine`	任意集合名	使用 Chroma 时生效
`service.http_port`	`OGMEM_HTTP_PORT`	`8090`	合法端口号	oGMemory HTTP 服务端口
`service.workers`	`OGMEM_WORKERS`	`2`	正整数	Gunicorn worker 数量
`service.http_ip_allowlist`	`OG_HTTP_IP_ALLOWLIST`	空	逗号分隔 IP / CIDR，例如 `127.0.0.1,10.0.0.0/8`	HTTP 白名单
`service.http_ip_allowlist_trust_proxy`	`OG_HTTP_IP_ALLOWLIST_TRUST_PROXY`	`false`	`true` / `false`	只有在反向代理前置时才建议开启
`service.http_trusted_proxies`	`OG_HTTP_TRUSTED_PROXIES`	空	逗号分隔 IP / CIDR	受信任代理列表
`agfs.base_url`	`AGFS_BASE_URL`	`http://127.0.0.1:1833`	URL	AGFS 服务地址
`agfs.mount_prefix`	`AGFS_MOUNT_PREFIX`	`/local`	路径前缀	AGFS 挂载前缀
`index.interval`	`INDEX_INTERVAL`	`30`	正整数，单位秒	索引轮询间隔
`index.workers`	`INDEX_WORKERS`	`1`	正整数	索引 worker 数量
`identity.account_id`	`OG_ACCOUNT_ID`	`acct-demo`	任意账户标识，如 `acct-company-a`	租户标识
`identity.user_id`	`OG_USER_ID`	`u-alice`	任意用户标识，如 `u-bob`	用户标识
`identity.agent_id`	`OG_AGENT_ID`	`main`	任意 Agent 标识，如 `shared-agent`	Agent 标识
`auth.role_control_enabled`	`OG_ROLE_CONTROL_ENABLED`	`false`	`true` / `false`	是否启用多租认证
`auth.root_api_key`	`OG_ROOT_API_KEY`	空	API Key 字符串	Root API Key
`auth.admin_api_keys`	`OG_ADMIN_API_KEYS`	空	`account_id:key` 或 `key`，多个值逗号分隔	Admin API Keys 列表
`sharing.agent_shared_mode`	`OG_AGENT_SHARED_MODE`	`off`	`off` / `user`	Agent 共享模式
`sharing.agent_shared_list`	`OG_AGENT_SHARED_LIST`	空	逗号分隔 Agent ID，例如 `shared-agent,agent-handbook`	共享 Agent ID 列表
`memory.after_turn_threshold`	`OGMEM_AFTER_TURN_THRESHOLD`	`200`	正整数	达到阈值后触发记忆提取
`memory.rolling_compress_enabled`	`OGMEM_ROLLING_COMPRESS_ENABLED`	`true`	`true` / `false`	是否启用滚动压缩
`memory.compact_prepare_token_ttl`	`OGMEM_COMPACT_PREPARE_TOKEN_TTL`	`300`	正整数，单位秒	prepare_compaction token 有效期
`memory.directory_summary_enabled`	`OGMEM_DIRECTORY_SUMMARY_ENABLED`	`false`	`true` / `false`	是否启用目录摘要
`memory.prefetch_enabled`	`OGMEM_PREFETCH_ENABLED`	`false`	`true` / `false`	是否启用 compose 前预取并填充 SessionTopicBuffer
`memory.prefetch_top_k`	`OGMEM_PREFETCH_TOP_K`	`5`	正整数	预取写入 pending_injection 的最大命中数
`memory.session_state_bridge_enabled`	`OGMEM_SESSION_STATE_BRIDGE_ENABLED`	`true`	`true` / `false`	是否将 SessionState 同步到 SessionWindowState
`memory.session_state_sync_interval_turns`	`OGMEM_SESSION_STATE_SYNC_INTERVAL_TURNS`	`1`	正整数	SessionState 版本变化后至少间隔多少用户轮次同步一次
`memory.topic_detection_enabled`	`OGMEM_TOPIC_DETECTION_ENABLED`	`false`	`true` / `false`	是否启用 P2 话题检测
`memory.compression_quality_enabled`	`OGMEM_COMPRESSION_QUALITY_ENABLED`	`false`	`true` / `false`	是否计算 P2 archive 压缩质量指标
`memory.compression_quality_persist_metadata`	`OGMEM_COMPRESSION_QUALITY_PERSIST_METADATA`	`false`	`true` / `false`	是否将压缩质量指标持久化到 archive metadata
`cache.enabled`	`OGMEM_CACHE_ENABLED`	`true`	`true` / `false`	是否启用缓存
`cache.max_size`	`OGMEM_CACHE_MAX_SIZE`	`1000`	正整数	缓存最大条目数

说明：

布尔值建议统一写成 true / false。

列表型变量通常使用逗号分隔。

如果某个字段已经在 ogmemory.yaml 中写死为硬编码值，则该字段优先级高于环境变量。

`${ENV_VAR}` 引用规则

${VAR_NAME} → 如果环境变量存在，替换为实际值
${VAR_NAME} → 如果环境变量不存在，保持原样（方便排查缺失配置）
非 ${...} 的硬编码值 → 不受影响，优先级最高

部署方式

方式一：完整部署（openGauss + ogmemory + openclaw-ogmemory）

适用于首次部署，需要向量数据库的场景。

bash deploy.sh -password <密码>

密码要求：

长度至少 8 个字符
包含大写字母、小写字母、数字、特殊符号(#?!@$%^&*)中的至少三种

示例：

bash deploy.sh -password "OpenGauss@2024"

方式二：仅部署服务（不使用 openGauss）

适用于已有外部数据库，或使用内存模式的场景。

修改配置文件：

ENABLE_OPENGAUSS="false"

执行部署：

bash deploy.sh

方式三：多租户部署

适用于多个租户共享同一套 oGMemory 服务，但各自拥有独立 OpenClaw Gateway 的场景。

在 ogmemory.yaml 中启用多租认证：

auth:
  role_control_enabled: true
  root_api_key: "${OG_ROOT_API_KEY}"
  admin_api_keys:
    - "acct-company-a:admin-key-for-a"
    - "acct-company-b:admin-key-for-b"

在 deploy.env 中配置认证 Key 和多租户 OpenClaw 实例：

OG_ROOT_API_KEY="root-secret-key-change-me"
OG_ADMIN_API_KEYS="acct-company-a:admin-key-for-a,acct-company-b:admin-key-for-b"

OPENCLAW_INSTANCES="openclaw_tenant_a|18789|tenant-a-web-token|admin-key-for-a|acct-company-a|/data/openclaw-a;openclaw_tenant_b|18790|tenant-b-web-token|admin-key-for-b|acct-company-b|/data/openclaw-b"

OPENCLAW_INSTANCES 格式说明：

container_name|gateway_port|gateway_token|auth_api_key|auth_account_id|openclaw_home_dir

各字段含义：

字段	说明
`container_name`	OpenClaw 容器名称
`gateway_port`	Gateway 端口
`gateway_token`	Web 界面配对密码
`auth_api_key`	连接 oGMemory 的 API Key（Admin Key 的 key 部分，或 Root Key）
`auth_account_id`	绑定的账户 ID
`openclaw_home_dir`	OpenClaw 状态持久化目录（可选，留空则不挂载）

多个实例用分号 ; 分隔。

说明： 配置了 OPENCLAW_INSTANCES 后，每个实例中的 auth_api_key / auth_account_id 优先级最高；单实例模式才会使用 OG_AUTH_API_KEY / OG_AUTH_ACCOUNT_ID 的默认回退逻辑。

执行部署：

bash deploy.sh -password <密码>

多租认证与 Agent 共享场景详解

核心概念

概念	说明
Account（账户）	数据隔离的最小单位，不同 Account 的记忆数据完全隔离
User（用户）	同一 Account 下的用户，数据共享
Agent（智能体）	同一 Account 下的 Agent，数据共享
Agent 共享	将指定 Agent 的记忆对同 Account 下所有 User 可见
Root API Key	超级管理员密钥，可访问所有 Account 的数据
Admin API Key	账户管理员密钥，只能访问绑定的 Account 数据

场景一：同 Account + 不同 User + Agent 共享

需求：一个公司（acct-company-a）有多个员工（u-alice、u-bob），他们共享同一个 Agent（shared-agent）的记忆，同时各自也有私有 Agent。

ogmemory.yaml 配置：

identity:
  account_id: "${OG_ACCOUNT_ID}"    # acct-company-a
  user_id: "${OG_USER_ID}"          # 默认用户，OpenClaw 可覆盖
  agent_id: "${OG_AGENT_ID}"        # 默认 Agent

auth:
  role_control_enabled: true
  root_api_key: "${OG_ROOT_API_KEY}"
  admin_api_keys:
    - "acct-company-a:admin-key-for-a"

sharing:
  agent_shared_mode: "user"          # 启用用户级共享
  agent_shared_list:
    - "shared-agent"                 # shared-agent 对所有 MEMBER 用户可见

deploy.env 配置：

# 共享 LLM 配置
LLM_PROVIDER="dashscope"
LLM_API_KEY="sk-xxxxx"
LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
LLM_MODEL="qwen3-max"

# 多租认证
OG_ROOT_API_KEY="root-secret-key-change-me"
OG_ACCOUNT_ID="acct-company-a"
OG_USER_ID="u-alice"
OG_AGENT_ID="main"

# 两个员工各一个 OpenClaw Gateway，共享同一个 Account
OPENCLAW_INSTANCES="openclaw_alice|18789|alice-web-token|admin-key-for-a|acct-company-a|/data/openclaw-alice;openclaw_bob|18790|bob-web-token|admin-key-for-a|acct-company-a|/data/openclaw-bob"

数据隔离效果：

用户	可见的 Agent	可见的记忆
u-alice（通过 openclaw_alice）	`main`（私有）+ `shared-agent`（共享）	自己的 + 共享的
u-bob（通过 openclaw_bob）	`main`（私有）+ `shared-agent`（共享）	自己的 + 共享的

说明： 两个 OpenClaw Gateway 使用同一个 Admin Key（admin-key-for-a）和同一个 Account（acct-company-a），但各自以不同 User 身份访问 oGMemory。shared-agent 的记忆对两个用户都可见，而各自的 main Agent 记忆互相隔离。

场景二：不同 Account + Agent 共享

需求：两个公司（acct-company-a、acct-company-b）各自独立，数据完全隔离，每个公司有自己的 Admin Key。

ogmemory.yaml 配置：

identity:
  account_id: "${OG_ACCOUNT_ID}"
  user_id: "${OG_USER_ID}"
  agent_id: "${OG_AGENT_ID}"

auth:
  role_control_enabled: true
  root_api_key: "${OG_ROOT_API_KEY}"
  admin_api_keys:
    - "acct-company-a:admin-key-for-a"
    - "acct-company-b:admin-key-for-b"

sharing:
  agent_shared_mode: "user"
  agent_shared_list:
    - "shared-agent"

deploy.env 配置：

LLM_PROVIDER="dashscope"
LLM_API_KEY="sk-xxxxx"
LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
LLM_MODEL="qwen3-max"

OG_ROOT_API_KEY="root-secret-key-change-me"
OG_ACCOUNT_ID="acct-company-a"
OG_USER_ID="u-alice"
OG_AGENT_ID="main"

# 两个公司各一个 OpenClaw Gateway，各自使用自己的 Admin Key
OPENCLAW_INSTANCES="openclaw_company_a|18789|company-a-web-token|admin-key-for-a|acct-company-a|/data/openclaw-a;openclaw_company_b|18790|company-b-web-token|admin-key-for-b|acct-company-b|/data/openclaw-b"

数据隔离效果：

公司	OpenClaw	认证	可见数据
acct-company-a	openclaw_company_a:18789	admin-key-for-a	仅 company-a 的记忆
acct-company-b	openclaw_company_b:18790	admin-key-for-b	仅 company-b 的记忆

说明： 两个公司使用不同的 Admin Key 和不同的 Account，数据完全隔离。每个公司内部的 shared-agent 仅对本公司的用户可见。

场景三：单租户（无认证，最简配置）

需求：个人使用或内网环境，不需要多租隔离。

ogmemory.yaml 配置：

identity:
  account_id: "acct-demo"
  user_id: "u-alice"
  agent_id: "main"

auth:
  role_control_enabled: false

sharing:
  agent_shared_mode: "off"

deploy.env 配置：

LLM_PROVIDER="dashscope"
LLM_API_KEY="sk-xxxxx"
LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
LLM_MODEL="qwen3-max"

说明： 无认证模式下，所有请求默认使用 identity 中配置的账户，无需 API Key。

关于 `openclaw.json` 的自动迁移

如果设置了 OPENCLAW_HOME_DIR，openclaw.json 会持久化保存。当前版本的容器入口脚本会这样处理：

如果 openclaw.json 不存在，按当前模板直接生成。
如果文件中仍残留模板占位符，也会自动重建。
如果文件缺少关键字段，例如 authApiKey、authAccountId，会先备份旧文件，再按当前模板重建。
自动备份最多保留最近 3 份，超过后会清理更旧的备份。

备份文件名示例：

openclaw.json.bak.20260420-101530

如果你曾手工修改过 openclaw.json，升级后请优先对比备份文件，再决定是否手工迁移你的自定义内容。

配置修改与生效

修改 oGMemory 配置

编辑 deploy/ogmemory.yaml
重启容器：

docker restart ogmem

💡 提示： ogmemory.yaml 直接挂载到容器中（只读），容器启动时 entrypoint 会自动完成 ${...} 替换和 openGauss 连接信息替换。修改后只需 docker restart 即可生效，无需重新运行 deploy.sh。

修改 OpenClaw 或基础设施配置

编辑 deploy/deploy.env
重新部署：

bash deploy.sh

说明： 如果只修改了 OG_AUTH_API_KEY、OG_AUTH_ACCOUNT_ID、OG_ROOT_API_KEY、OG_ACCOUNT_ID 这类 OpenClaw 连接参数，也建议重新执行 bash deploy.sh，让容器以新的环境变量启动，并在需要时触发 openclaw.json 自动迁移。

配置生效流程

ogmemory.yaml (用户编辑)
    │
    ▼ docker run -v ogmemory.yaml:/etc/ogmem/config.yaml:ro
    │
    ▼ 容器 entrypoint 自动执行：
    │   1. 读取 /etc/ogmem/config.yaml
    │   2. 替换 ${LLM_API_KEY} 等环境变量引用
    │   3. 替换 vector_db.connection_string（如有 OPENGAUSS_* 环境变量）
    │   4. 写入 /tmp/ogmem.resolved.yaml
    │   5. 设置 OGMEM_CONFIG=/tmp/ogmem.resolved.yaml
    │   6. 启动应用
    │
    ▼ 应用读取 /tmp/ogmem.resolved.yaml

部署过程说明

部署脚本会依次执行以下步骤：

前置检查: 检查 Docker 环境
拉取镜像: 从华为云 SWR 拉取所需镜像
部署 openGauss: 启动数据库容器（如启用）
等待数据库就绪: 最长等待 120 秒
部署 oGMemory: 挂载 ogmemory.yaml，传入环境变量，启动容器
部署 OpenClaw Gateway: 启动 Web 服务（单实例或多实例）
健康检查: 验证服务是否正常

常用命令

查看部署状态

bash deploy.sh --status

--status 只查看当前目录下这份 deploy.env 解析出来的容器名，不会再按全局标签扫描同机上的其它部署实例。

清理部署

bash deploy.sh --cleanup

--cleanup 只会删除当前目录下这份 deploy.env 中声明的容器名，例如 OG_CONTAINER_NAME、OGMEM_CONTAINER_NAME 和 OPENCLAW_INSTANCES / OPENCLAW_CONTAINER_NAME 对应的容器。这样同一台机器上可以并存多套部署；在某一套目录里执行 cleanup，不会误删另一套环境的容器。数据仍会保留在你配置的持久化目录中。这里说的“所有容器”是指当前这份 deploy.env 对应的全部容器，不是宿主机上所有带 ogmem.managed=true 标签的容器。

注意：此命令会停止并删除所有容器，数据不会丢失（如果配置了持久化目录）

查看日志

# 查看 oGMemory 日志
docker logs ogmem -f

# 查看 OpenClaw 日志
docker logs openclaw_ogmem -f

# 查看 openGauss 日志
docker logs opengauss -f

重启服务

# 重启所有服务
docker restart ogmem openclaw_ogmem

# 重启单个服务
docker restart ogmem

进入容器

# 进入 oGMemory 容器
docker exec -it ogmem bash

# 进入 openGauss 容器
docker exec -it opengauss bash

健康检查

# 检查 oGMemory 服务
curl http://<OPENCLAW_HOST_IP>:8090/api/v1/health

# 检查 OpenClaw 服务
curl http://<OPENCLAW_HOST_IP>:18789/health

查看 OpenClaw 当前配置及备份

ls -lt <OPENCLAW_HOME_DIR>/openclaw.json*

访问服务

部署成功后，通过以下地址访问：

单租户模式

服务	地址	说明
OpenClaw Web	http://<OPENCLAW_HOST_IP>:18789	Web 界面入口
oGMemory API	http://<OPENCLAW_HOST_IP>:8090	HTTP API
openGauss	<OPENGAUSS_HOST_IP>:15432	数据库连接

多租户模式

每个租户拥有独立的 OpenClaw Gateway 端口：

租户	OpenClaw Web	绑定账户
租户 A	http://<OPENCLAW_HOST_IP>:18789	acct-company-a
租户 B	http://<OPENCLAW_HOST_IP>:18790	acct-company-b

首次访问

进入 openclaw 容器内
输入 openclaw tui 进行交互对话

文件说明

deploy/
├── README.md                # 本文档
├── install.sh               # 一键安装脚本（下载部署文件）
├── deploy.sh                # 部署执行脚本
├── deploy.env               # OpenClaw + 基础设施配置
├── ogmemory.example.yaml    # oGMemory 配置模板（复制为 ogmemory.yaml 后编辑）
└── ogmemory.yaml            # oGMemory 实际配置（用户创建，不纳入版本控制）

OpenClaw + oGMemory 一键安装部署指南

概述

环境要求

系统要求

软件要求

网络要求

快速开始

远程一键安装

配置说明

配置文件结构

第一步：编辑 deploy.env

第二步：创建 ogmemory.yaml

deploy.env 环境变量列表

必填环境变量

可选环境变量 — OpenClaw 连接配置

可选环境变量 — 多租认证配置

可选环境变量 — 数据持久化配置

可选环境变量 — 容器配置

可选环境变量 — openGauss 容器配置

可选环境变量 — 部署控制

ogmemory.yaml 配置字段

YAML 字段与环境变量的对应关系

${ENV_VAR} 引用规则

推荐的去冗余写法

部署方式

方式一：完整部署（openGauss + ogmemory + openclaw-ogmemory）

方式二：仅部署服务（不使用 openGauss）

方式三：多租户部署

多租认证与 Agent 共享场景详解

核心概念

场景一：同 Account + 不同 User + Agent 共享

场景二：不同 Account + Agent 共享

场景三：单租户（无认证，最简配置）

关于 openclaw.json 的自动迁移

配置修改与生效

修改 oGMemory 配置

修改 OpenClaw 或基础设施配置

配置生效流程

部署过程说明

常用命令

查看部署状态

清理部署

查看日志

重启服务

进入容器

健康检查

查看 OpenClaw 当前配置及备份

访问服务

单租户模式

多租户模式

首次访问

文件说明

`${ENV_VAR}` 引用规则

关于 `openclaw.json` 的自动迁移