Khoj · 个人 AI 第二大脑 · Docker / Pip 自托管部署与使用全指南

项目仓库： https://github.com/khoj-ai/khoj

开源协议：GNU AGPL-3.0 · 服务端语言：Python（Django 体系） · 数据库：PostgreSQL + pgvector（Docker 方式内置） · 默认端口：42110 · 部署方式：Docker Compose 一键起服务，或 Pip 安装本地运行 · 仓库分支：master（命令、端口与环境变量以官方文档最新说明为准）

1 项目简介

Khoj 是一个面向个人使用的 AI 应用，定位为“你的 AI 第二大脑（Your AI second brain）”：它可以对话本地或在线大模型，从互联网与你自己的文档中检索答案，支持创建携带自定义知识、人设、聊天模型与工具的 Agent，并通过语义搜索快速找到相关资料。项目开源且始终支持自托管，可以只运行在自己的电脑上，也可以扩展到团队与企业级部署形态。

除 Web 应用外，Khoj 提供 Obsidian、Emacs、桌面端、手机端与 WhatsApp 等客户端入口，便于在日常写作与办公工具中直接调用。官方同时提供云端应用 app.khoj.dev 免注册体验；本文聚焦在自己服务器或本机上自托管开源服务端的部署方式。

非官方声明：Khoj 是独立开源项目，与 OpenAI、Anthropic、Google、Meta、Notion、WhatsApp 等第三方平台不存在隶属、授权或技术支持关系；应用内出现的厂商名称仅用于标识兼容对象。在线模型的能力、计费与数据政策由对应服务商规定。

1.1 核心信息一览

1.2 适用场景

• 把 Markdown、PDF、Word、Org-mode、Notion 等个人文档纳入统一检索与问答，在浏览器或笔记客户端中直接基于自己的资料提问。
• 希望对话模型与知识库都留在自己可控的机器上运行，敏感笔记与对话不经过第三方云端后台。
• 为不同角色创建自定义 Agent：各自携带知识范围、人设提示词、聊天模型与可用工具，承担写作、分析、研究助理等分工。
• 自动化重复的研究类任务，接收个人资讯简报与智能通知；通过语义搜索在历史文档中快速定位相关内容。
• 需要在 Obsidian、Emacs、桌面端、手机或 WhatsApp 等不同入口使用同一套个人 AI 服务。

1.3 能力边界（官方口径）

• 在线商业模型（OpenAI、Anthropic、Gemini 等）需要自行配置对应 API Key；离线 / 本地模型需要另行安装 OpenAI 兼容的本地推理服务（如 Ollama、vLLM、llama-cpp-server、LM Studio）。
• 文档读取支持 PDF、Markdown、Notion、Word、org-mode 等多种格式；Notion 工作区可直接从 Web 应用同步，本地文件与文件夹通过桌面端、Obsidian 或 Emacs 客户端同步。
• 视觉能力当前主要面向带视觉能力的 OpenAI 模型；其他模型的视觉能力在官方文档中标注为暂未利用。
• 自托管实例默认只允许本机访问；远程访问、公网暴露需要按官方远程访问文档配置域名、HTTPS 与环境变量。
• 企业版提供云服务、本地部署与混合方案，属于独立产品形态，以官网团队方案页面说明为准。

2 功能特性

以下功能条目来自官方 README 与文档目录，具体入口名称以当前版本界面为准。

2.1 模型对话

• 对话本地或在线大模型，官方列举的兼容对象包括 Llama 系列、Qwen、Gemma、Mistral、GPT、Claude、Gemini、DeepSeek 等。
• 在管理后台创建 AI Model API 与聊天模型，分别配置服务商密钥、接口地址、模型名称与模型类型；支持为带视觉能力的模型开启视觉开关。
• 可在服务端设置中选定默认聊天模型，用于意图识别、网页搜索等中间步骤。

2.2 文档与语义检索

• 从互联网与本地文档获取答案，支持图片、PDF、Markdown、Org-mode、Word、Notion 等资料类型。
• 基于语义搜索快速定位相关文档；资料通过桌面端、Obsidian、Emacs 客户端保持同步，也可在 Web 应用中拖拽上传文件。

2.3 Agent 与自动化

• 创建携带自定义知识、人设、聊天模型与工具的 Agent，承担特定角色任务。
• 自动化重复性研究工作，生成个人资讯简报并通过邮箱推送智能通知。

2.4 多端接入

• 除默认 Web 应用外，提供桌面端、Obsidian 插件、Emacs 包与 WhatsApp 入口；客户端设置中填写服务端主机地址即可接入同一实例。

2.5 创作与媒体工具

• 支持图像生成；支持语音朗读（Talk out loud）与播放消息。
• 服务端可集成代码沙箱运行代码，内置 SearXNG 网页搜索服务，也可对接外部网页搜索与网页阅读 API。

3 官方界面预览

3.1 聊天模型配置

管理后台中的 ChatModelOptions 面板：配置最大提示长度、订阅最大提示长度、分词器、聊天模型名称、模型类型与视觉开关，保存后供用户聊天选择。

3.2 模型服务商接口配置

创建 AI Model API 时填写友好名称、服务商 API Key 与可选 API Base URL；接口地址仅在对接 Ollama、LM Studio 等 OpenAI 兼容代理时需要填写。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Docker 方式：安装 Docker Engine 与 Docker Compose 工具；Windows 需先安装 WSL2 并在 WSL2 终端中执行部署命令。
• Pip 方式：本机已安装 Python 与 pip；本地离线模型扩展 khoj[local] 会涉及 llama-cpp-python 编译，需按操作系统准备对应的编译工具链。
• 在线模型 API Key（可选）：使用 OpenAI、Anthropic、Gemini 商业模型时，自备对应服务商密钥；本地模型则需要另行运行 Ollama、vLLM、LLM Studio 等 OpenAI 兼容服务。
• 客户端（可选）：桌面端、Obsidian 插件、Emacs 包、WhatsApp 接入按各自文档安装，服务端地址指向自托管实例。

5.2 硬件与系统建议（官方文档口径）

离线聊天模型的系统要求（来自官方自托管文档）：

仅使用在线商业模型时，本机不需要高端显卡；硬件压力由云端服务商承担。Docker 容器可用内存不足时，会在日志中出现进程被 Killed 的现象，需调大 Docker 资源上限。

5.3 端口与服务分配

默认情况下 Khoj 只允许本机访问；从其他机器访问需按官方远程访问文档配置 KHOJ_DOMAIN、KHOJ_ALLOWED_DOMAIN 与 HTTPS 相关变量，不要在匿名模式下直接把实例暴露到公网。

6 方式一：Docker Compose 一键部署（推荐）

6.1 下载编排文件

mkdir ~/.khoj && cd ~/.khoj
wget https://raw.githubusercontent.com/khoj-ai/khoj/master/docker-compose.yml

6.2 配置环境变量

编辑 docker-compose.yml 中 server 服务的 environment 段，按下表填写。

必填基础项：

在线模型密钥（按需填写其一或多个）：

本地模型对接：

• 取消 OPENAI_BASE_URL 注释，对接运行在宿主机上的 Ollama：http://host.docker.internal:11434/v1/；也可改为 vLLM、LM Studio、DeepInfra、DeepSeek 等其他 OpenAI 兼容接口地址。
• 可同时设置 KHOJ_DEFAULT_CHAT_MODEL 指定默认模型名（例如 Ollama 上已拉取的 qwen3）。

6.3 启动服务

cd ~/.khoj
docker-compose up

首次运行完成后重启一次服务，确保全部设置生效；终端日志中出现 🌖 Khoj is ready to engage in 即表示启动完成。浏览器打开 http://localhost:42110 开始使用，管理后台地址为 http://localhost:42110/server/admin。

6.4 Compose 服务构成

server 数据卷：khoj_config:/root/.khoj/（配置）、khoj_models:/root/.cache/torch/sentence_transformers 与 khoj_models:/root/.cache/huggingface（模型缓存）。服务启动命令为 --host="0.0.0.0" --port=42110 -vv --anonymous-mode --non-interactive。

7 方式二：Pip 本地安装运行

适用于不想使用 Docker、或需要在本机直接调试开发的场景。

7.1 安装服务端

确保本机已安装 Python 与 pip；如安装过程中遇到 llama-cpp 相关问题，先查阅 llama-cpp-python 官方编译说明。

macOS（Apple M1+）：

CMAKE_ARGS="-DGGML_METAL=on" python -m pip install 'khoj[local]'

macOS（Intel）：

python -m pip install 'khoj[local]'

Windows（PowerShell，按显卡选择）：

# CPU
py -m pip install 'khoj[local]'

# NVIDIA (CUDA) GPU
$env:CMAKE_ARGS = "-DGGML_CUDA=on"
py -m pip install 'khoj[local]'

# AMD (ROCm) GPU
$env:CMAKE_ARGS = "-DGGML_HIPBLAS=on"
py -m pip install 'khoj[local]'

# VULKAN GPU
$env:CMAKE_ARGS = "-DGGML_VULKAN=on"
py -m pip install 'khoj[local]'

Linux（按显卡选择）：

# CPU
python -m pip install 'khoj[local]'

# NVIDIA (CUDA) GPU
CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 python -m pip install 'khoj[local]'

# AMD (ROCm) GPU
CMAKE_ARGS="-DGGML_HIPBLAS=on" FORCE_CMAKE=1 python -m pip install 'khoj[local]'

# VULKAN GPU
CMAKE_ARGS="-DGGML_VULKAN=on" FORCE_CMAKE=1 python -m pip install 'khoj[local]'

7.2 启动服务

USE_EMBEDDED_DB="true" khoj --anonymous-mode

• --anonymous-mode 表示无需登录即可访问，适合本机单用户场景；需要账号认证时按官方认证文档配置。
• 首次运行会提示创建管理员账号（邮箱与密码），并选择要启用的聊天模型；准备好 OpenAI、Anthropic、Gemini 密钥与离线模型名称后再完成初始化。
• 日志出现 🌖 Khoj is ready to engage 后，打开 http://localhost:42110 使用。

7.3 开机自启（可选）

• Windows：使用任务计划程序配置后台自启。
• macOS / Linux：使用 Cron 的 @reboot khoj 方式实现开机自动运行。

8 配置项说明

8.1 Docker 服务端环境变量（docker-compose.yml）

8.2 管理后台模型配置口径

• OpenAI 类型：新建 AI Model API 并填入 OpenAI 密钥；可选填 API Base URL（仅对接 Ollama、LM Studio 等兼容代理时需要）；再新建聊天模型，model-type 选 OpenAI，填写聊天模型名（如 gpt-4o），带视觉能力的模型再开启 vision enabled。
• Anthropic 类型：新建 AI Model API 填入 Anthropic 密钥，不要填写 API Base URL；新建聊天模型时 model-type 选 Anthropic 并绑定对应 AI Model API。
• Google 类型：新建 AI Model API 填入 Gemini 密钥，不填 Base URL；新建聊天模型时 model-type 选 Google 并绑定 API。
• 离线 / 本地模型：先在管理后台添加 AI Model API，api url 填本地服务地址（如 Ollama 的 http://localhost:11434/v1/）；保存后重启服务端加载可用模型；未自动列出时手动新建聊天模型，再在用户聊天设置中选为偏好模型。
• tokenizer 与 max-prompt-size 为可选项，仅在明确知道模型分词器与上下文上限时填写，用于避免上下文填充溢出。

8.3 客户端连接

桌面端、Obsidian、Emacs、WhatsApp 客户端在设置页填写服务端主机地址；默认可用 http://127.0.0.1:42110 或 http://localhost:42110；个别场景下 localhost 不可用，改用回环 IP。

9 常用运维命令

9.1 Docker 方式

# 前台启动并查看日志
cd ~/.khoj
docker-compose up

# 后台启动
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看实时日志
docker-compose logs -f

# 停止服务（保留数据卷）
docker-compose down

# 升级到最新版本（重新拉取镜像构建）
docker-compose up --build

# 停止并删除容器、网络、镜像与数据卷（卸载用，谨慎执行）
docker-compose down --volumes

9.2 Pip 方式

# 升级服务端到最新版本
pip install --upgrade khoj

# 安装预发布版本
pip install --upgrade --pre khoj

# 卸载服务端
pip uninstall khoj

# 删除 PostgreSQL 数据库（外部独立数据库场景）
dropdb khoj -U postgres

9.3 备份要点

• Docker 方式下，配置与模型缓存保存在 khoj_config、khoj_models 与 khoj_db 三个命名数据卷中；升级前备份对应数据卷即可。
• 个人文档同步以本地源文件为准，定期备份原始笔记与文档；Khoj 服务端保存的是检索索引与对话记录。

10 常见故障排查

10.1 Pip 安装时依赖版本冲突

• 原因：Khoj 与系统中其他 Python 包要求的依赖版本不一致。
• 处理：使用 venv 独立虚拟环境安装；或使用 pipx 隔离安装：

pipx install khoj
# 之后按标准步骤启动 khoj

10.2 构建 tokenizers 依赖时报 Rust 错误

• 原因：tokenizers 包需要 Rust 工具链编译。
• 处理：先安装 Rust，以 macOS 为例：

brew install rustup
rustup-init
source ~/.cargo/env

完成后重新执行安装命令；其他系统参考 Rust 官方安装说明。

10.3 Docker 日志中服务进程被 Killed

• 原因：分配给 Docker 容器的内存不足。
• 处理：在 Docker Desktop 的资源设置中调大内存上限后重启 Compose 服务。

10.4 管理后台 CSRF 报错或 Cookie 异常

• 访问管理后台请使用 localhost，不要用 127.0.0.1，以避免 CSRF 校验报错。
• 前置负载均衡 / 反向代理时，设置 KHOJ_ALLOWED_DOMAIN 为内网可访问的域名或 IP；不设置时默认回退 KHOJ_DOMAIN。

10.5 自定义域名访问报 DISALLOWED HOST 或 400 Bad Request

• 通过自定义 IP / 域名或 HTTP 暴露实例时，设置 KHOJ_DOMAIN=<外部 IP 或域名>（不带协议前缀）；必要时设置 KHOJ_NO_HTTPS=True。

10.6 本地模型在后台列表中不出现

• 先确认本地 OpenAI 兼容服务已启动且地址可被服务端访问；Docker 方式对接宿主机 Ollama 时使用 host.docker.internal，而非 localhost。
• 保存 API 配置后重启 Khoj 服务端加载模型；仍未列出时手动新建聊天模型并填写模型名。
• 确认本地服务已拉取对应模型权重，且模型名称与配置中填写一致。

10.7 macOS 上无法登录管理后台

• Safari 浏览器可能出现登录兼容问题，改用 Chrome 或 Firefox 访问后台。

10.8 文档同步不生效

• 确认对应客户端已安装并指向正确服务端地址；桌面端、Obsidian、Emacs 分别维护各自的文件同步配置；Notion 工作区在 Web 应用中直接授权同步。

11 风险与合规说明

• 开源协议义务：Khoj 服务端以 GNU AGPL-3.0 协议发布；修改后通过网络向用户提供服务时，须按 AGPL-3.0 要求开放对应修改源码；二次开发与商用前请阅读协议全文。
• 第三方模型与平台条款：在线模型调用受对应服务商密钥额度、计费、内容政策与隐私条款约束；接入 Notion、WhatsApp 等第三方平台需遵守其开发者与使用规则。
• 数据隐私：自托管的核心价值是数据留在自己可控环境内；配置 KHOJ_ADMIN_PASSWORD 与 KHOJ_DJANGO_SECRET_KEY 时请使用随机强值；公网暴露前补齐认证、HTTPS 与访问控制，避免匿名模式下个人文档被未授权访问。
• 本地模型与生成内容：本地模型的能力与输出质量由所选模型权重决定；AI 生成内容可能存在错误或偏见，涉及个人决策、法律与财务场景须人工复核。
• 遥测与第三方 API：框架内置匿名遥测，可设置 KHOJ_TELEMETRY_DISABLE=True 关闭；搜索与阅读类第三方 API（Serper、Olostep、Firecrawl、Exa）各自有独立额度与隐私政策，按需开启。
• 企业版边界：团队级权限管理、共享知识库与私有化部署属于官方企业方案；社区自托管实例不自带这些团队管理能力。