服务端配置说明（mindlink.json）

本文说明 Cadau 后端进程 的主配置文件 backend/mindlink.json：各段做什么、改哪里会影响什么。面向 平台运维与管理员；普通成员一般无需阅读。

安全：本文件含密钥与账号，勿提交到 Git（仓库已忽略）。帮助文档里只写字段含义与非敏感示例，不写真实密钥。

---

1. 文件位置与加载方式

仅环境变量模式：不放置 mindlink.json 时，进程完全依赖环境变量（见各节「环境变量」列）。

---

2. 配置总览（结构示例）

以下为 mindlink.json 常见段落（密钥已省略；各环境具体取值以本机文件为准，完整字段见 backend/config.example.json）：

{
  "http": { "addr": ":8080" },
  "auth": { "jwt_secret": "<勿写入帮助文档>" },
  "database": { "url": "file:mindlink.db?cache=shared&mode=rwc" },
  "admin_bootstrap": { "email": "admin@local", "password": "<勿写入帮助文档>" },
  "redis": { "addr": "127.0.0.1:6379", "password": "", "db": 0 },
  "rag": {
    "enable_vector": true,
    "enable_bm25": false,
    "enable_rerank": false,
    "enable_query_rewrite": false,
    "embed_model": "",
    "scan_max_pages": 8
  },
  "sms": { "enabled": true },
  "smtp": {},
  "llm": {
    "default_profile": "router",
    "profiles": {
      "router": {
        "base_url": "http://127.0.0.1:8090/v1",
        "api_key": "<路由端为本套部署签发的站点令牌>",
        "model": "auto",
        "timeout_sec": 90,
        "context_tokens": 1000000
      }
    }
  },
  "agent_http_tool": {
    "enabled": true,
    "allow_hosts": ["localhost", "127.0.0.1", "::1", "crm.katop.com"],
    "max_rounds": 500,
    "timeout_sec": 45,
    "max_body_bytes": 262144,
    "max_request_body_bytes": 1048576,
    "allow_public_internet": true
  },
  "data_source_tool": {
    "enabled": true,
    "allow_hosts": [],
    "default_preview_max_rows": 200,
    "absolute_preview_max_rows": 500
  },
  "agent_script_tool": {
    "enabled": true,
    "timeout_sec": 60,
    "max_output_bytes": 10485760,
    "pip_index_url": "https://pypi.tuna.tsinghua.edu.cn/simple"
  },
  "agent_officecli_tool": {
    "enabled": true,
    "timeout_sec": 60,
    "max_output_bytes": 20971520
  },
  "agent_wecom_tool": {
    "enabled": true,
    "timeout_sec": 20
  },
  "paths": {
    "upload_dir": "tmp/uploads",
    "runtime_dir": "tmp/runtime",
    "agent_runtime_template_dir": "",
    "chat_archive_dir": "tmp/memoryforge/chat-archive"
  },
  "help_docs": { "dir": "help", "index_file": "index.json" },
  "skill_docs": { "dir": "docs/agent-skills", "index_file": "index.json" },
  "skill_registries": {
    "allow_external": true,
    "install_requires_admin": false,
    "http_timeout_sec": 30,
    "clawhub": {
      "enabled": true,
      "base_url": "https://clawhub.ai"
    }
  },
  "chat_context": {
    "resolve_max_runes_from_model": true,
    "max_runes": 937500,
    "reply_reserve_runes": 16000,
    "summarize_threshold_pct": 88,
    "min_verbatim_messages": 6,
    "summarize_batch_messages": 4
  },
  "debug_mirror": { "enabled": true, "dir": "" },
  "memory_forge": {
    "auto_scan_enabled": false,
    "auto_scan_interval": "24h",
    "auto_scan_days": 7
  },
  "agent_memory_maintain": {
    "enabled": false,
    "daily_local_hour": 2,
    "daily_note_retain_days": 14,
    "stale_review_days": 90,
    "min_entries_for_llm": 5,
    "max_agents_per_run": 30,
    "max_deletes_per_agent": 8,
    "use_llm": true
  },
  "schedule": {
    "enabled": true,
    "tick_interval": "30s",
    "max_active_per_user": 20
  },
  "mobile_push": {
    "base_url": "https://crm.katop.com/dtzXyJPn",
    "secret_key": "<勿写入帮助文档>"
  }
}

另有一项 未写在 JSON 内、由环境变量控制：运行时时区 MINDLINK_RUNTIME_TIMEZONE（默认 Asia/Shanghai / 北京时间）。 对话注入「当前时间」时：优先用户账号显示时区，未设置则用本项作为回退。界面消息时间同样跟账号时区；详见产品规格 §1.5.4。

---

3. 各段字段说明

3.1 http — 监听地址

环境变量：HTTP_ADDR

影响：API、Web 代理、移动端请求的入口端口。

http.public_base_url：手机扫注册码时要打开的对外地址。空则按当前请求推断。本机开发若要用真机扫码，填局域网地址（如 http://192.168.x.x:8080）。环境变量 PUBLIC_BASE_URL。

---

3.1a oauth — 注册扫码（微信 / 支付宝）

新用户注册须用微信或支付宝扫一扫。填了开放平台应用后走官方授权；不填则用户须用微信或支付宝打开本站确认页。

环境变量：WECHAT_APP_ID、WECHAT_APP_SECRET、ALIPAY_APP_ID

---

3.2 auth — 登录令牌签名

环境变量：JWT_SECRET

影响：更换后所有已登录用户需重新登录。

---

3.3 database — 数据库

环境变量：DATABASE_URL

影响：用户、工作区、会话、附件元数据等持久化存储。

---

3.4 admin_bootstrap — 首次管理员

环境变量：ADMIN_BOOTSTRAP_EMAIL、ADMIN_BOOTSTRAP_PASSWORD

影响：仅 数据库里还没有任何管理员 时生效；之后改 JSON 不会改已有管理员密码。

---

3.5 redis — 缓存与队列

环境变量：REDIS_ADDR、REDIS_PASSWORD、REDIS_DB

影响：会话缓存、部分异步能力；未配置时部分功能降级为进程内实现。

---

3.6 rag — 知识检索管线

环境变量：RAG_ENABLE_VECTOR、RAG_ENABLE_BM25、RAG_ENABLE_RERANK、RAG_ENABLE_QUERY_REWRITE、RAG_EMBED_MODEL、RAG_SCAN_MAX_PAGES

影响：智能体读取 知识库（说明文档与原文档案）以及帮助智能体检索 系统知识库 时的召回策略。测服与本地 Docker Postgres 请使用带 pgvector 的镜像（如 pgvector/pgvector:pg16），启动后由服务端执行 CREATE EXTENSION IF NOT EXISTS vector。若容器仍是旧的 postgres:16-alpine，只改 compose 不够，需重建该 Postgres 容器（可保留数据卷）。

---

3.7 sms — 是否允许短信验证码

走路由端时，本套配置只保留开关，通道密钥写在路由端。

未起路由端、要本进程直连短信网关时，才填写 api_url / mch_id / app_id / api_secret / template_code（或对应环境变量）。

影响：用户选「验证码登录」时能否收到短信；关则只能密码登录或改走邮件。

---

3.8 smtp — 邮件（可选本机回退）

走路由端时此处留空，由路由端代发邮件（登录验证码与插件告警）。未起路由端时才在本套配置填写 SMTP。

影响：邮件验证码。

---

3.9 llm — 大模型接入

正式环境请把供应商密钥登记在 大模型路由端（llm-router.json），backend 只连路由端：

路由端清单示例见 llm-router/config.example.json。用户在 消息 输入栏、智能体 人格 页或创建时可选用 自动 或指定某一个已上架模型。OPENAI_API_KEY 必须是路由端为这一套部署签发的站点令牌（在模型服务台开通）。开通、套餐、牌价与评测见 模型服务台。

未起路由端时，仍可用 llm.profiles 直连 供应商（本地开发回退）：

环境变量（单档兼容）：OPENAI_BASE_URL、OPENAI_API_KEY、OPENAI_MODEL、LLM_TIMEOUT_SEC

影响：帮助智能体、工作区智能体、摘要、索引重建等所有对话与嵌入能力。

---

3.10 agent_http_tool — 智能体联网请求（平台总开关）

工作区里开通 联网请求 能力后，智能体才能调用 http_request；此处是 全平台 门控与安全策略。

也可用 allow_hosts_csv 逗号分隔字符串代替 allow_hosts 数组。

环境变量：AGENT_HTTP_TOOL_ENABLED、AGENT_HTTP_ALLOW_HOSTS、AGENT_HTTP_ALLOW_PUBLIC_INTERNET、AGENT_TOOL_MAX_ROUNDS、AGENT_HTTP_TIMEOUT_SEC、AGENT_HTTP_MAX_BODY_BYTES、AGENT_HTTP_MAX_REQUEST_BODY_BYTES

与工作区的关系（用户侧说法）：

1. 工作区须开通 联网请求 能力包；
2. 成员或智能体须配置允许的站点（白名单 / 公网开放等）；
3. 平台 enabled 为关，则全站智能体均不能联网；
4. 内网、本地环回等仍受 SSRF 防护；公网开放须 本段 allow_public_internet 为真。

详情见仓库 docs/core-mechanisms/工作区能力包.md 中「联网请求」一节。

---

3.10a data_source_tool — 数据连接（平台总开关）

工作区开通 数据集成 能力后，智能体才能通过 data_source_invoke 访问 MySQL / PostgreSQL / SQL Server / SQLite 等连接；此处为 全平台 门控与安全策略。

环境变量：AGENT_DATA_SOURCE_TOOL_ENABLED、DATA_SOURCE_ALLOWED_HOSTS、DATA_SOURCE_DEFAULT_PREVIEW_MAX_ROWS、DATA_SOURCE_ABSOLUTE_PREVIEW_MAX_ROWS

与工作区的关系（用户侧说法）：

1. 工作区须开通 数据集成 能力包；
2. 管理员配置 数据连接、数据资源 与 谁可以使用；
3. 平台 enabled 为关，则全站智能体均不能查库；
4. 主机或 SQLite 路径须在平台 allow_hosts 白名单内（若已配置）。

用户侧操作见 数据连接与预定义查询。

---

3.11 agent_script_tool — 智能体脚本执行（平台总开关）

工作区里开通 脚本执行 能力后，智能体才能按技能执行 Python 脚本并产出 Office 等文件；此处是 全平台 门控。

环境变量：AGENT_SCRIPT_TOOL_ENABLED、AGENT_SCRIPT_TIMEOUT_SEC、AGENT_SCRIPT_MAX_OUTPUT_BYTES、MINDLINK_PIP_INDEX_URL（或 AGENT_SCRIPT_PIP_INDEX_URL、PIP_INDEX_URL）

与工作区的关系（用户侧说法）：

1. 工作区须开通 脚本执行 能力包，且 基础文档工具 同期有效；
2. 管理员可为 每位成员 单独设置 跟随工作区 / 禁止使用 / 单独授权；
3. 平台 enabled 为关，则全站智能体均不能执行脚本；
4. 服务器须安装 Python；脚本白名单依赖可自动 pip。.xlsx/.docx/.pptx 须安装 OfficeCLI，见 agent_officecli_tool。

用户侧操作说明见 脚本执行与成员授权。

---

3.11a agent_officecli_tool — 办公文档内置操作（OfficeCLI）

工作区开通 办公文档工具 后，智能体可通过 office_document 读写 .docx/.xlsx/.pptx；此处为 全平台 门控，且服务器须安装 OfficeCLI。

环境变量：AGENT_OFFICECLI_TOOL_ENABLED、AGENT_OFFICECLI_TIMEOUT_SEC、AGENT_OFFICECLI_MAX_OUTPUT_BYTES、MINDLINK_OFFICECLI（可执行文件路径）、OFFICECLI_SKIP_UPDATE=1（生产建议）

安装：

• Linux 容器：deploy/backend/Dockerfile 已内置 officecli-linux-x64
• Windows 本地开发：PowerShell 执行 irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex，或下载 release 后设置 MINDLINK_OFFICECLI

---

3.11b agent_wecom_tool — 企业微信（平台总开关）

工作区开通 企业微信 能力并配置自建应用后，智能体才能调用 wecom_invoke；服务通知与定时任务也可推到已绑定成员。此处是 全平台 门控。

环境变量：AGENT_WECOM_TOOL_ENABLED、WECOM_API_BASE_URL、WECOM_HTTP_TIMEOUT_SEC

与工作区的关系：

1. 工作区须开通 企业微信 能力包；
2. 管理员填写自建应用企业 ID、AgentId、Secret，并绑定成员账号；
3. 平台 enabled 为关，则全站不能调用企微、也不会推送；
4. 查审批 / 假期须在企微「应用管理 → 审批」详情里点「可调用接口的应用」的「设置」授权本应用。

详情见仓库 docs/core-mechanisms/工作区能力包.md 中「企业微信」一节。

---

3.12 paths — 运行时目录

环境变量：UPLOAD_DIR、RUNTIME_DIR、AGENT_RUNTIME_TEMPLATE_DIR、CHAT_ARCHIVE_DIR

影响：附件、智能体工作目录、操作规则文件（AGENTS.md）、会话摘要归档位置。

---

3.13 help_docs — 系统知识库（帮助智能体）

环境变量：HELP_DOCS_DIR、HELP_DOCS_INDEX_FILE

影响：未选工作区时 帮助智能体 检索的本目录（含新手引导、本文等）。维护方式见 help/README.md。

---

3.14 skill_docs — 内置技能目录索引

环境变量：SKILL_DOCS_DIR、SKILL_DOCS_INDEX_FILE

影响：技能中心展示与召回时的内置技能元数据（与工作区自建技能互补）。

---

3.15 skill_registries — 外部技能目录（ClawHub 等）

成员可在 技能中心 使用 「从目录安装」，或在 消息 里请工作区智能体 搜索 / 安装 公开技能包。服务端从目录 下载 zip，经与「导入技能包」相同的校验后写入 本工作区技能中心；不集成 OpenClaw 运行时，不执行包内的 OpenClaw 安装脚本或插件。

环境变量（JSON 加载后仍可覆盖）：

出站网络：进程需能访问 clawhub.base_url（HTTPS）。服务器在 HTTP 代理 后时，可设 HTTPS_PROXY / HTTP_PROXY（与 ClawHub CLI 行为一致）。

安全与边界（运维须知）：

• 外部包视为 不可信输入；单包上限 50 MiB；OpenClaw 插件包 会被拒绝，仅 操作说明类 Agent Skills 包可安装。
• 安装记录写入审计（user_conversation_skill.registry_installed）；技能来源在列表中显示为 「外部目录」。
• 关闭 allow_external 不影响本地上传 zip 导入技能。

示例（内网仅允许管理员安装）：

"skill_registries": {
  "allow_external": true,
  "install_requires_admin": true,
  "http_timeout_sec": 45,
  "clawhub": {
    "enabled": true,
    "base_url": "https://clawhub.ai"
  }
}

示例（完全关闭外部目录）：

"skill_registries": {
  "allow_external": false
}

实现对照与设计说明见仓库 docs/core-mechanisms/外部技能目录安装设计.md。

---

3.16 chat_context — 对话上下文与自动摘要

环境变量：CHAT_CONTEXT_RESOLVE_MAX_FROM_MODEL、CHAT_CONTEXT_MAX_RUNES、CHAT_CONTEXT_REPLY_RESERVE_RUNES、CHAT_CONTEXT_SUMMARIZE_THRESHOLD_PCT、CHAT_CONTEXT_MIN_VERBATIM_MESSAGES、CHAT_CONTEXT_SUMMARIZE_BATCH_MESSAGES、CHAT_MAX_CONCURRENT_AGENT_STREAMS、CHAT_MAX_CONCURRENT_EMBED_STREAMS（与 JSON 字段 max_concurrent_agent_streams / max_concurrent_embed_streams 等价，环境变量在 JSON 之后仍可覆盖）

影响：长会话是否自动压缩历史、界面上下文用量圆环上限。与 llm.profiles.*.context_tokens 联动。

---

3.16.1 对话生成并发（仅环境变量）

同一登录用户可同时让多个不同智能体生成回复；本项限制「同时生成中的智能体个数」，防止多开标签或脚本打满连接与模型调用。

超限：HTTP 429，code=agent_generation_user_limit，提示等待一条完成后再开。 同智能体（主站）仍互斥：HTTP 409，code=agent_generation_busy（与本上限无关）。

嵌入助手：同一智能体可同时为多位访客生成回复。限制的是「正在生成」的路数，不是历史会话条数。

智能体人格设置里的「嵌入助手同时回复上限」可再收紧，但不能突破本项。 超限：HTTP 429，code=embed_generation_limit，挂件提示「当前对话人数已达上限，请稍后再试」。同一对话内仍须等本轮说完再发。

改后需 重启后端。

---

3.17 debug_mirror — 调试镜像

环境变量：MINDLINK_DEBUG_MIRROR、MINDLINK_DEBUG_MIRROR_DIR

影响：排障用；生产环境建议关闭，避免磁盘堆积与敏感信息落盘。

---

3.18 mobile_push — 移动端推送

环境变量：MOBILE_PUSH_BASE_URL、MOBILE_PUSH_SECRET_KEY

影响：Cadau 移动 App 接收离线通知；未配置则仅应用内消息。

---

3.19 memory_forge — 记忆锻造自动扫描

环境变量：MEMORYFORGE_AUTO_SCAN_ENABLED、MEMORYFORGE_AUTO_SCAN_INTERVAL、MEMORYFORGE_AUTO_SCAN_DAYS

影响：管理端 记忆锻造（帮助/工作区知识叠加层提案）；不是个人智能体记忆清理。关闭时不影响用户「记住」、对话提炼与记忆维护。

---

3.20 agent_memory_maintain — 智能体个人记忆闲时整理

环境变量：AGENT_MEMORY_MAINTAIN_ENABLED、AGENT_MEMORY_MAINTAIN_DAILY_LOCAL_HOUR、AGENT_MEMORY_MAINTAIN_DAILY_NOTE_RETAIN_DAYS、AGENT_MEMORY_MAINTAIN_USE_LLM 等。

影响：个人记忆去重与过期清理；须同时 schedule.enabled。管理端入口与说明见 agent-memory-maintain.md。与 memory_forge 无关。

---

3.21 schedule — 用户定时任务调度

环境变量：SCHEDULE_ENABLED、SCHEDULE_TICK_INTERVAL、SCHEDULE_MAX_ACTIVE_PER_USER

影响：成员在 我的智能体 中创建的 Cron 类定时任务是否会被执行。

---

4. 修改后如何生效

1. 改 mindlink.json 后 重启后端进程（本地 Air 会自动重载；Docker 需重建/重启容器）。
2. 若同时设置了环境变量，确认优先级：JSON 加载后，部分 AGENT_HTTP_*、HELP_DOCS_* 等仍可能被环境变量覆盖。
3. 改 jwt_secret、数据库路径、LLM 密钥前建议备份并安排短暂维护窗口。

---

5. 常见问题（帮助智能体可引用）

---

6. 相关文档

• 示例配置：backend/config.example.json
• 工作区能力（用户视角）：docs/core-mechanisms/工作区能力包.md
• 脚本执行与成员授权：script-execution.md
• 数据连接与预定义查询（用户视角）：../product-features/data-integration.md
• 技能与技能中心（用户视角）：help/product-features/skills-and-agents.md
• 外部技能目录设计（实现对照）：docs/core-mechanisms/外部技能目录安装设计.md
• 智能体操作规则：help/product-features/agents-operating-rules.md
• 系统知识库维护：help/README.md
• 智能体记忆维护（管理端）：agent-memory-maintain.md
• 模型服务台（路由端）：model-routing.md
• 智能体记忆（用户）：../product-features/agent-memory.md