Server configuration (mindlink.json)

This page describes the Cadau backend process main config file backend/mindlink.json: what each section does and what changing it affects. For platform ops and admins; ordinary members usually skip it.

Safety: this file contains secrets and accounts — do not commit to Git (the repo already ignores it). Help docs only describe field meaning and non-sensitive examples, never real secrets.

---

1. File location and how it loads

Env-only mode: with no mindlink.json, the process depends entirely on environment variables (see each section’s Env column).

---

2. Config overview (structure example)

Common mindlink.json sections (secrets omitted; real values are on the machine; full fields in backend/config.example.json):

Typical blocks: http (listen addr), auth (jwt_secret — do not put in help), database (e.g. SQLite mindlink.db), admin_bootstrap (first admin email/password), redis, rag (vector/BM25/rerank/query rewrite/embed model/scan pages), sms, smtp, llm (default profile router pointing at the router with a site token, model auto), agent_http_tool, data_source_tool, agent_script_tool, agent_officecli_tool, agent_wecom_tool, paths (upload/runtime/archive dirs), help_docs (dir: help, index_file: index.json), skill_docs, skill_registries (ClawHub), chat_context, debug_mirror, memory_forge, agent_memory_maintain, schedule, mobile_push.

One item not in JSON, env-only: runtime time zone MINDLINK_RUNTIME_TIMEZONE (default Asia/Shanghai / Beijing time). When chat injects “current time”: prefer the user’s account display time zone; if unset, this is the fallback. UI message times also follow the account zone; see product spec §1.5.4.

---

3. Field notes by section

3.1 http — listen address

addr is the HTTP listen address, e.g. :8080 (env HTTP_ADDR). Affects the entry port for API, Web proxy, and mobile.

http.public_base_url: the public URL phones open when scanning a registration code. Empty infers from the current request. Local dev with a real phone: fill the LAN address (e.g. http://192.168.x.x:8080). Env PUBLIC_BASE_URL.

3.1a oauth — register by scan (WeChat / Alipay)

New users must scan WeChat or Alipay. With an open-platform app filled in, official OAuth runs; without it, the user must open this site’s confirm page in WeChat or Alipay.

Env: WECHAT_APP_ID, WECHAT_APP_SECRET, ALIPAY_APP_ID

3.2 auth — login-token signing

jwt_secret signs and verifies user login tokens; must be changed in production. Env JWT_SECRET. After change, all signed-in users must sign in again.

3.3 database — database

url is the connection string (this environment: SQLite file mindlink.db). Env DATABASE_URL. Affects persistence of users, workspaces, conversations, attachment metadata.

3.4 admin_bootstrap — first admin

email / password: if the database has no admin yet, create the first admin with these (sample email admin@local). Env ADMIN_BOOTSTRAP_EMAIL, ADMIN_BOOTSTRAP_PASSWORD. Only applies when there is still no admin in the database; later JSON changes do not change an existing admin password.

3.5 redis — cache and queues

addr Redis address; empty means no Redis. password, db. Env REDIS_ADDR, REDIS_PASSWORD, REDIS_DB. Affects conversation cache and some async features; without it some features degrade to in-process.

3.6 rag — knowledge retrieval pipeline

enable_vector (needs Postgres vector extension; otherwise start log warns and falls back to keyword/in-memory cosine — never pretends it vectorized), enable_bm25, enable_rerank, enable_query_rewrite, embed_model (router vector-model id; empty = auto, only models with “vector” capability), scan_max_pages (max pages to OCR scan/no-text PDFs). Env RAG_*. Affects how agents read the knowledge base (how-to articles and source archives) and how the help agent retrieves the system knowledge base. Test and local Docker Postgres should use a pgvector image (e.g. pgvector/pgvector:pg16); the server runs CREATE EXTENSION IF NOT EXISTS vector. An old postgres:16-alpine container is not enough to change compose — rebuild that Postgres container (data volume can stay).

3.7 sms — whether SMS codes are allowed

When going through the router, this deploy only keeps the switch; channel secrets live on the router.

enabled: whether to ask the router to send SMS codes. If the router is not up and this process talks to an SMS gateway directly, fill api_url / mch_id / app_id / api_secret / template_code (or matching env). Affects whether users who pick “code login” receive SMS; off means password or email only.

3.8 smtp — email (optional local fallback)

When going through the router, leave this empty; the router sends email (login codes and plugin alerts). Fill SMTP here only when the router is not up. Fields: host / port / username / password / from. Affects email codes.

3.9 llm — large-model access

In production, register vendor keys on the large-model router (llm-router.json); the backend only talks to the router:

Router list example: llm-router/config.example.json. Users can pick Auto or a listed model in the Messages composer, on the agent Persona page, or at create. OPENAI_API_KEY must be the site token the router issued for this deploy (opened in the model console). Open, plans, list prices, and eval: Model console.

Without a router you can still direct-connect a vendor via llm.profiles (local-dev fallback): default_profile, profiles.<id>.base_url / api_key / model / timeout_sec / context_tokens (backend converts ≈15/16 to a total character budget) / optional context_max_runes / resolve_context_from_model.

Single-profile env: OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL, LLM_TIMEOUT_SEC. Affects help agent, workspace agents, summaries, index rebuild — all chat and embed.

3.10 agent_http_tool — agent network requests (platform master switch)

After the workspace enables Network requests, agents can call http_request; this is site-wide gating and safety.

allow_hosts_csv comma string can replace the allow_hosts array. Env AGENT_HTTP_*.

vs workspace (user-facing): 1) workspace must enable the Network requests pack; 2) members or agents must configure allowed hosts (allow-list / public open); 3) if platform enabled is off, no agent site-wide can use the network; 4) intranet and loopback still have SSRF protection; public open requires this section’s allow_public_internet. Details: repo docs/core-mechanisms/工作区能力包.md “Network requests”.

3.10a data_source_tool — data connections (platform master switch)

After the workspace enables Data integration, agents can use data_source_invoke on MySQL / PostgreSQL / SQL Server / SQLite connections; this is site-wide gating.

Env AGENT_DATA_SOURCE_TOOL_ENABLED, DATA_SOURCE_*. Workspace must enable Data integration; admins configure data connections, data resources, and Who can use; platform enabled off means no agent site-wide can query; host or SQLite path must be on platform allow_hosts if configured. User-facing: Data connections and predefined queries.

3.11 agent_script_tool — agent script execution (platform master switch)

After the workspace enables Script execution, agents can run Python from skills and produce Office files; this is site-wide gating.

Fields: enabled, timeout_sec, max_output_bytes (default ~10 MiB), pip_index_url (passed to pip install -i for allow-listed deps such as reportlab/matplotlib; mainland should use Tsinghua/Aliyun). Env AGENT_SCRIPT_TOOL_ENABLED, AGENT_SCRIPT_TIMEOUT_SEC, AGENT_SCRIPT_MAX_OUTPUT_BYTES, MINDLINK_PIP_INDEX_URL (or AGENT_SCRIPT_PIP_INDEX_URL, PIP_INDEX_URL).

Workspace must enable Script execution and Basic document tools in the same period; admins can set each member to follow workspace / forbidden / per-member grant; platform enabled off means no agent site-wide can run scripts; the server needs Python; allow-listed script deps can auto-pip. .xlsx/.docx/.pptx need OfficeCLI — see agent_officecli_tool. User-facing: Script execution and member grants.

3.11a agent_officecli_tool — built-in office operations (OfficeCLI)

After the workspace enables Office document tools, agents can read/write .docx/.xlsx/.pptx via office_document; this is site-wide gating, and the server must install OfficeCLI.

Fields: enabled (default true; tool omitted from schema if the binary is missing), timeout_sec, max_output_bytes (default ~20 MiB). Env AGENT_OFFICECLI_*, MINDLINK_OFFICECLI (binary path), OFFICECLI_SKIP_UPDATE=1 (recommended in production).

Install: Linux containers — deploy/backend/Dockerfile already includes officecli-linux-x64. Windows local: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex, or download a release and set MINDLINK_OFFICECLI.

3.11b agent_wecom_tool — WeCom (platform master switch)

After the workspace enables WeCom and configures a self-built app, agents can call wecom_invoke; service notifications and scheduled tasks can also push to bound members. This is site-wide gating.

Fields: enabled, api_base_url (empty = https://qyapi.weixin.qq.com), timeout_sec (default 20). Env AGENT_WECOM_TOOL_ENABLED, WECOM_API_BASE_URL, WECOM_HTTP_TIMEOUT_SEC.

Workspace must enable the WeCom pack; admins fill corp ID, AgentId, Secret, and bind member accounts; platform enabled off means no WeCom calls or pushes site-wide; looking up approvals / leave requires authorizing this app under WeCom “App management → Approvals” → callable apps. Details: repo docs/core-mechanisms/工作区能力包.md “WeCom”.

3.12 paths — runtime directories

upload_dir user attachments (tmp/uploads); runtime_dir workspace runtime root (tmp/runtime); agent_runtime_template_dir agent runtime templates (empty = built-in default); chat_archive_dir long-conversation archive (tmp/memoryforge/chat-archive). Env UPLOAD_DIR, RUNTIME_DIR, AGENT_RUNTIME_TEMPLATE_DIR, CHAT_ARCHIVE_DIR. Affects attachments, agent working dirs, operating-rules files (AGENTS.md), conversation-summary archive.

3.13 help_docs — system knowledge base (help agent)

Env: HELP_DOCS_DIR, HELP_DOCS_INDEX_FILE. Affects what the help agent retrieves with no workspace selected (new-user guide, this page, etc.). Maintain: help/README.md. For English UI the backend prefers help/en/ when that tree’s index.json exists.

3.14 skill_docs — built-in skill directory index

dir platform built-in skill notes (docs/agent-skills); index_file index.json. Env SKILL_DOCS_DIR, SKILL_DOCS_INDEX_FILE. Affects built-in skill metadata shown and recalled in Skills Center (complements workspace-created skills).

3.15 skill_registries — external skill directories (ClawHub etc.)

Members can Install from directory in Skills Center, or ask a workspace agent in Messages to search / install a public skill pack. The server downloads a zip from the directory, validates it the same as “import skill pack”, then writes it into this workspace’s Skills Center. It does not integrate an OpenClaw runtime and does not run OpenClaw install scripts or plugins in the pack.

Env (can still override after JSON): SKILL_REGISTRIES_ALLOW_EXTERNAL, SKILL_REGISTRIES_INSTALL_REQUIRES_ADMIN, SKILL_REGISTRIES_HTTP_TIMEOUT_SEC, SKILL_REGISTRIES_CLAWHUB_ENABLED, SKILL_REGISTRY_CLAWHUB_BASE.

Outbound: the process must reach clawhub.base_url (HTTPS). Behind an HTTP proxy, set HTTPS_PROXY / HTTP_PROXY (same as ClawHub CLI).

Safety (ops): treat external packs as untrusted; per-pack cap 50 MiB; OpenClaw plugin packs are rejected; only how-to Agent Skills packs install. Install is audited (user_conversation_skill.registry_installed); skill source in the list shows External directory. Turning off allow_external does not affect local zip import skill.

Intranet example: allow_external true, install_requires_admin true. Fully off: "allow_external": false. Design: docs/core-mechanisms/外部技能目录安装设计.md.

3.16 chat_context — conversation context and auto-summary

resolve_max_runes_from_model infer total character budget from the current model name; max_runes default budget if infer fails; reply_reserve_runes reserved for this round’s reply; summarize_threshold_pct (50–99) when usage hits this percent of budget, summarize; min_verbatim_messages recent full messages kept after summarize; summarize_batch_messages early messages merged per summarize; max_concurrent_agent_streams max different agents “generating” at once for one user (0 = no limit); max_concurrent_embed_streams max concurrent generating conversations when this agent is an embed assistant (0 = no limit). Env CHAT_CONTEXT_*, CHAT_MAX_CONCURRENT_AGENT_STREAMS, CHAT_MAX_CONCURRENT_EMBED_STREAMS (env can still override JSON). Affects whether long conversations auto-compress history and the UI context-usage ring. Couples with llm.profiles.*.context_tokens.

3.16.1 Chat generation concurrency (env only)

One signed-in user can have several different agents generating at once; this limits “how many agents are generating”, so extra tabs or scripts do not fill connections and model calls.

CHAT_MAX_CONCURRENT_AGENT_STREAMS default 5; 0 = no limit. Over: HTTP 429, code=agent_generation_user_limit. Same agent (main site) is still exclusive: HTTP 409, code=agent_generation_busy (unrelated to this cap).

Embed assistant: the same agent can generate for several visitors at once. The cap is generating streams, not historical conversation count. CHAT_MAX_CONCURRENT_EMBED_STREAMS default 20. Persona “embed assistant concurrent reply cap” can tighten further but not exceed this. Over: HTTP 429, code=embed_generation_limit, widget “current conversation count has reached the limit”. Same conversation still waits for this round to finish. Restart the backend after change.

3.17 debug_mirror — debug mirror

enabled whether to mirror some request/response to a local directory; dir empty with enabled uses tmp/debug-mirror. Env MINDLINK_DEBUG_MIRROR, MINDLINK_DEBUG_MIRROR_DIR. For troubleshooting; production should turn off to avoid disk pile-up and secrets on disk.

3.18 mobile_push — mobile push

base_url push-service root; secret_key auth (do not publish). Env MOBILE_PUSH_BASE_URL, MOBILE_PUSH_SECRET_KEY. Affects Cadau mobile App offline notifications; unconfigured means in-app messages only.

3.19 memory_forge — memory-forge auto-scan

auto_scan_enabled (default false), auto_scan_interval (Go duration, e.g. 24h), auto_scan_days cluster conversation archives from the last N days. Env MEMORYFORGE_AUTO_SCAN_*. Affects admin memory forge (help/workspace knowledge overlay proposals); not personal agent-memory cleanup. Off does not affect user Remember, chat extract, or memory maintenance.

3.20 agent_memory_maintain — idle tidy of personal agent memory

enabled nightly auto-tidy (default false); daily_local_hour local night start hour (0–23), ~2-hour window; daily_note_retain_days daily-note retention; stale_review_days “somewhat old” mark for model review; min_entries_for_llm long-term count before model review-delete; max_agents_per_run; max_deletes_per_agent; use_llm. Env AGENT_MEMORY_MAINTAIN_*. Affects personal-memory dedupe and expiry cleanup; also needs schedule.enabled. Admin entry: agent-memory-maintain.md. Unrelated to memory_forge.

3.21 schedule — user scheduled-task scheduler

enabled (default true), tick_interval (e.g. 30s), max_active_per_user (default 20). Env SCHEDULE_*. Affects whether Cron-class scheduled tasks members create under My agents actually run.

---

4. How changes take effect

1. After changing mindlink.json, restart the backend (local Air reloads; Docker needs rebuild/restart).
2. If env is also set, confirm priority: after JSON loads, some AGENT_HTTP_*, HELP_DOCS_* may still be overridden by env.
3. Before changing jwt_secret, database path, or LLM keys, back up and plan a short maintenance window.

---

5. Common questions (help agent may cite)

---

6. Related docs

• Example config: backend/config.example.json
• Workspace capabilities (user-facing): docs/core-mechanisms/工作区能力包.md
• Script execution and member grants: script-execution.md
• Data connections and predefined queries (user-facing): ../product-features/data-integration.md
• Skills and Skills Center (user-facing): help/en/product-features/skills-and-agents.md
• External skill-directory design (implementation): docs/core-mechanisms/外部技能目录安装设计.md
• Agent operating rules: help/en/product-features/agents-operating-rules.md
• System knowledge-base maintenance: help/en/README.md
• Agent memory maintenance (admin): agent-memory-maintain.md
• Model console (router): model-routing.md
• Agent memory (users): ../product-features/agent-memory.md