oGMemory 配置指南

本页按安装方式说明配置文件怎么生成、生成到哪里、核心内容是什么。

完整字段参考：config/ogmem.reference.yaml 和 OGMEMORY_ENV.md。

一、配置入口

交互式向导是最推荐的配置方式：

bash

ogmem onboard

向导会依次询问模型、Embedding、数据库、部署方式，然后按选择生成对应文件。

安装方式	适合场景	交互式生成文件
Headless 本地服务	只启动 oGMemory HTTP 服务，供 SDK、脚本或已有系统调用	`config/ogmem.yaml`
Agent Plugin	接入本机已有 OpenClaw 或 Claude Code	`config/ogmem.yaml`，以及 `openclaw.plugin.json` 或 `.claude/settings.json`
Docker 一体化部署	一次部署 OpenClaw Gateway、oGMemory、可选 openGauss	`deploy/deploy.env`、`deploy/ogmemory.yaml`

ogmem.yaml 默认生成在项目根目录的 config/ogmem.yaml。如果需要放到其他路径，可以用 OGMEM_CONFIG=/path/to/ogmem.yaml 指定。

二、Headless 本地服务

选择 Headless (CE server only) 后，向导会生成：

text

config/ogmem.yaml

典型内容如下：

yaml

# Generated by ogmem onboard
paths:
  data_root: .ogmem_data       # 本地数据目录，用于保存运行时数据和本地索引

llm:
  provider: openai             # LLM 提供商：openai / volcengine / dashscope / zhipu / mock
  api_key: "sk-xxx"            # LLM API Key；也可用 OGMEM_API_KEY 覆盖
  base_url: "https://api.openai.com/v1" # OpenAI 兼容接口地址；国内模型可替换为对应 Base URL
  model: "gpt-4o-mini"         # 语义抽取、分类等任务使用的 LLM 模型
  temperature: 0.1             # 生成随机性；记忆抽取建议保持较低

embedding:
  provider: openai             # Embedding 提供商；通常和 llm.provider 保持一致
  model: "text-embedding-ada-002" # 向量化模型，需和 vector_db.dimension 匹配

storage:
  backend: sql                 # 记忆存储后端：sql / agfs；推荐使用 sql
  connection_string: "host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres" # PostgreSQL DSN
  pool_size: 5                 # 数据库连接池大小

vector_db:
  type: chroma                 # 向量索引后端；本地默认可用 chroma
  dimension: 1536              # Embedding 向量维度，必须和模型输出一致
  chroma_persist_dir: .ogmem_data/chroma # Chroma 本地持久化目录

service:
  http_port: 8090              # oGMemory HTTP 服务端口
  workers: 2                   # HTTP 服务 worker 数

identity:
  account_id: "acct-demo"      # 默认账户 ID，用于多租户隔离
  user_id: "u-alice"           # 默认用户 ID
  agent_id: "main"             # 默认 Agent ID

启动：

bash

ogmem start headless

这里需要重点确认三类配置：LLM 能访问、Embedding 维度和模型匹配、storage.connection_string 能连接到 PostgreSQL。

三、Agent Plugin

选择 Agent Plugin (OpenClaw / Claude Code) 后，向导会先生成 oGMemory 自身配置：

text

config/ogmem.yaml

内容会比 Headless 多一个 plugin 段：

yaml

llm:
  provider: openai             # LLM 提供商
  api_key: "sk-xxx"            # LLM API Key
  base_url: "https://api.openai.com/v1" # OpenAI 兼容接口地址
  model: "gpt-4o-mini"         # LLM 模型名
  temperature: 0.1             # 记忆抽取建议使用较低温度

embedding:
  provider: openai             # Embedding 提供商
  model: "text-embedding-ada-002" # Embedding 模型名

storage:
  backend: sql                 # 记忆存储后端：sql / agfs
  connection_string: "host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres" # PostgreSQL DSN
  pool_size: 5                 # 数据库连接池大小

vector_db:
  type: chroma                 # 向量索引后端
  dimension: 1536              # 向量维度，需和 Embedding 模型一致
  chroma_persist_dir: .ogmem_data/chroma # Chroma 本地索引目录

service:
  http_port: 8090              # oGMemory HTTP 服务端口
  workers: 2                   # HTTP 服务 worker 数

identity:
  account_id: "acct-demo"      # 默认账户 ID
  user_id: "u-alice"           # 默认用户 ID
  agent_id: "main"             # 默认 Agent ID

plugin:
  type: "openclaw"             # Agent 接入类型：openclaw 或 claude_hooks
  openclaw_config: "D:/path/to/project/openclaw.plugin.json" # OpenClaw Gateway 配置文件路径

如果选择 OpenClaw，还会生成：

text

openclaw.plugin.json

核心作用是把 OpenClaw Gateway 的模型配置和 oGMemory 地址连起来。实际文件会包含 OpenClaw 所需的完整 schema，可以重点检查这些字段：

json

{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-xxx",
  "ogmem_url": "http://127.0.0.1:8090",
  "gateway_port": "18789"
}

如果选择 Claude Code，向导会把 hooks 写入：

text

.claude/settings.json

启动：

bash

ogmem start plugin

注意：plugin 模式不会替你安装 OpenClaw 或 Claude Code 本体。它只生成 oGMemory 配置和 Agent 侧接入配置；OpenClaw / Claude Code 需要用户本机已经可用。

四、Docker 一体化部署

选择 Docker (containerized) 后，向导会生成两类文件：

text

deploy/deploy.env
deploy/ogmemory.yaml

deploy/deploy.env 负责容器部署和共享环境变量，典型内容如下：

bash

# Generated by ogmem onboard
LLM_PROVIDER="openai"
LLM_API_KEY="sk-xxx"
LLM_BASE_URL="https://api.openai.com/v1"
LLM_MODEL="gpt-4o-mini"

ENABLE_OPENGAUSS="true"
OG_HOST_PORT="15432"
OPENGAUSS_HOST_IP="127.0.0.1"

deploy/ogmemory.yaml 是容器内 oGMemory 使用的配置，里面会引用 deploy.env：

yaml

# Generated by ogmem onboard (Docker mode)
llm:
  provider: "${LLM_PROVIDER}"  # 从 deploy.env 读取 LLM 提供商
  api_key: "${LLM_API_KEY}"    # 从 deploy.env 读取 LLM API Key
  base_url: "${LLM_BASE_URL}"  # 从 deploy.env 读取模型服务 Base URL
  model: "${LLM_MODEL}"        # 从 deploy.env 读取 LLM 模型名
  temperature: 0.1             # 记忆抽取建议使用较低温度

embedding:
  provider: openai             # Embedding 提供商
  model: "text-embedding-ada-002" # Embedding 模型名
  base_url: "${LLM_BASE_URL}"  # 默认复用 LLM Base URL
  api_key: "${LLM_API_KEY}"    # 默认复用 LLM API Key

vector_db:
  type: opengauss              # Docker 场景常用 openGauss / pgvector
  connection_string: "host=127.0.0.1 port=8799 dbname=postgres user=gaussdb password=CHANGE_ME" # 向量库连接串
  dimension: 1536              # 向量维度，需和 Embedding 模型一致
  table_name: vector_index     # 向量索引表名
  pool_size: 5                 # 向量库连接池大小

storage:
  backend: sql                 # 记忆结构化数据存储后端：sql / agfs

agfs:
  base_url: "http://127.0.0.1:1833" # AGFS 服务地址
  mount_prefix: /local/plugin  # AGFS 挂载前缀

index:
  interval: 15                 # 后台索引任务轮询间隔，单位秒
  workers: 1                   # 后台索引 worker 数

service:
  http_port: 8090              # 容器内 oGMemory HTTP 服务端口
  workers: 2                   # HTTP 服务 worker 数

identity:
  account_id: "acct-demo"      # 默认账户 ID
  user_id: "u-alice"           # 默认用户 ID
  agent_id: "main"             # 默认 Agent ID

交互式 ogmem onboard --mode docker 会询问是否立即启动容器；选择 yes 时会调用 deploy/deploy.sh。如果只是生成配置，也可以之后手动启动：

bash

bash deploy/deploy.sh -password "OpenGauss@2024"

五、存储和向量索引

安装方式决定服务怎么启动，存储后端决定记忆怎么落盘。STORAGE_BACKEND / storage.backend 支持两个值：

值	说明	何时使用
`sql`	使用 PostgreSQL 直连存储记忆数据	推荐默认选择，适合本地开发、服务部署和排障
`agfs`	使用 AGFS 文件系统链路存储记忆数据	需要 AGFS 能力或兼容旧链路时使用

当前推荐默认使用 SQL：

yaml

storage:
  backend: sql                 # 推荐的记忆存储后端；可选值：sql / agfs
  connection_string: "host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres" # PostgreSQL DSN

向量索引可以选择本地 Chroma：

yaml

vector_db:
  type: chroma                 # 本地 Chroma 向量索引
  dimension: 1536              # 向量维度，需和 Embedding 模型一致
  chroma_persist_dir: .ogmem_data/chroma # 本地索引持久化目录

也可以选择 openGauss / pgvector：

yaml

vector_db:
  type: opengauss              # 使用 openGauss / pgvector 作为向量索引
  connection_string: "host=127.0.0.1 port=5432 dbname=postgres user=gaussdb password=CHANGE_ME" # openGauss 连接串
  dimension: 1024              # 向量维度，需和 Embedding 模型一致

dimension 必须和 Embedding 模型输出维度一致。

六、主要环境变量

一般优先改 YAML；环境变量适合临时覆盖、容器部署或 CI。完整列表见 OGMEMORY_ENV.md。

变量	默认值	说明
`OGMEM_API_KEY`	无	LLM API 密钥，OpenAI 兼容接口可直接使用
`OGMEM_BASE_URL`	无	自定义 LLM API 基础 URL
`OGMEM_LLM_MODEL`	`gpt-4o-mini`	抽取、分类等语义处理使用的 LLM 模型
`OGMEM_EMBEDDING_MODEL`	`text-embedding-ada-002`	向量索引使用的 Embedding 模型
`OGMEM_EMBEDDING_API_KEY`	回退到 `OGMEM_API_KEY`	Embedding 独立 API Key
`VECTOR_DB_TYPE`	`chroma`	向量后端：`chroma` / `memory` / `opengauss`
`STORAGE_BACKEND`	`sql`	存储后端：`sql` / `agfs`，推荐 `sql`
`SQL_CONNECTION_STRING`	无	PostgreSQL DSN，例如 `host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres`
`OGMEM_HTTP_PORT`	`8090`	HTTP 服务监听端口
`OGMEM_CONFIG`	`config/ogmem.yaml`	YAML 配置文件路径

配置优先级：

text

命令行显式传入 > YAML 配置 > 环境变量 > 代码默认值

七、自检

查看当前配置：

bash

ogmem config show

检查依赖和服务：

bash

ogmem check
curl http://127.0.0.1:8090/api/v1/health

文档	说明
config/ogmem.reference.yaml	完整 YAML 模板
OGMEMORY_ENV.md	完整环境变量说明
deploy/README.md	Docker 一体化部署
openclaw_context_engine_plugin/ENV.md	OpenClaw 插件变量

oGMemory 配置指南 ​

一、配置入口 ​

二、Headless 本地服务 ​

三、Agent Plugin ​

四、Docker 一体化部署 ​

五、存储和向量索引 ​

六、主要环境变量 ​

七、自检 ​

相关文档 ​

oGMemory 配置指南

一、配置入口

二、Headless 本地服务

三、Agent Plugin

四、Docker 一体化部署

五、存储和向量索引

六、主要环境变量

七、自检

相关文档