LocalGPT

使用自然语言构建可探索的3D世界——包括几何体、材质、光照、音频和行为。开源，可在本地运行。

安装

# 世界构建
cargo install localgpt-gen

# AI 助手（聊天、记忆、守护进程）
cargo install localgpt

生成模式（世界构建）

localgpt-gen 是一个独立的二进制文件，用于借助 Bevy 游戏引擎进行AI驱动的3D世界创建。

# 启动交互模式
localgpt-gen

# 使用初始提示启动
localgpt-gen "创建一个有金字塔和UFO悬浮其上的沙漠场景"

# 加载现有场景
localgpt-gen --scene ./world.glb

# 详细日志记录
localgpt-gen --verbose

特性

• 参数化形状 — 立方体、球体、圆柱体、胶囊体、平面、环面、金字塔、四面体、二十面体、楔形体
• PBR 材质 — 颜色、金属度、粗糙度、自发光、透明度、双面
• 光照 — 点光源、聚光灯、方向光，支持颜色和强度调节
• 行为 — 轨道运动、自转、上下摆动、注视目标、脉冲效果、沿路径移动、反弹
• 音频 — 环境音效（风声、雨声、森林声、海浪声、洞穴声）以及空间声源
• 导出 — glTF/GLB 格式、HTML（可在浏览器中查看）、截图
• 世界技能 — 可将完整的世界保存为可复用的技能并加载

无头模式与实验队列

将世界生成实验排队，在没有窗口的情况下进行生成——适合夜间批量运行、CI 流水线或脚本化的变体：

# 生成单个世界（无窗口）
localgpt-gen headless --prompt "建造一座位于雪地森林中的舒适小屋"

# 带风格提示
localgpt-gen headless --prompt "村庄集市" --style "吉卜力工作室"

记忆系统会在不同会话中学习你的创作风格——配色方案、光照偏好、实体模板等，并在未来的生成中自动应用。

完整文档：无头模式与实验队列

MCP 服务器

从任何兼容 MCP 的工具中使用生成功能（Claude CLI、Codex CLI、Gemini CLI、VS Code、Zed、Cursor）：

localgpt-gen mcp-server

将其添加到你的 .mcp.json 文件中：

{
  "mcpServers": {
    "localgpt-gen": {
      "command": "localgpt-gen",
      "args": ["mcp-server"]
    }
  }
}

当通过 CLI 后端交互式使用生成功能时，可以使用 --connect 参数，将工具调用路由到你现有的窗口，而不是再打开一个新的窗口。详情请参阅 CLI 模式（MCP 中继）。

完整文档：LocalGPT 生成 | MCP 服务器

如果你创造了什么酷炫的东西，请在 Discord 或 YouTube 上分享吧！

---

AI 助手

localgpt 是一款以本地优先的AI助手，具备持久化记忆、自主任务处理能力以及多种界面。

# 交互式聊天
localgpt chat

# 单一问题
localgpt ask "生命的意义是什么？"

# 作为守护进程运行，提供 HTTP API 和 Web UI
localgpt daemon start

为什么选择 LocalGPT？

• 单个二进制文件 — 无需 Node.js、Docker 或 Python
• 专注于本地设备 — 完全在你的机器上运行，数据始终属于你
• 持久化记忆 — 基于 Markdown 的知识库，支持全文和语义搜索
• 混合网络搜索 — 原生提供商搜索直通，同时具备客户端侧回退机制
• 自主心跳机制 — 将任务委托给它，让它在后台工作
• 多种界面 — CLI、Web UI、桌面 GUI、Telegram 机器人
• 纵深防御安全 — 签名策略文件、内核强制沙盒、提示注入防御
• 多模型提供商 — LM Studio、Ollama、Anthropic、OpenAI、xAI、GLM、Vertex AI、CLI 提供商

工作原理

LocalGPT 使用符合 XDG 规范的目录来存储配置、数据、状态和缓存。运行 localgpt paths 可查看解析后的路径。

工作区内存布局如下：

<workspace>/
├── MEMORY.md     # 长期知识（每次会话自动加载）
├── HEARTBEAT.md  # 自主任务队列
├── SOUL.md       # 个性与行为指导
└── knowledge/    # 结构化知识库

这些文件通过 SQLite FTS5 进行关键词搜索，并利用 sqlite-vec 实现基于本地嵌入的语义搜索。

配置

存储在 <config_dir>/config.toml 文件中：

通过 LM Studio 使用本地模型（无需 API 密钥，完全离线）：

[agent]
default_model = "openai/qwen/qwen3.5-35b-a3b"

[providers.openai]
api_key = "lm-studio"
base_url = "http://127.0.0.1:1234/v1"

云端提供商（Anthropic、OpenAI 等）：

[agent]
default_model = "claude-cli/opus"

[providers.anthropic]
api_key = "${ANTHROPIC_API_KEY}"

完整配置参考：website/docs/configuration.md

安全性

• 内核强制沙盒 — Linux 上的 Landlock/seccomp，macOS 上的 Seatbelt
• 签名策略文件 — 使用 HMAC-SHA256 签名的 LocalGPT.md 文件，具备篡改检测功能
• 提示注入防御 — 标记剥离、模式检测、内容边界控制
• 审计链 — 哈希链式安全事件日志

安全文档：website/docs/sandbox.md | website/docs/localgpt.md

HTTP API

端点	描述
GET /	内嵌 Web UI
POST /api/chat	与助手聊天
POST /api/chat/stream	SSE 流式聊天
GET /api/memory/search?q=<query>	搜索记忆

完整 API 参考：website/docs/http-api.md

CLI 命令

localgpt chat                   # 交互式聊天
localgpt ask "question"         # 单一问题
localgpt daemon start           # 启动守护进程
localgpt memory search "query"  # 搜索记忆
localgpt config show            # 显示配置
localgpt paths                  # 显示解析后的路径

完整 CLI 参考：website/docs/cli-commands.md

博客

• 可探索的世界作为智能体技能
• 为什么我在4个晚上内构建了LocalGPT

技术栈

Rust、Tokio、Axum、Bevy、SQLite（FTS5 + sqlite-vec）、fastembed、eframe

贡献者

许可证

Apache-2.0

LocalGPT 快速上手指南

LocalGPT 是一款开源的本地优先 AI 工具集，包含两个核心组件：

1. localgpt-gen：基于自然语言生成可探索的 3D 世界（使用 Bevy 引擎）。
2. localgpt：具备持久记忆、自主任务能力的本地 AI 助手。

环境准备

• 操作系统：支持 Linux、macOS 和 Windows。
• 前置依赖：
  • 必须安装 Rust 工具链（包含 cargo）。
    • 安装命令：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • 图形驱动：若使用 localgpt-gen 进行 3D 渲染，请确保显卡驱动正常。
  • 模型服务（可选）：若需完全离线运行 AI 助手，建议安装 LM Studio 或 Ollama 并在本地启动模型服务。

注意：目前国内暂无官方指定的 Rust crate 镜像加速方案，若 cargo install 下载缓慢，可尝试配置国内 Cargo 源（如清华源或中科大源）或在终端设置 CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse 以提升解析速度。

安装步骤

LocalGPT 分为两个独立的二进制文件，请根据需求选择安装：

1. 安装 3D 世界生成器 (Gen Mode)

用于通过自然语言构建 3D 场景。

cargo install localgpt-gen

2. 安装 AI 助手 (AI Assistant)

用于本地聊天、记忆管理和后台自主任务。

cargo install localgpt

基本使用

场景一：使用 natural language 构建 3D 世界

交互式生成 直接运行命令进入交互模式，输入提示词即可开始创作：

localgpt-gen

一键生成指定场景 直接在命令行传入提示词，例如创建一个沙漠场景：

localgpt-gen "Create a desert scene with pyramids and a UFO hovering above"

无头模式（Headless Mode） 适用于脚本批量生成或 CI 流程，不弹出窗口：

localgpt-gen headless --prompt "Build a cozy cabin in a snowy forest" --style "Studio Ghibli"

加载现有场景

localgpt-gen --scene ./world.glb

---

场景二：使用本地 AI 助手

交互式对话 启动终端聊天界面：

localgpt chat

单次问答 快速询问一个问题并退出：

localgpt ask "What is the meaning of life?"

以守护进程模式运行 启动后台服务，开启 HTTP API 和 Web UI 界面：

localgpt daemon start

启动后，可在浏览器访问默认端口（通常为 http://localhost:PORT，具体见启动日志）使用图形界面。

配置本地模型（推荐离线使用） 编辑配置文件（运行 localgpt config show 查看路径），在 <config_dir>/config.toml 中添加本地模型提供商（如 LM Studio）：

[agent]
default_model = "openai/qwen/qwen3.5-35b-a3b"

[providers.openai]
api_key = "lm-studio"
base_url = "http://127.0.0.1:1234/v1"

注：确保本地已启动 LM Studio 并加载了相应模型。

查看记忆与路径 搜索本地知识库或查看文件存储路径：

localgpt memory search "query"
localgpt paths