面向个人与团队的本地优先 AI Agent 工作台，集成聊天、多模型、工具调用、MCP、知识库、记忆系统与 Web 控制台。
TokenMind 是一个本地优先的 AI Agent 框架，目标不是只做一个聊天机器人，而是提供一套可持续扩展的 Agent 运行时与工作台：
- 统一接入多种模型与推理提供商
- 在会话中调用文件、Shell、Web 搜索、MCP 等工具
- 提供知识库、记忆系统、定时任务与文件中心
- 用完整的 Web UI 管理对话、模型、知识库和运行时设置
它适合用来搭建你自己的个人 AI 助手，也适合在团队内做私有化 Agent 工作台。
- 多模型支持：内置 OpenAI、Anthropic、Gemini、DeepSeek、MiniMax、OpenRouter、Ollama、SiliconFlow、Qwen、GLM、Moonshot 和自定义兼容接口等提供商
- Web 控制台：支持会话管理、流式回复、工具时间线、停止生成、模型切换、知识库链接
- 工具系统：内置
exec、文件读写、Web 搜索、定时任务、消息发送、MCP 工具接入 - MCP 集成：支持
stdio、sse、streamableHttp三类服务 - 知识库：支持多知识库、多文档格式、Embedding、Rerank、混合检索、来源引用
- 记忆系统：包含长期记忆、当前上下文、近期归档与会话持久化
- 审批与审计：支持高风险
exec审批、审计日志与会话级授权
核心链路可以概括为：
Web UI / Channel -> MessageBus -> AgentLoop -> Providers + Tools -> Session / Memory / Knowledge -> WebSocket / Channel Output
主要由三部分组成：
- Python 后端：负责 Agent 运行时、配置系统、知识库、记忆、会话和 API
- React 前端：负责聊天、设置中心、知识库、记忆中心、文件中心和定时任务
- Node Bridge：负责某些渠道桥接能力，例如 WhatsApp
- Python
3.11+ - Node.js
20+（源码运行 Web UI、前端开发或 WhatsApp Bridge 需要） - 推荐使用独立虚拟环境
如果你是从源码运行，建议先创建虚拟环境，避免和系统 Python 里的包互相影响。
Windows PowerShell
git clone https://gitee.com/sun124578963_0/TokenMind.git
cd TokenMind
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .macOS / Linux
git clone https://gitee.com/sun124578963_0/TokenMind.git
cd TokenMind
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .tokenmind onboard这一步会在 ~/.tokenmind/config.json 生成默认配置文件。
这里要分清楚两种运行方式：
pip install tokenmind-ai安装：前端构建产物已经打包进 Python 包里。git clone源码运行：仓库里通常不会提交frontend/dist，所以需要你自己先构建前端。
方式 A：pip 安装 / 桌面安装包
tokenmind web --port 18888然后打开 http://localhost:18888。
如果 18888 仍然被占用，可以换成任意空闲端口，例如：
tokenmind web --port 3000此时请打开 http://localhost:3000。
方式 B：源码生产模式，推荐给普通源码使用者
先构建 React 前端，再让后端 18888 直接托管构建后的页面：
cd frontend
npm install
npm run build
cd ..
tokenmind web --port 18888然后打开 http://localhost:18888。
如果浏览器里看到 {"detail":"Not Found"}，通常说明你是源码模式但还没有执行 npm run build，或者构建产物没有生成成功。重新执行上面的 cd frontend && npm install && npm run build 后再启动 tokenmind web --port 18888。
方式 C：源码开发模式，适合正在改前端
开发模式需要开两个终端。
终端 1：启动后端和 Agent 服务：
tokenmind web --port 18888终端 2：启动 Vite 前端开发服务器：
cd frontend
npm install
npm run dev然后打开 http://localhost:5173。Vite 开发服务器会自动代理 API 请求到后端 18888 端口。
如果后端使用了自定义端口，例如 tokenmind web --port 3000，前端开发服务器也要指定代理目标：
# PowerShell
$env:TOKENMIND_API_PROXY="http://localhost:3000"
npm run dev
# cmd
set TOKENMIND_API_PROXY=http://localhost:3000
npm run dev如果还没有配置 API Key，服务仍然会正常启动，但聊天功能暂不可用。
打开上一步对应的地址（pip/生产模式为 http://localhost:18888，源码开发模式为 http://localhost:5173），进入设置中心：
- 在 Providers 区域选择你要使用的模型提供商（如 OpenAI、Anthropic、DeepSeek 等）
- 填入对应的 API Key
- 在 Model 下拉框选择并启用模型
- 返回聊天页面，即可开始对话
也可以直接编辑
~/.tokenmind/config.json，在providers下对应的提供商字段中填入api_key。
修改前端后，如果想让后端 18888 直接提供最新页面，请重新构建：
cd frontend
npm install
npm run build
cd ..
tokenmind web --port 18888如果你想把 Agent 接到 Telegram、飞书等聊天渠道：
tokenmind gatewaycd bridge
npm install
npm run build启动后会显示二维码，用 WhatsApp 扫码登录。
如果要把 TokenMind 做成普通用户可双击安装的 Windows 程序，使用仓库内置的 PyInstaller + Inno Setup 流程。
构建机器需要先准备：
- Python 3.11+
- Node.js 20+
- Inno Setup 6
- PyInstaller：
python -m pip install ".[windows]"
然后在项目根目录运行：
.\packaging\windows\build-installer.ps1如果 PowerShell 执行策略拦截脚本，可以用：
powershell -ExecutionPolicy Bypass -File .\packaging\windows\build-installer.ps1脚本会自动执行：
- 构建
frontend/dist - 用 PyInstaller 生成
dist-windows\TokenMind\TokenMind.exe - 用 Inno Setup 生成安装包
dist-installer\TokenMindSetup-版本号.exe
最终交给用户的是 dist-installer 里的单个安装包 exe。用户安装后点击桌面图标即可启动 TokenMind，本机 Web UI 会自动打开；用户电脑不需要安装 Node.js。
如果只想测试 PyInstaller 产物，不生成安装包：
.\packaging\windows\build-installer.ps1 -SkipInstallerWeb UI 覆盖了日常使用的核心能力：
- 最近会话列表、搜索、重命名、删除
- 流式回复与停止生成
- 工具执行时间线与审批
- 设置中心（模型、提供商、API Key、运行时参数）
- 项目工作区（按项目组织会话）
- 记忆中心
- 定时任务
- 文件中心
- 知识库总览、详情、资料上传、检索配置
TokenMind 内置了轻量知识库能力，并且和聊天会话直接打通。
支持的能力包括：
- 新建多个知识库
- 每个知识库上传多种格式资料
- 文档切块、Embedding、Rerank、混合检索
- 聊天输入框下方手动“链接知识库”
- 只在用户主动链接后参与回答
- 回答附来源引用
支持的资料类型包括：
pdfdocxpptxxlsxmdtxt- 图片类资料（依赖解析链）
默认向量后端支持：
QdrantSQLite（轻量兜底）
Embedding 与 Rerank 模型支持用户自定义配置。
你可以通过两种方式管理模型配置：
- 在 Web UI 的设置中心里直接配置 Provider、模型、API Key 与运行时参数
- 手动编辑
~/.tokenmind/config.json
当前常见提供商包括但不限于：
| Provider | 示例模型 |
|---|---|
| OpenAI | gpt-4o |
| Anthropic | claude-sonnet-4-5 |
| Gemini | gemini-2.0-flash |
| DeepSeek | deepseek-chat |
| MiniMax | MiniMax-M2.7 |
| OpenRouter | anthropic/claude-sonnet-4-5 |
| Ollama | llama3.2 |
| SiliconFlow | Qwen/Qwen2.5-7B-Instruct |
| Qwen | qwen-max |
| GLM | glm-4 |
| Moonshot | kimi-k2.5 |
| 自定义 | default |
TokenMind 原生支持 MCP 服务接入，工具会自动注册到 Agent 工具集。
支持的接入方式：
stdiossestreamableHttp
接入后会暴露为统一工具名，例如：
mcp_minimax_web_search
mcp_minimax_understand_image
你可以在设置中心里：
- 管理 MCP 服务配置
- 限制暴露工具范围
- 查看连通状态
- 刷新并查看工具列表
TokenMind/
├─ tokenmind/ # Python 后端主包
│ ├─ agent/ # Agent 主循环、上下文构建、工具系统
│ ├─ bus/ # 消息总线与队列
│ ├─ channels/ # 聊天渠道接入
│ ├─ cli/ # 命令行入口
│ ├─ config/ # 配置模型与加载逻辑
│ ├─ cron/ # 定时任务
│ ├─ knowledge/ # 知识库与检索
│ ├─ providers/ # 模型提供商实现
│ ├─ server/ # FastAPI、WebSocket、Web channel
│ ├─ session/ # 会话与历史持久化
│ └─ skills/ # 内置技能
├─ frontend/ # React + Vite Web UI
├─ bridge/ # Node 渠道桥接服务
├─ tests/ # 后端测试
├─ README.md
└─ pyproject.toml
python -m pip install -e ".[dev]"
pytest -q
ruff check tokenmind/前端开发时打开 http://localhost:5173：
cd frontend
npm install
npm run dev如果要让 tokenmind web --port 18888 直接提供最新页面，需要生成生产构建：
cd frontend
npm install
npm run build
cd ..
tokenmind web --port 18888cd bridge
npm install
npm run buildTokenMind 比较适合这些使用方式：
- 想要一套能长期演进的个人 AI 助手框架
- 想把多模型、多工具、多渠道统一到同一个运行时
- 想做本地优先、私有部署的 Agent 工作台
- 想把知识库、记忆、会话、MCP 和工具链放到一个项目里统一管理
MIT