Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Halaman ini mencantumkan setiap pengaturan konfigurasi untuk pencarian memori OpenClaw. Untuk ikhtisar konseptual, lihat:

Ikhtisar memori

Cara kerja memori.

Mesin bawaan

Backend SQLite default.

Mesin QMD

Sidecar yang mengutamakan lokal.

Pencarian memori

Pipeline pencarian dan penyetelan.

Active Memory

Sub-agen memori untuk sesi interaktif.
Semua pengaturan pencarian memori berada di bawah agents.defaults.memorySearch dalam openclaw.json kecuali dinyatakan lain.
Jika Anda mencari toggle fitur Active Memory dan konfigurasi sub-agen, itu berada di bawah plugins.entries.active-memory, bukan memorySearch.Active Memory menggunakan model dua gerbang:
  1. Plugin harus diaktifkan dan menargetkan id agen saat ini
  2. Permintaan harus berupa sesi obrolan persisten interaktif yang memenuhi syarat
Lihat Active Memory untuk model aktivasi, konfigurasi milik Plugin, persistensi transkrip, dan pola rollout yang aman.

Pemilihan penyedia

KunciTipeDefaultDeskripsi
providerstringterdeteksi otomatisID adaptor embedding seperti bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai, atau voyage; juga dapat berupa models.providers.<id> yang dikonfigurasi dengan api mengarah ke salah satu adaptor tersebut
modelstringdefault penyediaNama model embedding
fallbackstring"none"ID adaptor fallback saat yang utama gagal
enabledbooleantrueAktifkan atau nonaktifkan pencarian memori

Urutan deteksi otomatis

Saat provider tidak ditetapkan, OpenClaw memilih yang pertama tersedia:
1

local

Dipilih jika memorySearch.local.modelPath dikonfigurasi dan file tersebut ada.
2

github-copilot

Dipilih jika token GitHub Copilot dapat diselesaikan (env var atau profil auth).
3

openai

Dipilih jika kunci OpenAI dapat diselesaikan.
4

gemini

Dipilih jika kunci Gemini dapat diselesaikan.
5

voyage

Dipilih jika kunci Voyage dapat diselesaikan.
6

mistral

Dipilih jika kunci Mistral dapat diselesaikan.
7

deepinfra

Dipilih jika kunci DeepInfra dapat diselesaikan.
8

bedrock

Dipilih jika rantai kredensial AWS SDK berhasil diselesaikan (peran instance, kunci akses, profil, SSO, identitas web, atau konfigurasi bersama).
ollama didukung tetapi tidak terdeteksi otomatis (tetapkan secara eksplisit).

ID penyedia khusus

memorySearch.provider dapat mengarah ke entri khusus models.providers.<id>. OpenClaw menyelesaikan pemilik api penyedia tersebut untuk adaptor embedding sambil mempertahankan id penyedia khusus untuk endpoint, auth, dan penanganan prefiks model. Ini memungkinkan penyiapan multi-GPU atau multi-host mendedikasikan embedding memori ke endpoint lokal tertentu:
{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

Resolusi kunci API

Embedding jarak jauh memerlukan kunci API. Bedrock menggunakan rantai kredensial default AWS SDK sebagai gantinya (peran instance, SSO, kunci akses).
PenyediaEnv varKunci konfigurasi
BedrockRantai kredensial AWSTidak perlu kunci API
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENProfil auth melalui login perangkat
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (placeholder)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
OAuth Codex hanya mencakup chat/completions dan tidak memenuhi permintaan embedding.

Konfigurasi endpoint jarak jauh

Untuk endpoint khusus yang kompatibel dengan OpenAI atau menimpa default penyedia:
remote.baseUrl
string
URL dasar API khusus.
remote.apiKey
string
Timpa kunci API.
remote.headers
object
Header HTTP tambahan (digabungkan dengan default penyedia).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Konfigurasi khusus penyedia

KunciTipeDefaultDeskripsi
modelstringgemini-embedding-001Juga mendukung gemini-embedding-2-preview
outputDimensionalitynumber3072Untuk Embedding 2: 768, 1536, atau 3072
Mengubah model atau outputDimensionality memicu reindeks penuh otomatis.
Endpoint embedding yang kompatibel dengan OpenAI dapat ikut menggunakan field permintaan input_type khusus penyedia. Ini berguna untuk model embedding asimetris yang memerlukan label berbeda untuk embedding kueri dan dokumen.
KunciTipeDefaultDeskripsi
inputTypestringtidak ditetapkaninput_type bersama untuk embedding kueri dan dokumen
queryInputTypestringtidak ditetapkaninput_type saat kueri; menimpa inputType
documentInputTypestringtidak ditetapkaninput_type indeks/dokumen; menimpa inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
Mengubah nilai-nilai ini memengaruhi identitas cache embedding untuk pengindeksan batch penyedia dan sebaiknya diikuti dengan reindeks memori saat model upstream memperlakukan label tersebut secara berbeda.

Konfigurasi embedding Bedrock

Bedrock menggunakan rantai kredensial default AWS SDK — tidak perlu kunci API. Jika OpenClaw berjalan di EC2 dengan peran instance yang mengaktifkan Bedrock, cukup tetapkan penyedia dan model:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
KunciTipeDefaultDeskripsi
modelstringamazon.titan-embed-text-v2:0ID model embedding Bedrock apa pun
outputDimensionalitynumberdefault modelUntuk Titan V2: 256, 512, atau 1024
Model yang didukung (dengan deteksi keluarga dan default dimensi):
ID ModelPenyediaDimensi DefaultDimensi yang Dapat Dikonfigurasi
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
Varian bersufiks throughput (misalnya, amazon.titan-embed-text-v1:2:8k) mewarisi konfigurasi model dasar.Autentikasi: auth Bedrock menggunakan urutan resolusi kredensial AWS SDK standar:
  1. Variabel lingkungan (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. Cache token SSO
  3. Kredensial token identitas web
  4. Kredensial bersama dan file konfigurasi
  5. Kredensial metadata ECS atau EC2
Region diselesaikan dari AWS_REGION, AWS_DEFAULT_REGION, baseUrl penyedia amazon-bedrock, atau default ke us-east-1.Izin IAM: peran atau pengguna IAM memerlukan:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Untuk hak akses minimum, batasi cakupan InvokeModel ke model tertentu:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
KunciTipeBawaanDeskripsi
local.modelPathstringdiunduh otomatisPath ke file model GGUF
local.modelCacheDirstringbawaan node-llama-cppDirektori cache untuk model yang diunduh
local.contextSizenumber | "auto"4096Ukuran jendela konteks untuk konteks embedding. 4096 mencakup chunk umum (128–512 token) sekaligus membatasi VRAM non-weight. Turunkan ke 1024–2048 pada host terbatas. "auto" memakai maksimum terlatih model — tidak direkomendasikan untuk model 8B+ (Qwen3-Embedding-8B: 40 960 token → ~32 GB VRAM vs ~8,8 GB pada 4096).
Model bawaan: embeddinggemma-300m-qat-Q8_0.gguf (~0,6 GB, diunduh otomatis). Checkout sumber tetap memerlukan persetujuan build native: pnpm approve-builds lalu pnpm rebuild node-llama-cpp.Gunakan CLI mandiri untuk memverifikasi path penyedia yang sama dengan yang digunakan Gateway:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Jika provider adalah auto, local dipilih hanya ketika local.modelPath mengarah ke file lokal yang sudah ada. Referensi model hf: dan HTTP(S) masih dapat digunakan secara eksplisit dengan provider: "local", tetapi referensi tersebut tidak membuat auto memilih lokal sebelum model tersedia di disk.

Timeout embedding inline

sync.embeddingBatchTimeoutSeconds
number
Timpa timeout untuk batch embedding inline selama pengindeksan memori.Jika tidak disetel, gunakan bawaan penyedia: 600 detik untuk penyedia lokal/self-hosted seperti local, ollama, dan lmstudio, serta 120 detik untuk penyedia hosted. Tingkatkan ini ketika batch embedding lokal yang terikat CPU berjalan sehat tetapi lambat.

Konfigurasi pencarian hibrida

Semuanya berada di bawah memorySearch.query.hybrid:
KunciTipeBawaanDeskripsi
enabledbooleantrueAktifkan pencarian hibrida BM25 + vektor
vectorWeightnumber0.7Bobot untuk skor vektor (0-1)
textWeightnumber0.3Bobot untuk skor BM25 (0-1)
candidateMultipliernumber4Pengali ukuran kumpulan kandidat
KunciTipeBawaanDeskripsi
mmr.enabledbooleanfalseAktifkan pemeringkatan ulang MMR
mmr.lambdanumber0.70 = keragaman maks, 1 = relevansi maks

Contoh lengkap

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

Path memori tambahan

KunciTipeDeskripsi
extraPathsstring[]Direktori atau file tambahan untuk diindeks
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
Path dapat berupa absolut atau relatif terhadap workspace. Direktori dipindai secara rekursif untuk file .md. Penanganan symlink bergantung pada backend aktif: engine bawaan mengabaikan symlink, sedangkan QMD mengikuti perilaku pemindai QMD yang mendasarinya. Untuk pencarian transkrip lintas agen yang tercakup per agen, gunakan agents.list[].memorySearch.qmd.extraCollections alih-alih memory.qmd.paths. Koleksi tambahan tersebut mengikuti bentuk { path, name, pattern? } yang sama, tetapi digabungkan per agen dan dapat mempertahankan nama bersama eksplisit ketika path mengarah ke luar workspace saat ini. Jika path hasil resolusi yang sama muncul di memory.qmd.paths dan memorySearch.qmd.extraCollections, QMD mempertahankan entri pertama dan melewati duplikatnya.

Memori multimodal (Gemini)

Indeks gambar dan audio bersama Markdown menggunakan Gemini Embedding 2:
KunciTipeBawaanDeskripsi
multimodal.enabledbooleanfalseAktifkan pengindeksan multimodal
multimodal.modalitiesstring[]["image"], ["audio"], atau ["all"]
multimodal.maxFileBytesnumber10000000Ukuran file maks untuk pengindeksan
Hanya berlaku untuk file di extraPaths. Root memori default tetap hanya Markdown. Memerlukan gemini-embedding-2-preview. fallback harus berupa "none".
Format yang didukung: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (gambar); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Cache embedding

KeyTypeDefaultDescription
cache.enabledbooleanfalseSimpan embedding chunk di SQLite
cache.maxEntriesnumber50000Maksimum embedding yang di-cache
Mencegah embedding ulang teks yang tidak berubah selama pengindeksan ulang atau pembaruan transkrip.

Pengindeksan batch

KeyTypeDefaultDescription
remote.nonBatchConcurrencynumber4Embedding inline paralel
remote.batch.enabledbooleanfalseAktifkan API embedding batch
remote.batch.concurrencynumber2Job batch paralel
remote.batch.waitbooleantrueTunggu penyelesaian batch
remote.batch.pollIntervalMsnumberInterval polling
remote.batch.timeoutMinutesnumberTimeout batch
Tersedia untuk openai, gemini, dan voyage. Batch OpenAI biasanya paling cepat dan paling murah untuk backfill besar. remote.nonBatchConcurrency mengontrol panggilan embedding inline yang digunakan oleh penyedia lokal/self-hosted dan penyedia hosted saat API batch penyedia tidak aktif. Ollama secara default menggunakan 1 untuk pengindeksan non-batch agar tidak membebani host lokal yang lebih kecil; tetapkan nilai lebih tinggi pada mesin yang lebih besar. Ini terpisah dari sync.embeddingBatchTimeoutSeconds, yang mengontrol timeout untuk panggilan embedding inline.

Pencarian memori sesi (eksperimental)

Indeks transkrip sesi dan tampilkan melalui memory_search:
KeyTypeDefaultDescription
experimental.sessionMemorybooleanfalseAktifkan pengindeksan sesi
sourcesstring[]["memory"]Tambahkan "sessions" untuk menyertakan transkrip
sync.sessions.deltaBytesnumber100000Ambang byte untuk pengindeksan ulang
sync.sessions.deltaMessagesnumber50Ambang pesan untuk pengindeksan ulang
Pengindeksan sesi bersifat opt-in dan berjalan secara asinkron. Hasil dapat sedikit kedaluwarsa. Log sesi berada di disk, jadi perlakukan akses sistem file sebagai batas kepercayaan.

Akselerasi vektor SQLite (sqlite-vec)

KeyTypeDefaultDescription
store.vector.enabledbooleantrueGunakan sqlite-vec untuk kueri vektor
store.vector.extensionPathstringbundledTimpa path sqlite-vec
Saat sqlite-vec tidak tersedia, OpenClaw secara otomatis beralih ke kemiripan kosinus dalam proses.

Penyimpanan indeks

KeyTypeDefaultDescription
store.pathstring~/.openclaw/memory/{agentId}.sqliteLokasi indeks (mendukung token {agentId})
store.fts.tokenizerstringunicode61Tokenizer FTS5 (unicode61 atau trigram)

Konfigurasi backend QMD

Tetapkan memory.backend = "qmd" untuk mengaktifkan. Semua pengaturan QMD berada di bawah memory.qmd:
KeyTypeDefaultDescription
commandstringqmdPath executable QMD; tetapkan path absolut saat PATH layanan berbeda dari shell Anda
searchModestringsearchPerintah pencarian: search, vsearch, query
includeDefaultMemorybooleantrueIndeks otomatis MEMORY.md + memory/**/*.md
paths[]arrayPath tambahan: { name, path, pattern? }
sessions.enabledbooleanfalseIndeks transkrip sesi
sessions.retentionDaysnumberRetensi transkrip
sessions.exportDirstringDirektori ekspor
searchMode: "search" hanya leksikal/BM25. OpenClaw tidak menjalankan probe kesiapan vektor semantik atau pemeliharaan embedding QMD untuk mode tersebut, termasuk selama memory status --deep; vsearch dan query tetap memerlukan kesiapan vektor dan embedding QMD. OpenClaw memprioritaskan koleksi QMD dan bentuk kueri MCP saat ini, tetapi tetap menjaga rilis QMD yang lebih lama tetap berfungsi dengan mencoba flag pola koleksi yang kompatibel dan nama tool MCP lama saat diperlukan. Saat QMD mengiklankan dukungan untuk beberapa filter koleksi, koleksi dengan sumber yang sama dicari dengan satu proses QMD; build QMD yang lebih lama tetap menggunakan jalur kompatibilitas per koleksi. Sumber yang sama berarti koleksi memori tahan lama dikelompokkan bersama, sementara koleksi transkrip sesi tetap menjadi grup terpisah agar diversifikasi sumber tetap memiliki kedua input.
Override model QMD tetap berada di sisi QMD, bukan konfigurasi OpenClaw. Jika Anda perlu mengoverride model QMD secara global, tetapkan variabel lingkungan seperti QMD_EMBED_MODEL, QMD_RERANK_MODEL, dan QMD_GENERATE_MODEL di lingkungan runtime gateway.
KunciJenisDefaultDeskripsi
update.intervalstring5mInterval penyegaran
update.debounceMsnumber15000Debounce perubahan file
update.onBootbooleantrueSegarkan saat manajer QMD jangka panjang terbuka; juga membatasi penyegaran startup opt-in
update.startupstringoffPenyegaran opsional saat gateway dimulai: off, idle, atau immediate
update.startupDelayMsnumber120000Penundaan sebelum penyegaran startup: "idle" berjalan
update.waitForBootSyncbooleanfalseBlokir pembukaan manajer hingga penyegaran awalnya selesai
update.embedIntervalstringIrama embed terpisah
update.commandTimeoutMsnumberTimeout untuk perintah QMD
update.updateTimeoutMsnumberTimeout untuk operasi pembaruan QMD
update.embedTimeoutMsnumberTimeout untuk operasi embed QMD
KunciJenisDefaultDeskripsi
limits.maxResultsnumber6Hasil pencarian maksimum
limits.maxSnippetCharsnumberBatasi panjang cuplikan
limits.maxInjectedCharsnumberBatasi total karakter yang diinjeksi
limits.timeoutMsnumber4000Timeout pencarian
Mengontrol sesi mana yang dapat menerima hasil pencarian QMD. Skema yang sama dengan session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
Default yang dikirim mengizinkan sesi langsung dan saluran, sambil tetap menolak grup.Default hanya DM. match.keyPrefix mencocokkan kunci sesi yang dinormalisasi; match.rawKeyPrefix mencocokkan kunci mentah termasuk agent:<id>:.
memory.citations berlaku untuk semua backend:
NilaiPerilaku
auto (default)Sertakan footer Source: <path#line> dalam cuplikan
onSelalu sertakan footer
offHilangkan footer (path tetap diteruskan ke agent secara internal)
Penyegaran boot QMD menggunakan jalur subproses sekali jalan selama startup gateway. Manajer QMD jangka panjang tetap memiliki file watcher reguler dan timer interval saat pencarian memori dibuka untuk penggunaan interaktif.

Contoh QMD lengkap

{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 6, timeoutMs: 4000 },
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

Dreaming

Dreaming dikonfigurasi di bawah plugins.entries.memory-core.config.dreaming, bukan di bawah agents.defaults.memorySearch. Dreaming berjalan sebagai satu sweep terjadwal dan menggunakan fase internal ringan/dalam/REM sebagai detail implementasi. Untuk perilaku konseptual dan perintah slash, lihat Dreaming.

Pengaturan pengguna

KunciJenisDefaultDeskripsi
enabledbooleanfalseAktifkan atau nonaktifkan dreaming sepenuhnya
frequencystring0 3 * * *Irama cron opsional untuk sweep dreaming penuh
modelstringmodel defaultOverride model subagent Dream Diary opsional

Contoh

{
  plugins: {
    entries: {
      "memory-core": {
        subagent: {
          allowModelOverride: true,
          allowedModels: ["anthropic/claude-sonnet-4-6"],
        },
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
            model: "anthropic/claude-sonnet-4-6",
          },
        },
      },
    },
  },
}
  • Dreaming menulis status mesin ke memory/.dreams/.
  • Dreaming menulis output naratif yang dapat dibaca manusia ke DREAMS.md (atau dreams.md yang sudah ada).
  • dreaming.model menggunakan gerbang kepercayaan subagent plugin yang sudah ada; tetapkan plugins.entries.memory-core.subagent.allowModelOverride: true sebelum mengaktifkannya.
  • Dream Diary mencoba sekali lagi dengan model default sesi saat model yang dikonfigurasi tidak tersedia. Kegagalan kepercayaan atau allowlist dicatat di log dan tidak dicoba ulang secara diam-diam.
  • Kebijakan dan ambang fase ringan/dalam/REM adalah perilaku internal, bukan konfigurasi yang ditujukan untuk pengguna.

Terkait