Configuration

OpenKnowledge reads YAML config from three places:

• Project: ./.ok/config.yml (this project, committed to git)
• User: ~/.ok/global.yml (every project on your machine)
• Project-local: ./.ok/local/config.yml (this project on this machine; gitignored). Holds per-machine-per-project preferences such as autoSync.mode. Maintained by the editor (auto-sync onboarding modal, sync popover, Settings pane Sync section); you don't normally hand-edit it.

All files are optional; defaults cover everything.

You can inspect and edit config three ways:

• Settings pane in the editor: Cmd/Ctrl-, or App menu → Settings…
• Your IDE: .ok/config.yml ships with a $schema magic comment for autocomplete and inline field descriptions
• CLI: ok config validate checks the merged result

Edits made anywhere reflect everywhere; an open Settings pane refreshes live.

Schema

The Scope column says which file a setting belongs in:

• project → .ok/config.yml (shared in git)
• user → ~/.ok/global.yml (personal, all projects)
• project-local → .ok/local/config.yml (this machine only, gitignored)

A key set in a file more specific than its scope (a user-scope key in .ok/config.yml, for example) is ignored.

Removed keys

As new versions of OpenKnowledge are released, some keys are retired from the schema. If any of your config files contains a key the schema no longer reads, that key alone is dropped from the loaded config and reported with the setting that replaced it.

This applies to genuinely retired keys only. A file that cannot be trusted — invalid YAML, or a value that fails validation — is rejected and falls back to defaults.

Run ok config validate to see which keys are stale and what replaced each one. ok config migrate removes them for you; it defaults to every layer, so a bare run reaches whichever file the key lives in. Narrow it with --scope project, project-local, user, or all (the default), and preview with --dry-run. Migration deletes retired keys, but it never rewrites anything else on your behalf. A key whose replacement is not a one-to-one translation is removed and reported for you to recreate by hand.

Folder properties

A folder's own metadata lives in that folder's .ok/ directory, not in config.yml: its own open-shape frontmatter (any keys; title / description / tags are the conventional ones) in .ok/frontmatter.yml, and its templates in .ok/templates/. Folder properties describe only their own folder: they are not inherited by the docs inside it. (Templates do resolve leaf-to-root, so a root template is available in every subfolder.) Set them from the editor's Folder properties pane, or via the edit({ folder }) / write({ folder }) MCP tools. See Folders and templates for the full walkthrough.

Ignore patterns

Path exclusions live in a project-root .okignore file using gitignore syntax. .gitignore rules are honored automatically alongside it, and a leading ! re-includes a file .gitignore excluded. Edit patterns from the Ignore patterns section of the Settings pane, the right-click menu in the file tree, or by hand in any editor; the running server picks up changes without a restart. See Ignore patterns for the full UX.

Precedence

CLI flags (when running the bundled ok CLI) > environment variables > project-local config > project config > user config > defaults. Leaf values at higher levels override the same leaf below; arrays replace, they don't concatenate.

Environment variables

Most users never set these — the schema settings above cover the common cases. These have no config.yml key or Settings toggle; they are environment-only.

Common:

Advanced / operator:

Semantic search

The MCP search tool can fuse an embeddings-based semantic signal into its ranking, so an agent's query surfaces conceptually-related pages even when they share no keywords (a query about "auth retries" can surface a page titled "Session Token Refresh"). It is off by default and additive — with it off, search everywhere (the MCP tool and the cmd-K omnibar) is purely lexical and stays on-machine. With it on, the omnibar gains a By meaning mode alongside its default lexical mode: typing never embeds; pressing Enter fires one semantic search, sending the query to the embeddings provider.

To turn it on (per project, per machine):

1. Enable it for the project: the Settings → This project → Search toggle, or ok embeddings enable. Either sets search.semantic.enabled: true in project-local config (<project>/.ok/local/config.yml), picked up live by a running server; ok embeddings disable turns it off.
2. Set the API key right there on the same screen (or ok embeddings set-key in the project). Keys are per project — one project's key is never shared with another unless both point at the same endpoint. A localhost endpoint (Ollama / LM Studio) needs no key at all — the field shows "not required". ok embeddings list shows every stored key (redacted); ok embeddings clear-key removes this project's.
3. (Optional) point at your own OpenAI-compatible endpoint (a self-hosted Ollama / vLLM / LM Studio server, or another provider): open Custom endpoint in that same section, set the endpoint URL and the model id, and press Test connection — it runs one throwaway embed and reports either the detected vector size or the specific reason it failed. The same knobs are available from the CLI (ok embeddings set-url <url> / clear-url, ok embeddings set-model <id> / clear-model) and in project-local config (search.semantic.baseUrl / model). The vector size is detected automatically, so dimensions normally stays unset. Changing the endpoint or the model discards the cached vectors and re-embeds the corpus.

The first semantic search kicks off a background embed of the corpus (cents for a whole vault with text-embedding-3-small); vectors are cached incrementally under .ok/local/ and only changed docs re-embed. If the key is missing, the provider errors, or you're offline, search degrades to lexical — it never blocks or errors. Because that degradation is quiet, Test connection is the way to tell a working custom endpoint apart from one that is failing. Each MCP search response reports embedding coverage so an agent knows when vectors are still filling in.

Link previews

Hovering a link in the editor shows a preview card. For internal links (other documents in your project) the card — title, folder, tags, last-edited time, backlink count, and a short excerpt — is built entirely from the local index and file contents: always on, no configuration, and nothing leaves the machine.

For external links, a card shows the destination's site name, page title, description, and favicon. It is on by default; turn it off per machine in Settings.

To turn it off (per machine): the Settings → This project → Link previews toggle, which sets linkPreviews.enabled: false in project-local config (<project>/.ok/local/config.yml), picked up live by a running server. The setting is enforced by the local server, so with it off no external request is made. A preview that can't be fetched (offline, timeout, the site blocks it) quietly falls back to the plain URL pill.

Verifying changes

The Settings pane validates .ok/config.yml against the schema as you edit and surfaces errors inline. The Ignore patterns section shows a live count of files each pattern matches, so you can confirm scope changes without leaving the editor.