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.enabled. 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.

If .ok/config.yml contains a key that has been removed from the schema, config load fails with an error naming the replacement — a stale key is never a silent no-op. ok config migrate (--dry-run to preview; --scope project|user|both) strips removed keys from your config files.

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 machine):

1. Store the provider key in ~/.ok/secrets.yml (0600, this machine only): ok embeddings set-key (reads the key from a hidden prompt or stdin). Check it with ok embeddings status; remove it with ok embeddings clear-key.
2. Enable it for the project: ok embeddings enable, or the Settings → This project → Search toggle. 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.
3. (Optional) point at a non-OpenAI provider (Azure / self-hosted): ok embeddings set-url <url> — or set search.semantic.baseUrl in project-local config; ok embeddings clear-url resets to the default. Tune model / dimensions in config.

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 silently degrades to lexical — it never blocks or errors. 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.