MindOS 是一个"人负责思考、AI Agent 负责行动"的人机协作心智系统，你的笔记、项目与知识全部以本地 Markdown 形式存储。当 AI Agent 可以直接读写你的文件时，安全边界就成了核心命题：MindOS 通过 Bearer Token 认证、路径沙箱、Agent 写保护与原子写入四道防线，在保证 Agent 高效干活的同时，确保你的本地隐私和数据始终处于自己的掌控之中。

一、Bearer Token 认证：给每次 API 请求上"身份锁"

MindOS 的 Web 服务（默认端口 3456）和 MCP 接口（默认端口 8781）都可能暴露到局域网甚至远程网络。为了防止未授权访问，MindOS 采用Bearer Token 认证机制：所有对App /api/*和 MCP/mcp端点的请求，都必须携带Authorization: Bearer <token>请求头。

Token 从哪里来？执行mindos onboard初始化时会自动生成，保存在本地配置文件中；你也可以随时用mindos token命令查看当前 Token，它会同时打印出给各 Agent（Claude Code、Gemini CLI 等）接入用的 MCP 配置片段。

相关源码：

• 服务端认证逻辑：packages/mindos/src/server/auth.ts
• 客户端自动附带 Token：packages/mindos/src/client.ts
• Token 管理命令：packages/mindos/bin/commands/token.js

认证机制的三个细节

1️⃣ 常量时间比较，防时序攻击

服务端使用 safeTokenEquals 做 Token 比对，底层调用 Node.js 的timingSafeEqual——无论 Token 匹配到第几位才失败，耗时都相同，避免攻击者通过响应时间差逐字节猜出 Token。

2️⃣ 本地浏览器同域豁免

本机浏览器打开的 Web UI 发起的请求，若来自回环地址（127.0.0.1/localhost），可以免 Token 通过；但一旦请求经由反代从远程机器转发进来（通过X-Forwarded-For等头识别），豁免立即失效。这个设计让本地体验流畅，又不给局域网内其他设备留后门。

3️⃣ 网页密码与 Token 双轨独立

webPassword保护浏览器登录，authToken保护 API/MCP 调用，二者相互独立。配置项说明见 docs/zh/configuration.md：如果你的 MindOS 暴露到网络，建议务必设置authToken。

二、路径沙箱：把一切文件操作锁进~/.mindos围栏

MindOS 桌面端负责运行时（runtime）的下载、替换和清理，这是最容易发生路径穿越攻击的地方。为此，packages/desktop/src/safe-paths.ts 实现了一个严格的路径沙箱，核心函数validateRuntimePath对每个路径做四重校验：

白名单仅包含runtime、runtime-downloading、runtime-old、config.json等少数更新所需条目——哪怕路径格式合法，只要不在这个清单里，直接抛出SECURITY: Subdirectory not whitelisted错误。

此外还有配套的目录名"消毒"机制：isValidDirName 会拒绝包含路径分隔符、空字节、以.开头的隐藏目录名；sanitizeDirName 则把可疑字符替换为安全形式，从源头上阻止非法目录名进入文件系统。

三、写保护：给 Agent 的手腕上"权限铐"

在 MindOS 中，Agent 通过知识库（KB）工具操作你的笔记。"能读"和"能写"是完全不同的权限等级。packages/mindos/src/agent/tool/kb-tools.ts 把工具划分成三组权限策略：

• READONLY_TOOL_NAMES：只读策略下的工具集，Agent 只能查询、检索、浏览；
• KNOWLEDGE_WRITE_TOOL_NAMES：受限写策略下的工具集——可以写入，但会跳过破坏性的移动/删除操作；
• WRITE_TOOLS：全部写操作工具名单，由 Agent 会话在beforeToolCall钩子中逐一拦截校验（见 packages/mindos/src/agent/mindos-pi/session.ts），每次写操作都会被审核并记入审计日志。

这意味着：当你对某个任务使用"只读模式"对话时，Agent 物理上拿不到任何写工具；即便授予了写入权限，危险操作也仍需经过写保护拦截器。权限最小化，而不是事后追责。

四、原子写入与符号链接防护：数据落盘零损坏

先写临时文件，再原子改名

无论是服务器端文件写入（atomicWriteFile：写.tmp-<pid>-<时间戳>后renameSync原子替换），还是知识库元数据更新（atomicMetadata：wx标志独占创建 +0o600权限 + 重命名），MindOS 都遵循同一个模式：

绝不直接覆盖原文件——新内容先写进临时文件，成功后用rename一步替换。

同一文件系统内rename是原子操作：你看到的要么是旧版本、要么是完整的新版本，绝不会出现"写了一半的损坏文件"。即使进程在写入中途崩溃，原文件也毫发无损，finally块还会清理残留的临时文件。

符号链接攻击：安全删除器的必修课

rename、删除操作最危险的陷阱是符号链接：攻击者可以把runtime-old软链指向你的用户数据目录，诱导更新流程"清理旧版本"时误删真实数据。packages/desktop/src/safe-rm.ts 提供的assertNotSymlink、assertNoSymlinksInPath、safeRmSync会逐层检查路径链，发现软链立即中止并抛出SECURITY错误。

这些防线不是纸面设计，而是有完整的对抗性测试护航的：tests/security-hardening.test.ts 模拟了"软链指向用户数据"、../../../../etc/passwd路径穿越、更新中断后回滚等端到端攻击场景，逐一验证防御生效、数据无损。

五、安全设计速查表

总结：透明、可控、可验证的安全

MindOS 的安全理念可以浓缩为一句话：Agent 拥有完成工作所需的最小权限，且每道防线都可被测试验证。

• 对外，Bearer Token 让远程调用"持证上岗"，本地访问依然丝滑；
• 对内，路径沙箱和写保护把 Agent 关进权限围栏，你的笔记目录结构不会越界，敏感操作不会失控；
• 对数据，原子写入和软链防护保证每一次落盘都是完整且可预期的。

如果你想亲自体验，可参考 README_zh.md 完成安装，用mindos token拿到 Token，再通过 docs/zh/configuration.md 配置authToken与webPassword，即可拥有一个既开放协作又守口如瓶的本地 AI 心智系统 🧠🔒