<!-- Generated from zh-CN/docs.html. Do not edit by hand. -->

> Markdown twin of https://conduitllm.com/zh-CN/docs.html
> 安装 Conduit、添加第一个提供商、连接 MCP 工具、从源码构建，并排查常见问题。

---
文档

# 快速开始

Conduit 是一个桌面应用。它没有可登录的托管版本，你是在自己的机器上运行它，并使用自己的提供商密钥。

## 安装

安装包位于 [GitHub Releases](https://github.com/runningpixels/conduit/releases) 页面，当前打好标签的构建版本是 **v1.0.0-rc.7**，适用于 Windows、macOS 和 Linux。你也可以从源码构建；如果机器上已经装好工具链，整个过程大约需要五分钟。

### 前置要求

| 要求 | 版本 | 说明 |
| --- | --- | --- |
| Node.js | 20 | CI 当前基于此版本构建 |
| pnpm | 10.34.4 | 已固定版本；最简单的方式是执行 `corepack enable` |
| Rust | stable | 通过 `rustup` 安装，并带上 `rustfmt` 和 `clippy` |
| Visual Studio 2022 Build Tools | — | 仅 Windows 需要，用于本地编译 |

在 Windows 上，仓库自带 `check-setup.ps1`，会检查这四项并告诉你缺了什么。

### 构建并运行

terminal

```
git clone REPO_URL conduit
cd conduit
pnpm install
pnpm dev
```

`pnpm dev` 会先启动 Vite 开发服务器，然后启动桌面 shell。第一次 Rust 构建会比较慢，后续构建则是增量的。

| 命令 | 作用 |
| --- | --- |
| `pnpm dev` | 以开发模式运行应用 |
| `pnpm build` | 为你的平台生成原生安装包 |
| `pnpm check` | 对 TypeScript workspace 做类型检查 |

### 支持的平台

- **Windows 10 / 11** — x86_64，NSIS 安装包，无需管理员权限
- **macOS 11 Big Sur 及更高版本** — 面向 Apple silicon 和 Intel 的通用二进制
- **Linux** — Ubuntu 20.04+ 提供 `.deb` 和 AppImage；其他发行版尽力支持

**这些二进制文件还没有操作系统级代码签名。** macOS Gatekeeper 和 Windows SmartScreen 会在首次启动时发出警告，因为这些安装包目前没有操作系统级签名。自动更新包*会*单独签名并验证。从源码构建则可以完全绕过这个警告。

## 第一次对话

在 Conduit 有能力访问模型之前，它不会让你开始聊天。首次启动时，引导流程会让你选择一个提供商，并提供相应凭据。

### 使用托管提供商

1. 打开 **Settings → Providers & Keys**（⌘,）。
2. 选择你的提供商，并粘贴其 API 密钥。
3. 从 Conduit 通过该提供商拉取到的列表中选择一个模型。

这把密钥会进入你的操作系统凭据存储，即 Windows 凭据管理器、macOS 钥匙串或 Linux Secret Service。Settings（设置）里只保存一个引用，从不保存实际值。在没有钥匙串的机器上，也可以显式选择使用加密的文件型存储。

### 使用本地模型，无需密钥

安装 [Ollama](https://ollama.com) 或 LM Studio，拉取一个模型，然后在设置里选择对应提供商。这样不需要凭据，也不会有任何内容离开你的机器。配合仅本地模式（会彻底拒绝云端提供商）使用时，Conduit 完全不会发出互联网请求。

当模型支持视觉能力时，你可以附加图片。你可以编辑任意一条消息并重新发送：编辑最新一条消息会原地改写它，而编辑更早的消息则会从那一点分叉出一段新对话，原对话保持不变。你还可以将对话导出为 Markdown 或 JSON。

### 支持的提供商

内置提供商共有 17 个——兼容 OpenAI 的端点就是第 17 个，不是额外加上去的。

| 提供商 | 凭据 | Base URL |
| --- | --- | --- |
| Anthropic | API 密钥 | 可编辑 |
| OpenAI | API 密钥 | 可编辑 |
| Google Gemini | API 密钥 | 固定 |
| xAI | API 密钥 | 可编辑 |
| Z.ai | API 密钥 | 可编辑 |
| Moonshot AI | API 密钥 | 可编辑 |
| Qwen | API 密钥 | 可编辑 |
| DeepSeek | API 密钥 | 固定 |
| Mistral | API 密钥 | 固定 |
| Groq | API 密钥 | 固定 |
| Together AI | API 密钥 | 可编辑 |
| Fireworks AI | API 密钥 | 可编辑 |
| OpenRouter | API 密钥 | 固定 |
| OpenCode Zen | API 密钥 | 固定 |
| Ollama | 无，本地运行 | 可编辑 |
| LM Studio | 无，本地运行 | 可编辑 |
| 任何兼容 OpenAI 的端点 | 可选 | 可编辑 |

最后一行包括自托管网关，如 vLLM 和 LiteLLM，也包括尚未有专属适配器的任何厂商：给 Conduit 一个 base URL，如果该端点需要，再提供一个密钥。

### 接入 GPT、Claude、Grok、GLM、Kimi 等模型

Conduit 可以对接 2026 年实际被大量使用的模型家族——GPT、Claude、Gemini、Grok、GLM、DeepSeek、Kimi、Qwen 和 MiniMax——具体走以下三条路径中的哪一条，取决于你想用的模型。

1. **内置适配器。**Anthropic、OpenAI、Gemini、xAI、Z.ai、Moonshot AI、Qwen、DeepSeek、Mistral、Groq、Together AI 和 Fireworks AI 都各自拥有专属提供商：选中它，粘贴密钥，加载模型列表即可。这条路径能直接覆盖 Claude、GPT、Gemini、Grok、GLM、Kimi、Qwen 和 DeepSeek——每一个都自带默认端点，你不需要去查找 base URL。
2. **网关。**OpenCode Zen 或 OpenRouter 会在一个密钥背后收录其余的模型，包括 MiniMax，以及这些服务当下提供的任何其他模型——Conduit 拉取的是实时列表，而不是固定目录。
3. **任何兼容 OpenAI 的端点。**对于没有专属适配器的厂商，或是像 vLLM、SGLang 这样自托管的代理，把兼容 OpenAI 的提供商指向该端点的 base URL，如果它需要密钥就一并提供。

Qwen 的内置适配器默认使用 DashScope 的国际版端点，Moonshot 默认使用 `api.moonshot.ai`——如果你需要其他区域，这两个字段都可以修改。

## 键盘快捷键

在 Windows 和 Linux 上，请用 Ctrl 代替 ⌘。

| 快捷键 | 操作 |
| --- | --- |
| ⌘K | 命令面板，可搜索、执行命令、切换模型和查找工件 |
| ⌘1–⌘9 | 前往首页、聊天、应用、幻灯片、文档、资料库、工作流、连接器、记忆 |
| ⌘N | 新建对话 |
| ⌘, | 打开 Settings |
| ⌘/ | 打开这个快捷键面板 |
| ⌘\ | 切换侧边栏 |
| ⌘J | 切换文档面板 |
| ⌘⇧E | 展开工件面板，或恢复布局 |
| ⌘⇧P | 切换提供商 |
| ⌘⇧W | 切换本轮是否启用网页搜索 |
| ⌘⇧F | 从此处分叉对话 |
| ⌘⇧C | 复制最后一条助手消息 |
| Esc | 关闭面板，或停止当前响应 |

命令面板是分模式的：输入 `>` 查看命令，输入 `@` 查找工件，输入 `/` 选择模型，或者直接输入普通文本来搜索你发过的所有消息。Settings 顶部也有自己的搜索框，可以直接按名称跳到某项设置，不用逐个翻找分区。

## 工具与连接器

### 内置工具

这些都不需要额外配置：

- **网页搜索与抓取** — 自动 / 托管 / 本地后端（默认 Exa，无需密钥，另有 Tavily、Brave、SearXNG、DuckDuckGo；托管搜索支持 Anthropic、OpenAI、Gemini 和 OpenRouter），支持域名允许/屏蔽列表和行内编号引用
- **文档创作** — 创建和编辑 HTML、Markdown 与文本工件，并可导出
- **剪贴板** — 读取和写入系统剪贴板
- **实用工具** — 计算器、当前时间、UUID、随机值

除非被标记为只读，工具在运行前都会先征求你的确认。内置的只读工具会自动运行，连接器的工具只有在其服务器把它标记为只读时才会自动运行；其他所有工具在运行前都会先征求你的确认。网页搜索默认是关闭的，首次使用时会征求同意；托管搜索只能通过 Anthropic、OpenAI 或 Gemini 的官方端点运行，一旦你把某个提供商指向自定义 base URL，就会回退到上面的本地后端。发往本地搜索后端的查询会交给对应的服务；默认的 Exa 可能会按其自身条款保留这些查询。

模型的网页抓取只会访问公开的 https 网站：绝不会访问 `localhost` 或你自己网络中的地址，每次重定向也都会检查。它返回网页的标题和可读文本，而不是原始 HTML，并能读取最大 20 MB 的 PDF。没有文本的扫描版 PDF 算作没有内容可读的网页。

### MCP 连接器

Conduit 会以受监管的连接器方式运行 Model Context Protocol 服务器。你可以在**连接器**页面添加一个本地进程，填入启动它的命令和参数；也可以指向一个使用 streamable HTTP 的远程 MCP 端点。

只有当服务器把某个连接器工具标记为只读（标准的 `readOnlyHint`，或 Conduit 自己的 `permissionLevel` 字段）时，它才会不经询问直接运行。其他所有工具都会先询问，你可以让 Conduit 记住这次批准：仅限当前聊天，或始终有效。在 1.0.0-rc.6 之前，大多数第三方服务器上的工具都是不经询问直接运行的，所以你已在使用的连接器现在可能会就以前悄悄运行的工具征求确认。

运行时会对崩溃的本地服务器做退避重启，限制为五分钟内最多三次；它还会限制并发，并把单次调用超时设为三十秒。工具输出在到达模型之前会经过大小限制和脱敏处理，同时还会有结构性防护，防止这些输出被重新当成指令执行，也就是阻断通过工具结果进行提示词注入（prompt injection）的常见路径。

**传输方式：**当前支持本地 `stdio` 和远程 streamable HTTP。 不支持旧的 HTTP+SSE。

composer 不仅能调用连接器的工具，还能调用它的 prompt 和 resource：prompt 选择器会先填好某个 prompt 声明的参数，再把结果放进 composer 供你编辑；resource 选择器附加的内容只作用于下一条消息。同意是按连接器逐个征求的，而如果某个 resource 试图夹带指令，它会被拒绝并被点名，而不是被悄悄执行。

在自己机器上连接服务器是文档要解决的问题。把那个服务器摆到客户面前——不用 JSON 配置，也不出现在 Claude Desktop 里面——则是另一个问题。[如何向客户演示 MCP 服务器](https://conduitllm.com/zh-CN/mcp-distribution.html) 比较了托管式聊天、配合配置文件的 Claude Desktop，以及交付一个桌面客户端。

### Agent 循环

当模型调用工具时，Conduit 会执行它，并在同一轮里把结果回送给模型，继续下一步。你可以在 **Settings → Agent** 中控制边界：最大步数可设为 1 到 50，总耗时（wall-clock）预算可设为 30 秒到 30 分钟。聊天界面不再只是一个转圈图标，而是会显示一条实时进度时间线——按跨轮次实际发生的顺序展示思考、工具调用和文本，附带已用时间，并在某一轮卡住时给出提示。

## 工件

更长的输出，如文档、脚本或小型网页，会在对话旁边的面板中打开，而不是塞满消息滚动区。Conduit 可以原生渲染文本、带语法高亮的代码、可折叠树形 JSON、Markdown（包括 Mermaid 图表和 KaTeX 公式）以及交互式 HTML。

交互式 HTML 运行在一个只允许脚本、除此之外什么都不允许的沙盒框架中：没有同源访问、没有弹窗、没有顶层导航。表单仍然可以使用——Conduit 会把提交事件交给页面，但提交本身不会把任何内容发送到任何地方。注入的内容策略会设置 `connect-src 'none'`，因此页面无法自行发起请求或打开套接字，而且 Conduit 会从它自己的沙盒地址提供该页面。页面无法调用应用自身的命令。有一个例外，是 macOS 上的已知问题：在 macOS 上，页面的脚本仍然可以建立 WebRTC 连接，内容策略并不覆盖这一点；Windows 和 Linux 在 webview 中已将其拦截。如果你确实需要让工件从特定主机加载图片或字体，可以在 **Settings → Privacy & data** 的 **Artifact Security**（工件安全）部分自行放宽。

需要实时数据的页面——比如汇率、天气——仍然可以发出请求。它的 `fetch()` 调用会先交给 Conduit，Conduit 会拦下对每个新网站的第一次请求，并弹出一条横幅说明是哪个网站。你可以选择只允许这一次、为这个页面始终允许、完全不允许，或者允许该页面访问任何公开网站。之后由 Conduit 代为发起请求：仅限 https，不携带 cookie 或凭据，不访问本地或内网地址，超时时间为 20 秒，响应大小上限为 5 MB，每个页面每分钟最多 120 次请求。页面上的地球图标按钮会列出它请求过的每一个网站和每一次请求。这些权限只属于这一个页面，页面被删除时权限也一并删除。仅本地模式会拒绝这一切；在同一个工件安全设置中关闭**“允许页面连接互联网”**也能达到同样效果。

把带围栏的代码块粘贴到对话中时，Conduit 会提供将其提升为工件的选项。工件可以导出到磁盘，也可以附带可选的元数据 sidecar 文件。

每个工件只保存一份当前内容。它没有版本历史，编辑会直接原地替换内容，因此任何你想保留副本的东西都应该先导出。

## 文档

在侧边栏的**文档**（Documents）中新建一个集合，然后添加文件——支持纯文本、Markdown、CSV、Word（.docx）和 PDF。你可以把文件拖放到窗口任意位置来添加，也可以在 composer 里为单次对话附加整个集合。回复会把它所依据的文件显示为可点击的小标签，点开就能看到具体引用的段落。

每个集合只由一个提供商做嵌入——OpenAI、Gemini、OpenRouter 或 Ollama（Anthropic 不能做嵌入）。索引过程会把文档的完整文本发送给这个提供商，因此 Conduit 会在第一次使用时征求同意，按提供商记住你的选择，之后你也可以在**文档**页面中撤回。选择 Ollama，内容就不会离开你的机器——仅本地模式会强制这一选择。检索本身是混合式的：在同一个本地 SQLite 数据库上同时做向量相似度检索和关键词检索，检索到的段落仍然会发给回答这次对话的提供商。

解析在本地设备上完成，没有 OCR 步骤，所以没有文本层的扫描版 PDF 什么都提取不到——遇到这种情况时，Conduit 会告诉你，而不是导入一份空文档。

## 图像生成

OpenAI、Gemini 和 OpenRouter 可以直接在对话中生成图像。由于每张图像都由提供商计费，Conduit 会在生成第一张图像之前征求一次同意——只是聊到图像生成本身并不会触发这个询问。生成结果会作为工件保存在本地，而不是由提供商链接提供，因此不会过期。

## 个人应用

值得留下的页面可以保存为个人应用：在页面的 ⋯ 菜单中选择**另存为应用**，就会生成一份副本，你可以从导航栏的**应用**打开它，也可以从新聊天界面上的*你的应用*打开。即使删除了那段对话，这份副本也照常可用。保存时会逐项询问要保留该页面的哪些网站权限，你没有勾选的一项都不会保留。之后对话中的页面有变化时，应用会提供**更新**。内置八个入门应用；可以在应用页面中添加，也可以在带有应用的创意上点击**打开应用**。

页面（应用，或对话中的页面）还可以声明另外三件事，每一件都由 Conduit 检查。它可以在启动之间保留数据——每个页面最多 5 MB，与你的其他数据存放在一起，开启静态加密时同样加密；**清除数据**可将其删除。它可以接收几项设置，比如一个城市，由 Conduit 在自己的表单中向你询问，并在不重新加载的情况下传给正在运行的页面。它还可以在你为该页面允许之后向你的 AI 模型提问：提示会指明提供商，并说明何时有文本会离开你的设备，页面得到的只有文本输入和文本输出——没有工具、聊天记录、记忆或文档。

每个个人应用都有自己的**设置**页面（应用标题栏中的齿轮，或 ⋯ → 设置）：由哪个模型回答、每天的 token 用量以及云端模型的每日上限（默认 100,000；你电脑上的模型不受限制）、按键查看的已保存数据（可导出和清除）、它可以使用的网站和提供商，以及一周的单行活动记录——从不记录提示、回复或已保存的值。

## 幻灯片

描述你的故事，或在任意聊天中要求做一份演示文稿，Conduit 会先起草一份供你批准的故事线，再据此构建**一份实时演示文稿**：每次修改都是在这份文稿上直接编辑，而不是再生成一个副本。文稿在工作室中打开，中间是放大的幻灯片，聊天窗口在一旁。提出修改要求，助手会只编辑某一张幻灯片，或在整份文稿中替换某个词。

**脚本**把文稿中的每一个字显示为一份文档；可以在那里输入，也可以双击幻灯片上的文字。你写下的文字会在助手重写该幻灯片时保留，除非你要求修改这段文字。**历史记录**会为每次修改保留一个以你的要求命名的版本，随时可以恢复。内置两套主题，也可以使用助手为你设计的主题。

**演示**会全屏播放文稿，另有一个独立的**演示者视图**（当前和下一张幻灯片、演讲者备注、计时器），在你共享幻灯片时保持私密。**导出**可保存为在任何浏览器中都能自行放映的单个 HTML 文件，或 PDF（仅限 Windows）。幻灯片会向本地数据库添加内容，因此退回到幻灯片功能出现之前的版本会从空数据库开始（旧文件会保留为备份）。

## 研究

如果一个问题需要的不只是一次快速搜索，就在 composer 的 **+** 菜单里打开**研究**（或在首页选择它），然后提问。它要求已开启网页搜索，在仅本地模式下不可用。研究使用本地搜索后端（Exa、Tavily、Brave、你自己的 SearXNG 或 DuckDuckGo），从不使用托管搜索：搜索查询发往该服务，网页文本发往你选择的聊天提供商。

**简报。** 在任何步骤运行之前，研究会先提出一份简报：它要回答的 1 到 6 个子问题、可选的范围，以及一个深度。你可以编辑并批准它。每种深度规定了它最多能做到哪一步：

- **快速** — 最多 8 次搜索、15 个网页、10 分钟
- **标准** — 最多 20 次搜索、40 个网页、20 分钟
- **深入** — 最多 50 次搜索、100 个网页、40 分钟

**它读什么。** 它会完整阅读网页，每次三个：包括网页和最大 20 MB 的 PDF，解析在你的设备上完成。扫描版 PDF 没有文本，算作没有内容可读的网页。对于较长的网页或 PDF，模型看到的是开头以及与你的问题相符的部分，而不是全部。

**引文核对。** 模型会提取论断，每条都附上页面中支持它的原话。只有当引文（至少 20 个字符）确实出现在该网页保存的文本中，这条论断才算数，而这项核对由应用完成，不是模型。随后研究会再次搜索仍未解答的部分，再由撰写者把核对过的论断写成报告。带编号的引用和来源列表也由应用生成，不是模型。

**报告。** 结果是聊天文档中的一份 Markdown 文档：摘要、按子问题列出的发现、尚未解决的问题，以及带编号的来源，每条发现都有引用。聊天中的卡片显示摘要，以及已引用和已阅读的来源数量，并带有**打开报告**按钮。**停止**会结束运行，并保留到那时为止已找到的内容。

**网页无法对它下命令。** 网页文本只会进入没有工具的模型调用，所以试图塞入指令的网页无法让它搜索、抓取或保存任何东西。研究的模型调用在它自己的隐藏对话中运行。

**局限：** 对于较长的网页，模型看到的是节选而不是全部。扫描版 PDF 没有文本。你自己的文档目前还不是来源。思考型模型运行较慢，深入可能在完成之前就达到时间上限。

## 工作流

**工作流**页面会替你运行例行任务：抓取网页、搜索网页、让模型做摘要、向你提问，并把结果保存为文档。可以从现成的工作流开始——晨间简报、网页摘要、主题关注——也可以在步骤编辑器中自己搭建，然后立即运行，或按计划运行（每天、工作日的固定时间，或每隔几小时）。打开任意一次运行，可以看到每个步骤做了什么；修好某个步骤后，可从该步骤重新运行，之前的步骤不会重复执行。

开启计划时，会先列出该工作流可以自行完成的全部操作——它读取的网站、网页搜索、使用的模型、保存文档——供你批准。如果某次计划运行需要更多权限（例如编辑之后），它会暂停并询问：允许一次、始终允许或不允许。每次运行都有时间和 token 限制，你可以停止正在进行的运行。Conduit 关闭期间错过的运行，会在你打开它时执行一次。

为了在关闭窗口后让计划继续运行，Conduit 可以驻留在托盘并在你登录时在托盘中启动；两者默认都是关闭的，托盘选项只会在你第一次开启计划时提示一次。

## 首页

Conduit 打开后先进入**首页**，它是导航栏中的第一项。一个输入框就能开始任何事：要求做演示文稿，幻灯片会带着故事线打开；其他请求则开始一次聊天。下方的**待处理**列出等你处理的工作流批准、工作流提问和记忆建议（没有内容时隐藏），**从上次离开的地方继续**显示你最近的聊天、演示文稿和应用，应用的每个区域都有一个带实时数量的卡片；区域为空时则显示一个可以试试的示例。

Ctrl+1 到 Ctrl+9（macOS 上为 ⌘）依次打开首页、聊天、应用、幻灯片、文档、资料库、工作流、连接器和记忆，命令面板中也为每一项提供了“前往”条目。

## 外观与语言

Conduit 只有一种设计，分两种模式。在 **设置 → 外观** 中，可以选择深色、浅色或跟随系统，并为每种模式分别挑选主色——按钮、选中内容和当前项目所用的强调色；难以辨认的颜色会被拒绝。同一页面还可以设置界面字号、密度和图表大小。

同一个 Settings 页面会设置界面语言，覆盖 Conduit 提供的全部八种语言。它会改变菜单、按钮、日期和数字的显示方式——但不会改变助手回复所用的语言。

## 你的数据存放在哪里

Conduit 会把所有内容存到你所在平台的应用数据目录中：对话、消息、提示词和用量记录保存在 SQLite 数据库里；附件和工件则进入按内容寻址的 blob 存储，并按哈希去重。

消息以只追加的事件日志形式写入，并在其上维护一个物化视图，这正是对话在应用中途被强制结束时仍能恢复的原因。启动时，Conduit 会对这两者进行协调。

你也可以在 **Settings → Privacy & data** 中启用可选的 AES-256-GCM 静态加密，主密钥由你的操作系统钥匙串包裹。它默认关闭，而且目前还不覆盖消息文本，当前范围请查看[隐私页面](https://conduitllm.com/zh-CN/privacy.html)。

## 故障排查

### 在 Windows 上构建失败

几乎总是因为缺少 C++ 工具链。安装带有 “Desktop development with C++” 工作负载的 Visual Studio 2022 Build Tools，然后运行 `check-setup.ps1` 确认。

### 我的提供商密钥没有保存成功

Conduit 需要可用的操作系统凭据存储。在无头或精简的 Linux 系统上，可能没有运行 Secret Service。你可以启动一个 keyring 守护进程，或者启用加密的文件型凭据存储，但后者需要通过环境变量提供一个密钥。

### 看不到 Ollama 的模型

请确认 Ollama 正在运行，并且至少已经拉取了一个模型；同时确认 Conduit 为它配置的 base URL 与 Ollama 正在监听的端口一致。

### 其他问题

你可以从 **Settings → Diagnostics** 导出诊断包并附到 issue 中。出于设计考虑，其中不包含机密信息、base URL、允许列表或对话内容，而且在生成前会要求你确认其中包含的内容。

[查看源码](https://github.com/runningpixels/conduit)