Khoj 桌面端接入全指南Companion App 同步你的知识库与 PWA 桌面安装【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khojKhoj 的桌面端由两种形态组成基于 Electron 的 Companion App用于把本地文件、文件夹持续同步到 Khoj 服务端让你的搜索与对话能感知整个语料库和以渐进式 Web AppPWA方式运行的 Khoj 主应用。本文以仓库内 官方客户端文档 为骨架结合 桌面端源码 与 服务端内容索引 API完整讲解两种形态的安装、配置、自托管对接、文件同步原理与常见问题排查读完即可在个人电脑上把 Khoj 变成随叫随到的第二大脑。Companion App把本地文件变成本地知识库Companion App 是 Khoj 为桌面用户提供的一个独立伴随程序。它的核心职责是让你通过界面把本地文件和文件夹共享给 Khoj由 App 自动追踪这些文件的变更并持续同步到 Khoj 服务端进行索引之后你在 Khoj 中搜索或对话时Khoj 就能基于这些最新内容给出带上下文的回答。换句话说它把打开终端手动喂文件变成了选中目录后自动保持同步。在仓库中这段逻辑完整实现了 Companion App 的入口主进程Electron 的 main 进程、设置页界面 与 渲染层状态逻辑 三部分源码即是最好的功能说明书。安装与配置Setup官方文档给出的标准接入流程分为三步适用于连接 Khoj 云端服务app.khoj.dev的场景安装应用根据你的操作系统下载安装 Khoj Desktop App即 Companion App。生成 API Key登录 Khoj Web App进入设置页中的客户端管理区域生成一个 API Key。填入 Key 并保存打开 Desktop App 的Settings页面在API Key输入框中填入刚才生成的 Key。可选添加同步内容在Settings页面中通过Add File / Add Folder添加你希望 Khoj 感知的文件或文件夹然后点击保存。此后这些内容会被自动保持同步。说明上述步骤中涉及 Web App 的操作均需在浏览器中访问 Khoj 官方提供的托管服务完成本仓库源码对应的是可自托管的 Khoj 服务端部分。自托管时如何对接Self Hosting如果你运行的是自己部署的 Khoj 服务端需要在 Desktop App 的Settings页面做两处关键调整见 官方文档 中的 Self Hosting 提示Khoj URL 字段填写你的 Khoj 服务器地址。默认情况下本地默认端口使用http://127.0.0.1:42110。Khoj API Key 字段如果你的 Khoj 服务端运行在匿名模式下不要填写 API Key。例如以如下命令启动服务端即处于匿名模式khoj --anonymous-mode从源码侧可以印证这两点的含义设置页为 URL 和 Key 分别提供了独立输入框settings.html 中的khoj-host-url与khoj-access-key在输入 URL 失焦保存时渲染层会先用new URL()校验合法性renderer.js而主进程保存时还会做规范化处理——去除末尾/并在缺少协议前缀时自动补上http://// src/interface/desktop/main.jssetURL url url.replace(/\/$/, ); if (!url.match(/^[a-zA-Z]:\/\//)) { url http://${url}; } store.set(hostURL, url);服务端侧--anonymous-mode是官方支持的启动选项见 Khoj App 运行说明 中的python3 src/khoj/main.py --anonymous-mode。在 configure.py 中可以看到当state.anonymous_mode为真时认证逻辑会直接放行并且 路由装配逻辑 会跳过 auth 路由的注册——这就是匿名模式下无需 API Key的底层原因。设置页字段速查Companion App 的Settings页面字段含义如下界面结构与字段均对应 settings.html字段 / 按钮含义备注Server URLKhoj 服务端地址默认云端为https://app.khoj.dev源码常量KHOJ_URL自托管时改为http://127.0.0.1:42110API Key访问 Khoj 的令牌云端模式必填自托管匿名模式必须留空Files需要同步的单个文件列表通过Add File添加可逐个移除Folders需要同步的文件夹列表通过Add Folder添加会递归扫描其中受支持的文件Force Sync强制全量重建索引触发服务端全量重建源码中对应syncData(true)Delete All清空所有已索引内容清空文件/文件夹配置并让服务端删除索引设置页还会展示每个文件/文件夹的同步状态图标已同步 / 未同步并显示最近同步时间与下次同步时间见 renderer.js 的update-state回调。同步机制与源码级原理Companion App 的同步并非简单的上传一次而是一个由配置收集 → 增量比对 → 批量请求 → 定时触发组成的闭环。读懂 main.js 就能完全掌握它。1. 配置持久化结构App 使用electron-store持久化配置其 schema 定义了以下字段{ files: [{ path }], // 用户添加的文件 folders: [{ path }], // 用户添加的文件夹 khojToken: , // API Key hostURL: , // 服务端地址 lastSync: [{ path, datetime }] // 每个文件最近一次成功同步的时间 }lastSync是增量同步的基石——它记录了每个文件上次成功上传的时间戳用于判断哪些文件需要再次上传。2. 收集阶段递归扫描与文件类型过滤主进程pushDataToKhoj()会把配置中的文件与文件夹汇总成待上传列表对文件直接检查其是否存在不存在则跳过并告警对文件夹通过processDirectory()递归遍历main.js自动跳过以.开头的隐藏文件与隐藏目录只收录受支持扩展名的文件遇到权限错误EACCES、路径不存在ENOENT等异常会打印错误并跳过。受支持的文件类型在源码中定义得很明确默认的 Khoj 文本文档类型org/md/markdown/txt/html/xml加上从 Magika 模型配置衍生的文本扩展名如c/css/csv/go/java/javascript/json/python/rust/sql/yaml等几十种再叠加二进制文档类型pdf/jpg/jpeg/png/webp详见 main.js 中的textFileTypes与binaryFileTypes。3. 增量同步只上传有变化的内容收集到完整文件列表后App 会比对lastSync记录跳过自上次同步以来未被修改的文件// 仅当文件修改时间晚于上次同步时间时才重新上传 if (stats.mtime.toISOString() lastSync.find(syncedFile syncedFile.path file)?.datetime) { continue; }对于已被删除的同步文件存在于lastSync但不在本次收集结果中App 会生成一个空 Blob 上传通知服务端把该文件从索引中移除。4. 上传阶段按 MIME 识别 千文件分批每个待上传文件会按扩展名映射为合适的 MIME 类型pdf→application/pdf、png→image/png、jpg/jpeg→image/jpeg、webp→image/webp、md/markdown→text/markdown、org→text/org其余文本默认text/plain其中文本类会追加; charsetUTF-8见 main.js 的filenameToMimeType。上传请求以每批最多 1000 个文件的方式发送到{hostURL}/api/content?clientdesktop请求携带Authorization: Bearer {khojToken}头并使用不同的 HTTP 方法区分语义场景方法服务端对应实现常规增量同步PATCHapi_content.py 中的patch_contentForce Sync 全量重建PUTapi_content.py 中的put_content请求成功后将本次上传成功的文件及其时间戳写回lastSync为下一轮增量比对做准备。5. 触发时机启动、定时器与手动同步在三种情况下被触发均可从 main.js 得到印证应用启动时主进程一启动就会调用一次pushDataToKhoj()每 10 分钟App 注册了 cron 任务表达式0 */10 * * * *周期性执行同步手动触发设置页的Force Sync按钮对应syncData(true)会以PUT做全量重建Delete All则清空文件/文件夹配置后同样触发同步让服务端清除全部索引。主应用以 PWA 形式把 Khoj 装到桌面除了 Companion App你还可以把 Khoj 主应用以**渐进式 Web AppPWA**的形式安装到桌面。它本质上复用了 Khoj 的 Web 前端仓库中 Next.js Web 应用 即服务端渲染并自带 PWA 清单因此能得到原生窗口、独立图标、离线资源缓存等类原生体验而无须单独下载客户端。方式一通过浏览器地址栏安装推荐用 Chrome 打开 Khoj Web App登录后使用。点击地址栏中的安装按钮把应用安装到桌面。需要说明的是这种方式要求你的 Chrome 浏览器处于登录状态文档中的原话为必须登录你的 Chrome 浏览器。方式二通过浏览器菜单安装如果你在地址栏没有看到安装入口也可以走菜单路径点击浏览器右上角的三点菜单进入Cast、Save 和 Share投射、保存和分享选项组点击其中的Open in Khoj在 Khoj 中打开 / 安装选项。安装完成后桌面上会出现独立的 Khoj 应用入口你可以像使用普通桌面软件一样启动它进行对话、搜索与知识库管理。仓库中面向 Android 的 TWA 封装见 web_app_manifest.json也进一步印证了 Khoj 围绕 Web 清单构建跨端应用的技术路线。状态反馈与故障排查当同步异常时App 会通过设置页的状态区与文件图标给出反馈renderer.js失败的同步会把文件图标切换为file-not-synced.svg并把错误信息展示在同步状态栏。以下常见问题均可从 main.js 的错误处理分支中找到答案现象源码判断说明与建议提示无法连接 Khoj 服务器ECONNREFUSED确认Settings中的 Server URL 是否可达自托管场景核对http://127.0.0.1:42110是否拼写正确、服务是否已启动提示空间不足需要升级套餐HTTP429云端场景同步容量已达上限需在订阅设置中扩容自托管无计费不受此限制提示同步失败其他异常可查看主进程控制台日志定位必要时反馈给官方支持邮箱某个文件没有进入索引收集阶段被过滤检查扩展名是否在受支持列表中、是否位于隐藏目录下或文件路径是否存在另外主进程 会为应用窗口注入严格的内容安全策略CSP仅放行自建域与hostURL对应域因此当自定义 Server URL 指向第三方域时部分内嵌资源可能受限——这也提醒你尽量使用自托管的官方服务或受信任地址。从源码运行与构建桌面端仓库的 桌面端目录 本身就是可直接运行的最小 Electron 工程适合想深入调试或二次开发的读者详见该目录下的 README。# 安装依赖会安装全部开发依赖 yarn install # 本地启动 Companion App yarn start工程配置方面package.json主进程入口为main.jsElectron 版本以 devDependencies 锁定运行时依赖包括axiosHTTP 请求、cron定时同步、electron-store本地配置持久化与todesktop/runtime自动更新。除设置页外App 还内置了shortcut.html全局快捷查询窗口快捷键Command/CtrlShiftK可直接把选中文本发给 Khoj、系统托盘菜单与关于页这些 UI 均通过 preload.js 暴露的安全桥接接口与主进程通信。小结综合官方 Desktop 客户端文档 与仓库源码可以看到 Khoj 桌面体验的完整闭环Companion App 负责把本地文件以配置 增量比对 千文件分批 每 10 分钟轮询的可靠方式持续同步到服务端自托管场景只需把 Server URL 指向http://127.0.0.1:42110并按匿名模式留空 API Key而 PWA 形态的 Khoj 主应用则把完整的对话与检索体验搬到了桌面。按照本文的两种安装路径与排查表操作即可快速让 Khoj 感知你机器上的全部知识内容。【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khoj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考