Eigent 如何只使用本地模型和本地 MCP 服务器实现完全离线运行

Eigent 如何只使用本地模型和本地 MCP 服务器实现完全离线运行

【免费下载链接】eigent Eigent: The Open Source Cowork Desktop – Local and Free Alternative to Claude Cowork and Codex 项目地址: https://gitcode.com/GitHub_Trending/ei/eigent

Eigent 的本地部署模式可以不依赖任何云服务运行：后端服务（FastAPI + PostgreSQL）完整跑在你的机器上，模型来自本地推理服务（vLLM、Ollama、LM Studio 等），工具能力来自本地运行的 MCP 服务器。官方文档对离线原则的表述是："For a fully offline environment, only use local models and local MCP servers, and avoid configuring any external Providers or remote MCP addresses"（见 server/README_EN.md 末尾）。本文按仓库文档走通这套部署：启动本地后端、把前端切到本地模式、配置本地模型 Provider、导入本地 MCP，并给出验证方式。

适用环境（来自 server/README_EN.md 的 Prerequisites）：

• Docker Desktop：已安装并运行；
• Python：3.12.*（推荐 3.12.0 或更高）；
• Node.js：>=18.0.0 <23.0.0；
• 一个对外提供 OpenAI 兼容 API 的本地推理服务（Ollama、vLLM、LM Studio 等，README.md 在本地部署一栏列出的集成对象）；
• 你要接入的本地 MCP 服务器进程。

启动本地后端

在 server/ 目录下创建 .env 并启动容器（PostgreSQL、Redis、FastAPI API）：

cd server
# Copy .env.example to .env(or create .env according to .env.example)
cp .env.example .env
# Environment variables from .env are automatically passed to Docker images
docker-compose up –build -d

几个要点：

• .env 基于 server/.env.example 创建，其中定义的环境变量会自动传入 Docker 镜像；
• 数据库迁移（Alembic）在容器启动时自动执行，不需要手动建库；
• 端口映射（见 server/docker-compose.yml）：API 为宿主 3001 → 容器 5678，PostgreSQL 为宿主 5432 → 容器 5432。

验证：docker ps 能看到 eigent_api、eigent_postgres 等容器在运行；打开 http://localhost:3001/docs 能加载 Swagger UI。这个地址是后续所有接口核对的入口。

把前端指向本地后端

项目根目录自带的 .env.development 默认是云连接配置（VITE_USE_LOCAL_PROXY=false、VITE_PROXY_URL 指向 dev.eigent.ai）。按 server/README_EN.md 的说明，需要修改它启用本地模式并指向本地后端：

VITE_BASE_URL=/api
VITE_USE_LOCAL_PROXY=true
VITE_PROXY_URL=http://localhost:3001

然后在项目根目录启动前端：

npm install
npm run dev

注册本地账号并配置本地模型 Provider

模型与 MCP 的管理接口都需要登录态。先用 POST /register（邮箱 + 密码）在本地数据库中创建账号，再用 POST /login 获取本地签发的 token——两者都只落本地库（server/README_EN.md 的 Users & Accounts 一节）。

创建模型 Provider 用 POST /provider（provider_controller.py）。请求体字段由 ProviderIn 定义（provider.py）：

前端内置的 Provider 模板中有 "OpenAI Compatible"（id 为 openai-compatible-model，描述为 "OpenAI-compatible API endpoint configuration"，见 llm.ts），Ollama、vLLM、LM Studio 这类本地服务就通过该方式接入：把 endpoint_url 填成本地推理服务对外暴露的 OpenAI 兼容端点地址，其余字段按你的本地服务填写。

创建成功后，调用 POST /provider/prefer（请求体为 {"provider_id": <id>}，<id> 替换为创建接口返回的 Provider id）将其设为首选，前端与后端都会优先使用它。

注意：离线运行期间不要创建任何云端模型 Provider。文档明确说明，配置外部模型后，相关请求会发往你指定的第三方服务，这会破坏完全离线。

导入本地 MCP 服务器

MCP 导入接口为 POST /mcp/import/{Local|Remote}（mcp_controller.py）。接入本地运行的 MCP 服务器时走 local 分支，请求体字段由 McpLocalImport 定义（mcp_user.py）：

{
"command": "<本地 MCP 服务器进程的启动命令>",
"args": ["<启动参数，按实际填写>"],
"env": {}
}

• command / args / env 分别对应 MCP 服务器进程的启动命令、参数和环境变量，按你自己本地 MCP 服务器的实际启动方式替换尖括号内的值；
• remote 分支对应的是 server_url（远程 MCP 服务地址）——完全离线环境下应当避免配置任何远程 MCP 地址。

验证离线状态

• 调用 GET /mcps 查看已导入的 MCP 列表（支持 mine 参数按当前用户筛选），确认导入的都是本地类型；
• 调用 GET /providers 查看 Provider 列表，确认 endpoint_url 均指向本地地址，且只有本地 Provider 被设为首选；
• 以上核对都可以在 http://localhost:3001/docs 的 Swagger UI 中交互完成。

验证通过后，用户注册、模型 Provider 配置、工具设置、聊天历史这些数据都存储在本机 PostgreSQL 的 Docker 卷 server_postgres_data 中；只有在显式配置外部服务（云端模型或远程 MCP）时，请求才会发往第三方。

限制与常用操作

• App triggers 在离线模式下不可用：incoming webhook 触发器要求外部服务能通过 HTTPS 回调地址访问你的服务器，即需要公网可达域名（文档提到本地开发可用 ngrok 暴露）。完全离线环境不满足这一前提，该功能无法工作。
• 云连接快速启动模式需要注册 Eigent 账号，与本地部署是两条独立路径；本文只覆盖离线这一条。
• 常用运维命令（server/README_EN.md）：

# 查看 API 容器日志
docker logs -f eigent_api | cat

# 重启 API 容器（保留数据库）
docker stop eigent_api
docker start eigent_api

【免费下载链接】eigent Eigent: The Open Source Cowork Desktop – Local and Free Alternative to Claude Cowork and Codex 项目地址: https://gitcode.com/GitHub_Trending/ei/eigent

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考