whattsreply/openwiki/operations/configuration-and-data.md

---

type: operations title: Configuration and data files description: How src/config.rs loads config.toml, the system prompt from SOUL.md and the optional image description request from vision.md, the supported keys and defaults (reply_delay_seconds, catch_up_seconds, ai_retries, web_port), the template files, where the data directory and databases live, the build version, and operational and security caveats. tags: [configuration, toml, data-directory, sqlite, security, soul-md] verified:

• by: openwiki/0.7.2 at: 2026-10-21T21:49:12.291Z sources:
• id: openwiki-source-ea70eb6c04 resource: repo://.gitignore
• id: openwiki-source-0d5b861992 resource: repo://config.toml.global.template
• id: openwiki-source-1b05507d70 resource: repo://src/ai.rs
• id: openwiki-source-2a737474d8 resource: repo://src/config.rs generated: { by: "claude-code", at: "2026-10-21T21:49:12.291Z" } ---

Configuration and data files

All runtime settings come from files in the data directory, loaded once at startup by Config::load (src/config.rs:265-281): config.toml for the settings, SOUL.md for the system prompt and the optional vision.md for the image description request. No environment variable is ever read (src/config.rs:1-25). Editing any of them requires restarting wh.

Data directory

The data directory is fixed: <platform config dir>/wh, resolved with dirs::config_dir() (src/config.rs:160-168). On Windows this is %APPDATA%\wh, on Linux ~/.config/wh (file names are case-sensitive there). It cannot be changed from the config file. At startup ensure_data_dir creates it if missing (src/config.rs:308-315).

File	Purpose	Defined by
config.toml	Optional settings	CONFIG_FILE, src/config.rs:54
SOUL.md	System prompt: the responder's identity and rules; required for the AI	SOUL_FILE, src/config.rs:56
vision.md	Optional request sent with each image to obtain its description	VISION_FILE, src/config.rs:58
session.db	WhatsApp session store used by whatsapp-rust (WhatsApp client)	session_db_path, src/config.rs:317-323
history.db	Local messages, chats, contacts, per-chat autoreply flags, the global autoreply setting and image descriptions (History store)	history_db_path, src/config.rs:325-331
ai_requests.log	Optional AI request log, written only when ai_log = true (AI client)	ai_log_path, src/config.rs:333-339

The two databases are separate by design: session.db belongs to the WhatsApp library (linked-device session and keys, schema owned by whatsapp-rust), while history.db belongs to the app.

Keys in config.toml

Key	Purpose	Default when missing or blank
openai_api_key	Bearer token for the AI endpoint (trimmed)	none — the AI client cannot be built
openai_base_url	Base URL of the OpenAI-compatible endpoint (trimmed, trailing / removed)	https://ollama.com/v1
openai_model	Model for text replies (trimmed)	deepseek-v4.1-flash
openai_vision_model	Model that describes images (trimmed)	none — image understanding disabled
ai_log	Boolean; when true every request sent to the AI model is appended to ai_requests.log	false
reply_delay_seconds	Seconds the autoreply waits after the first unanswered message of a chat; messages received meanwhile are answered in the same reply; 0 answers at once	30
catch_up_seconds	After a restart, the last unanswered message of each private chat is answered once if it is at most this old; 0 disables the catch-up	7200
ai_retries	How many times a failed AI request is retried, waiting 2 s, 4 s, …; HTTP 4xx other than 429 is never retried; 0 disables retrying	2
web_port	TCP port of the web control panel on 0.0.0.0, no authentication; valid range 1–65535	unset — panel disabled

Mapping and defaults: Config::from_file (src/config.rs:284-306) and the constants at src/config.rs:34-43. reply_delay_seconds, catch_up_seconds and ai_retries are unsigned integers in the file (Option<u32>, src/config.rs:121-127), so a negative value is rejected as an invalid value type. web_port is Option<u16> (src/config.rs:128-129), so negatives and values above 65535 fail TOML parsing, and resolve_web_port (src/config.rs:254-263) additionally rejects 0. Their use is described in AI autoreply, AI client and Web control panel.

Unknown keys are ignored. In particular the keys of older versions are no longer read: system_prompt (move the prompt to SOUL.md) and cooldown_seconds / group_cooldown_seconds (replaced by reply_delay_seconds); a leftover value is silently ignored, not an error.

config.toml.global.template in the repository root lists every key with its default and a comment (with web_port commented out) and points to SOUL.md for the prompt; copy it to the data directory as config.toml and fill in openai_api_key.

Prompt files: SOUL.md and vision.md

read_prompt_file (src/config.rs:212-223) reads both files:

• the content is kept as written (not trimmed, multiline, Markdown allowed); only a leading UTF-8 BOM is removed;
• a missing file or one that is blank (only whitespace) yields None;
• an unreadable or non-UTF-8 file is an error naming the path (cannot read prompt file <path>), which aborts startup.

SOUL.md becomes Config::system_prompt. The binary embeds no prompt text: without SOUL.md (or with a blank one) the AI is not configured, every autoreply path stops and the status line says AI non configurata: imposta openai_api_key in config.toml e il prompt in SOUL.md (see Application state). soul.md.template in the repository root is a minimal starting point. The app appends only factual context to the prompt (chat kind and name, who writes the user and assistant messages, see AI autoreply); behaviour — including when to call the no_reply tool and stay silent — belongs in SOUL.md.

vision.md becomes Config::image_description_prompt; when it is missing or blank the AI client uses its built-in Italian description request.

Loading rules for config.toml

• Missing file → all defaults (read_config_file, src/config.rs:196-210).
• Unreadable file → cannot read config file <path>.
• Invalid TOML or wrong value type → invalid config file <path> with the cause invalid TOML syntax or value type at line L, column C; the error never echoes file content (parse_config_file, src/config.rs:181-194). This also covers negative or non-integer reply_delay_seconds, catch_up_seconds and ai_retries, a non-boolean ai_log and an out-of-range web_port.
• A leading UTF-8 BOM (common with Windows editors) and CRLF line endings are tolerated.
• openai_base_url consisting only of slashes is rejected with openai_base_url in config.toml must not be empty or only slashes (src/config.rs:241-252).
• web_port = 0 is rejected with web_port in config.toml must be between 1 and 65535.

Startup aborts with cannot load configuration on any of these errors (Runtime).

Build version

wh --version (or -V) prints wh <version> (<short git commit>) and exits without reading any file; the same text is shown at the bottom right of the main screen. The commit hash is embedded at build time by build.rs and is unknown when built without git (see Runtime and event loop).

Security and operational notes

• The API key is never printed: Config's Debug shows *** or <unset> (src/config.rs:132-158), and the raw FileConfig has no Debug impl at all (src/config.rs:107-130). The AI client redacts it too.
• ai_requests.log never contains the API key and replaces image data with a size placeholder, but it does store the full request (system prompt and chat context) and the reply in clear text, one record per attempt including retries, and it is only appended to, never rotated. Enable ai_log only for diagnosis and delete the file afterwards.
• web_port exposes an unauthenticated HTTP panel on every network interface: anyone who can reach the port can see chat names, toggle autoreplies and quit the bot. Set it only on a trusted network or firewall the port. A port already in use aborts startup with cannot start web server on port <port>.
• Keep config.toml and SOUL.md in the data directory, outside the repository. .gitignore ignores a root-level /config.toml, .env, any SOUL.md and *.log files (.gitignore:4-18), as well as SQLite journal/WAL/SHM files; note that the *.db pattern is commented out (.gitignore:7), so databases copied into the repo would not be ignored.
• session.db holds the linked-device credentials: deleting it forces a new QR pairing (copying it to another machine reuses the linked session). history.db can be deleted to reset local history, image descriptions and the per-chat and global autoreply flags; it is recreated on start.
• Images downloaded for description are kept in memory only and never written to the data directory; only their text description is stored in history.db.

Tests

src/config.rs:342+ covers defaults, full files, the ignored legacy system_prompt key, blank values, trimming, base URL normalisation and errors, Debug masking, vision model, DB and AI log paths, ai_log, reply_delay_seconds (default, custom values including 0, negatives rejected, legacy cooldown keys ignored), catch-up and ai_retries defaults and negatives, web_port (unset, valid, 0 and out-of-range rejected), unknown keys, BOM/CRLF, non-leaking parse errors, missing, existing, invalid and unreadable files, and SOUL.md reading (missing, blank, kept as written without BOM, non-UTF-8 error naming the path). See Unit tests.