用 SurfMind 把本地 LLM 或自定义 AI 接入你的浏览器

SurfMind 不会把你锁死在某一套模型上。通过 Custom Model API（自定义模型 API），你可以让它指向运行在自己机器上的模型（Ollama、LM Studio、Jan、llama.cpp、vLLM），也可以指向几乎任何支持 OpenAI 补全接口的外部 AI 服务商——Poe、z.ai、Together、Groq、DeepSeek、AWS Bedrock 等等，数不胜数。

但问题在于：如果第一次没跑通，往往只是某个小小的配置失误。而返回的报错（“connection failed”“401”“404”“model not found”）有时让人摸不着头脑。

这篇文章就是一份快速检查与自助排查指南。把清单过一遍，确认你的配置。如果还是不行，给我们发邮件：wave@surfmind.ai。

想找某个具体的服务商？ 看看我们的清单：本地模型（Ollama、LM Studio、Jan……）或 AI 服务商（Poe、z.ai、Together、Groq、AWS……）。

60 秒自查清单

在做任何排查之前，先把这几项过一遍。绝大多数配置问题都逃不出它们：

1. 服务真的启动了吗？ 对本地模型来说，运行器（Ollama、LM Studio 等）必须已经启动，并且 加载了一个模型。
2. 端口对吗？ Ollama 是 11434，LM Studio 是 1234。两者 不能 互换，而这是最常见的一个错误。
3. 路径对吗？ Ollama 的原生路径是 /api/chat，而几乎所有其他服务都是 /v1/chat/completions。两者搞混就会报错。
4. 你粘贴的是完整端点，还是只有基础地址？ SurfMind 的 API URL 字段需要的是以 /chat/completions（Ollama 则是 /api/chat）结尾的完整 URL，而不是只填到 https://api.provider.com/v1。
5. API key（以及它对应的请求头）正确吗？ 本地运行器通常不需要 key。外部服务商则需要把请求头设为 Authorization，并填入你真实的 key 作为值。
6. 对于浏览器里的本地模型：CORS 放行了吗？ 这是本地配置特有的一个额外步骤（OLLAMA_ORIGINS，或在 LM Studio 里打开“Enable CORS”）。

如果做完这些还是卡住，那就接着往下读——上面每一项都有一个让人栽跟头的微妙变体。

每个字段该填什么

当你打开 Custom 标签页 → Add Custom Models 时，会看到 “Custom Model API” 表单。下面是每个字段的确切要求：

大家最容易填错的两个字段是 API URL（基础地址 vs 完整端点）和 API Key Header（用哪个请求头）。本指南接下来会重点拆解这两点。

错误 #1：API URL 路径（/api/chat 对 /v1/chat/completions 的陷阱）

这是最大的一个坑，而且值得搞清楚它 为什么 会发生。

这个世界上存在两种不同的 API “方言”：

• Ollama 的原生 API，使用 http://localhost:11434/api/chat。
• OpenAI 补全 API，使用 .../v1/chat/completions。LM Studio、vLLM、Jan、Poe、z.ai、Together、Groq——基本上其他所有人——讲的都是这种。

所以，如果你照搬一份为 LM Studio 写的配置指南，把那个路径用在 Ollama 上（或者反过来），即便服务跑得好好的，你也会拿到 404。服务是开着的；你只是敲错了门。

值得一提： Ollama 其实 两种 方言都讲。SurfMind 里的 Ollama preset 用的是原生 /api/chat 路径，这是最省事的方式，并且能自动发现模型。只有当某个工具明确要求 OpenAI 格式时，你才需要用 Ollama 的 /v1/chat/completions 路径。对 SurfMind 来说，直接用预设就好。

错误 #2：端口号

每个本地运行器都有自己默认的端口，而它们看起来又足够相似，很容易手滑打错：

11434 和 1234 是经典的混淆——乍一看很容易认错，但只要差一个数字，就什么都连不上。如果你自己改过端口（比如用 --port 9000 启动了 vLLM），那就用 你自己的 端口，而不是默认值。

快速验证一下：在浏览器里打开这个端口。访问 http://localhost:11434 应该会看到 Ollama 的 “Ollama is running” 提示。如果页面根本打不开，那就是服务没启动，或者端口填错了。

错误 #3：粘贴了基础 URL，而不是端点

服务商的文档几乎总是给你一个 基础 URL——类似 https://api.poe.com/v1。这是因为它们的代码示例用的是 OpenAI SDK，SDK 会在底层帮你拼上 /chat/completions。

而 SurfMind 的 API URL 字段不会帮你做这件事。它需要的是 完整端点。所以你得自己把路径补上：

• 文档里的基础 URL：https://api.poe.com/v1
• 你粘进 SurfMind 的内容：https://api.poe.com/v1/chat/completions

Models URL 字段（用来自动列出可用模型）也是同样的道理：拿基础地址，加上 /models → https://api.poe.com/v1/models。

两个相关的小失误：

• 重复的 /v1。 如果基础地址已经以 /v1 结尾，就别再加一个。.../v1/v1/chat/completions 会得到 404。
• 结尾的斜杠。 .../chat/completions/ 这样带个结尾斜杠，在某些服务器上会失败。把它去掉。

错误 #4：Models URL 与 API URL 不匹配

Models URL 是可选的。它是 SurfMind 调用来获取某服务商所提供模型列表的端点，这样就能在下拉菜单里展示它们，省得你手动输入名字。如果保存之后选择器里没出现你的模型，问题通常就出在这个字段。它必须和聊天端点遵循 同一种方言：

一个常见的错误是把两者搞混——给 OpenAI-compatible 服务商用了 /api/tags，或者给 Ollama 原生预设用了 /v1/models。如果你用的是 Ollama preset，这一项会自动帮你正确填好；别去动它。

什么时候该留空： 有些服务商不公开模型列表端点，或者干脆屏蔽它。这没关系——把 Models URL 留空，自己把准确的模型 id 输入到模型字段里就行（见 错误 #7）。聊天照样能用；你只是少了那个自动填充的下拉菜单。

错误 #5：API Key Header（Bearer 对 x-api-key）

API Key Header 下拉框决定了你的 key 以何种方式附加到请求上。选错了，即便 key 完全有效，你也会拿到 401 Unauthorized。一共有三个选项：

然后 API Key 字段只填 key 本身：

• 不要 输入 Bearer 这个词——当你选择 Authorization 时，SurfMind 会自动加上。
• 不要 留下结尾的空格（这是 401 出人意料地常见的一个原因）。
• 对 本地模型，留空即可。（LM Studio 是个例外——它需要 某个 非空值；它自己的文档里用的是 lm-studio。）

如果拿不准某个服务商用哪个请求头：99% 的 OpenAI-compatible 服务商都用 Authorization。只有当服务商的文档明确展示了 x-api-key 请求头时，才去用 x-api-key。还是收到 401？那就重新生成 key，再三确认请求头的选择，并确认没有多余的空格。

错误 #6：CORS——本地特有的坑

浏览器会拒绝调用本地服务，除非该服务明确允许来自扩展的请求。这个坑专门绊倒 本地 配置（外部服务商已经默认放行）。

• Ollama： 启动时启用浏览器访问：

  # Mac/Linux
  OLLAMA_ORIGINS="*" ollama serve
  
  # Windows (PowerShell)
  $env:OLLAMA_ORIGINS="*"; ollama serve

  遇到 “port 11434 already in use”？ 说明 Ollama 后台应用已经在运行了。先把它退出（Mac 在菜单栏，Windows 在系统托盘），然后再运行上面的命令。

• LM Studio： 在 Developer / 本地服务标签页里，启动服务之前先把 Enable CORS 打开。

还有一个细节：如果 localhost 连不上，试试改用 127.0.0.1（或者反过来）。在某些系统上，这两者的解析方式并不相同。

错误 #7：模型名必须完全一致

连上之后，你选择的 模型名 必须和服务商所预期的完全一致——包括大小写。这在那些不自动列出模型、或者命名方式不寻常的服务商上特别坑人：

• Poe 使用展示风格的 bot 名称，比如 Claude-Sonnet-4.6 和 GPT-5.4——照着它在 Poe 上显示的样子原样复制。
• z.ai 使用 glm-4.6、glm-5 这样的 id。
• Together AI 使用带命名空间的 id：meta-llama/Llama-3.3-70B-Instruct-Turbo、deepseek-ai/DeepSeek-V3。
• Fireworks 使用完整路径 id：accounts/fireworks/models/llama-v3p3-70b-instruct。

如果连接正常，却收到 “model not found”，那几乎总是模型名打错了或大小写不对。当 SurfMind 能通过 Models URL 自动列出模型时，从列表里选，而不是手动输入。

快速参考：本地模型

下面这些都运行在你自己的机器上。打开 SurfMind 的 Custom 标签页 → Add Custom Models，选中对应的预设（Ollama 有自己的预设；其余的用通用的 OpenAI-compatible 预设），并把 API Key Header 设为 None。服务商名称链接到各工具的配置文档。

Ollama

• API URL：http://localhost:11434/api/chat
• Models URL：http://localhost:11434/api/tags
• API key：无

LM Studio

• API URL：http://localhost:1234/v1/chat/completions
• Models URL：http://localhost:1234/v1/models
• API key：任意非空值（例如 lm-studio）

Jan

• API URL：http://localhost:1337/v1/chat/completions
• Models URL：http://localhost:1337/v1/models
• API key：无（或填你的 Jan key）

llama.cpp

• API URL：http://localhost:8080/v1/chat/completions
• Models URL：http://localhost:8080/v1/models
• API key：无（除非你用 --api-key 启动了它）

vLLM

• API URL：http://localhost:8000/v1/chat/completions
• Models URL：http://localhost:8000/v1/models
• API key：如果你设置了 --api-key，就填它

LocalAI

• API URL：http://localhost:8080/v1/chat/completions
• Models URL：http://localhost:8080/v1/models
• API key：无

这些服务别忘了 CORS 那一步（错误 #6）。针对 Ollama，带截图的完整图文教程见我们的 Ollama 指南；如果你在前两者之间犹豫不决，可以看看 Ollama vs LM Studio。

快速参考：热门 AI 服务商

下面这些云服务商都讲 OpenAI-compatible API。用通用的 OpenAI-compatible 预设，把 API Key Header 设为 Authorization（它们都用 Bearer token），然后粘贴你的 key。服务商名称链接到各家的 API 文档。

Poe — 一个 key 通行数百个模型（Claude、GPT、Gemini、Llama……），按你的 Poe 订阅积分计费。模型名是展示风格的 bot 名称——照着它在 Poe 上显示的样子原样复制（例如 Claude-Sonnet-4.6、GPT-5.4）。key 从 poe.com → Settings → API key 获取。

• API URL：https://api.poe.com/v1/chat/completions
• Models URL：https://api.poe.com/v1/models

CanopyWave — GPU 云服务商，提供开源模型（Kimi、DeepSeek、Llama、Qwen）。key 从 CanopyWave 控制台获取。

• API URL：https://inference.canopywave.io/v1/chat/completions
• Models URL：https://inference.canopywave.io/v1/models

z.ai (GLM) — 智谱的 GLM 模型（glm-4.6、glm-5）。注意：z.ai 还发布了一个单独的 Coding Plan 端点（https://api.z.ai/api/coding/paas/v4）和一个 PaaS 端点（https://api.z.ai/api/paas/v4）——用下面这个 OpenAI-compatible 的，并且别多加一个 /v1。

• API URL：https://api.z.ai/api/openai/v1/chat/completions
• Models URL：https://api.z.ai/api/openai/v1/models

Together AI — 庞大的开源模型目录。模型 id 很长（meta-llama/Llama-3.3-70B-Instruct-Turbo）——照着 Together 的模型页面原样复制。

• API URL：https://api.together.xyz/v1/chat/completions
• Models URL：https://api.together.xyz/v1/models

Groq — 推理速度极快。坑点：路径是 /openai/v1，而不是只有 /v1。

• API URL：https://api.groq.com/openai/v1/chat/completions
• Models URL：https://api.groq.com/openai/v1/models

DeepSeek — 当前模型是 deepseek-v4-flash 和 deepseek-v4-pro（较旧的 deepseek-chat / deepseek-reasoner 别名正在被淘汰——最新情况请查 DeepSeek 文档）。/v1 是可选的；DeepSeek 接受带或不带它的 URL。

• API URL：https://api.deepseek.com/v1/chat/completions
• Models URL：https://api.deepseek.com/v1/models

Mistral — mistral-large-latest、mistral-small-latest 等。标准的 OpenAI-compatible。

• API URL：https://api.mistral.ai/v1/chat/completions
• Models URL：https://api.mistral.ai/v1/models

Fireworks AI — 坑点：路径是 /inference/v1，而不是 /v1。模型 id 长这样：accounts/fireworks/models/llama-v3p3-70b-instruct。

• API URL：https://api.fireworks.ai/inference/v1/chat/completions
• Models URL：https://api.fireworks.ai/inference/v1/models

xAI (Grok) — Grok 模型（grok-4 等）。标准的 OpenAI-compatible。

• API URL：https://api.x.ai/v1/chat/completions
• Models URL：https://api.x.ai/v1/models

AWS Bedrock — Bedrock 现在有了一个 OpenAI-compatible 端点，但有两个坑：host 与区域相关（例如 us-west-2），且路径是 /openai/v1。你必须使用 Bedrock API key（在控制台里生成的 bearer token）——而不是你平常的 AWS 访问密钥/SigV4。模型 id 长这样：openai.gpt-oss-120b-1:0。

• API URL：https://bedrock-runtime.<region>.amazonaws.com/openai/v1/chat/completions
• Models URL：留空——稍后再输入模型 id

还是连不上？最后的排查

按这个清单逐项排查：

1. 在浏览器里打开 API URL 的 host。 本地服务打不开 → 它没在运行，或者端口错了。
2. 重读一遍路径。 Ollama → /api/chat。其他所有人 → /v1/chat/completions（或表格里该服务商的特殊路径）。
3. 确认你粘贴的是完整端点，而不是基础地址，并且没有重复的 /v1 或结尾斜杠。
4. 401？ 那就是 key 或请求头的问题。请求头 = Authorization，key 不带空格、不带 Bearer 前缀。
5. 404 “model not found”？ 连接没问题——修正模型名（大小写要准）。
6. 本地模型，被浏览器拦截？ 启用 CORS（OLLAMA_ORIGINS="*" 或 LM Studio 的开关），并试试 127.0.0.1 和 localhost 互换。

这套流程能解决绝大多数配置问题。

还需要帮助？

如果你已经过完整份清单，服务商却依然连不上，请发邮件到 wave@surfmind.ai，告诉我们你正在尝试的服务商以及你看到的报错。我们会帮你把它连上。

---

连上了？在你接下来要读的那个页面上打开 SurfMind，让你的模型开始干活吧。

获取 SurfMind →