元宿six在本地把大模型服务跑起来之后，网页端要调用它，最烦的不是模型本身，而是浏览器那一侧各种拦路。我第一次遇到这个问题的时候，模型进程明明在终端里输出了正常的日志，curl 请求也返回了完整 JSON，页面一刷新却给我一行 net::ERR_CONNECTION_REFUSED。后来我把“浏览器访问的地址”“本地跑的模型引擎”“项目里的页面源”这三件事分开看，才发现问题大多不是模型没起来，而是中间那段连接关系没被管理起来。于是就有了这组我起名叫 QCLAW 的配置方案与连接组件，专门负责浏览器和本地推理服务之间的联通。这篇会依次解释它的原理、架构和数据流向，然后把你可能遇到的配置项逐条拆开，顺带放几个我实际排查过的场景，给正在做网页端本地模型调用的人当参考。
我会默认你已经能把模型服务在终端里跑通，至少有基本的命令行能力。如果你连模型服务都还没启动，也不影响阅读，这篇的重点是它在“浏览器到模型引擎”之间承担的角色，以及配置时为什么某个字段不能乱填。
1. 为什么浏览器连本地模型服务，比你想的更脆弱
先说结论：浏览器访问本地模型接口，跟你在终端里执行一条 curl 是完全不同的两码事。curl 只负责把 HTTP 请求发出去、把响应打出来；浏览器会在请求前、请求中、请求后做一堆安全检查，任何一环不过，页面就拿不到数据。
1.1 一次浏览器请求真正经过的四个关卡
从页面上的一次 fetch 到模型返回结果，至少要过四关。
第一关是地址解析。页面代码里写的 http://localhost:8765/v1/chat/completions，会被浏览器先解析。localhost 可能对应 IPv4 的 127.0.0.1，也可能对应 IPv6 的 ::1，浏览器有自己的解析顺序。你本机的 QCLAW 如果只监听在 IPv4 地址上，而浏览器优先去连 ::1，就会出现连接被拒绝，但你用 curl http://localhost:8765 又一切正常。
第二关是 TCP 连接。浏览器必须能跟 QCLAW 监听的地址和端口建立连接。如果监听端口没起来、端口被别的进程占掉、监听地址写错，这一关就直接失败。现代浏览器对连接失败的报错有时候挺“欺骗性”的，明明只是端口没开，控制台里却可能显示一个看起来像 DNS 的报错。
第三关是跨域安全检查。如果页面运行在 http://localhost:5173，而请求发到 http://localhost:8765，即使都是本机，端口不同也属于跨源。浏览器会先发一个 OPTIONS 预检请求，检查 QCLAW 返回的 Access-Control-Allow-Origin 是否允许当前页面源。很多本地服务默认不处理 OPTIONS 请求，或者返回的响应头不完整，于是页面真正想发的 POST 请求根本不会发生。
第四关才是真正的业务请求。浏览器把实际数据发过去，QCLAW 接收后转发给模型引擎，再把模型的响应返回给页面。这一步还可能因为响应格式不对、流式数据没按预期分段、字段名和前端代码不匹配而宣告失败。
1.2 curl 能通、浏览器不通的本质原因，远远不止跨域
我见过不少人一遇到浏览器报错，第一反应就是“是不是要关掉某个安全设置”。绝大多数情况不用。
curl 不带 Origin 头，也不执行任何同源策略，所以它测试的是“链路通不通”；浏览器带 Origin 头、Sec-Fetch-Site 头、Cookie 及其他请求上下文，它测试的是“这个页面有没有资格访问这个服务”。两者目标不一样，结果当然可能不同。
另一个容易被忽略的点是：浏览器会有缓存。你在 QCLAW 里改了允许的来源，前端页面可能还留着旧的 CORS 预检结果，于是你看到浏览器依然报错，配置却明明改对了。排查时用无痕窗口验证非常关键。
浏览器还会区分安全上下文。http://localhost 被当作潜在可信来源，但换成局域网 IP 访问页面时，很多浏览器策略会收紧。就算你的页面和 QCLAW 都在同一台机器上，一旦你从 http://192.168.x.x:5173 打开页面，浏览器对发起请求的限制和从 localhost 打开时并不完全一样。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. QCLAW 的结构设计：页面、配置和推理服务之间到底发生什么
QCLAW 本身不是模型引擎，它不做任何推理，也不存对话记录。它的职责是“把浏览器的请求安全地交给模型引擎，再把模型的响应按浏览器能接受的方式还回去”。类比一下，它就像公司前台的访客登记处：访客（浏览器）不能直接冲进办公室（模型引擎）找负责人，得先在登记处说明来意、核对身份，由登记处联系负责人，再把负责人带到会客室。
2.1 为什么不让浏览器直接连模型引擎
最直接的原因是跨域。模型引擎一般跑在 127.0.0.1:8000，前端开发服务器跑在 localhost:5173，二者不同源。让模型引擎直接开放跨域很简单，加上 Access-Control-Allow-Origin: * 就行，但这会带来一个非常实际的风险：只要浏览器里任何页面发请求到你的模型引擎，它都会响应。
本地开发时你觉得无所谓，可你电脑上还有别的网页在跑。如果某个不可信页面知道你在本地 8000 端口开了带模型能力的服务，它完全可以借着你浏览器的身份去调用模型，消耗你的计算资源。QCLAW 存在的价值就是在这层做一个受控入口，只允许配置文件里写明的页面来源调用，其他来源一律拒绝。
另外，模型服务的地址、密钥、可用模型清单这类信息不应该暴露给前端代码。浏览器里所有代码对用户都是可见的，把密钥写到前端 JavaScript 里等于把钥匙挂在门口。通过 QCLAW 统一放行，页面只需要知道 QCLAW 的地址，模型引擎的细节被挡在后面。
2.2 一个完整请求在 QCLAW 里的流转路径
我用一个具体例子来说明。假设前端页面跑在 http://localhost:5173，QCLAW 监听在 http://127.0.0.1:8765，模型引擎跑在 http://127.0.0.1:8000，而且引擎提供的是 OpenAI 兼容接口。
请求流程可以拆成下面几条。
- 用户在页面里点“发送”，前端代码向
http://127.0.0.1:8765/v1/chat/completions发起 POST 请求。 - 浏览器发现请求源是
http://localhost:5173，目标源是http://127.0.0.1:8765，端口和协议都不同，于是先发一个 OPTIONS 预检。 - QCLAW 收到 OPTIONS，检查请求头里的 Origin 是否在配置文件的
origins白名单里。在名单内就返回 204，并带上允许的请求方法和请求头；不在名单内就返回 403。 - 浏览器确认预检通过，发出真正的 POST。
- QCLAW 验证请求格式、检查路径
/v1/chat/completions是否在路由表里，然后把请求重写到模型引擎的路径，例如/openai/v1/chat/completions。 - 模型引擎开始处理，返回 JSON 或者流式数据。QCLAW 把响应原样传回给浏览器，并保持正确的
Content-Type。 - 页面拿到数据，渲染出对话内容。
整个过程中，浏览器只感知到 QCLAW 的存在。模型引擎换了地址、换了路径、甚至从本地换成另一台服务器，只要 QCLAW 的配置文件同步更新，前端代码可以完全不用改动。
2.3 为什么我用“路由重写”而不是单纯的端口转发
如果只是把端口从 8765 转到 8000，不需要额外处理路径差异。但实际开发里，模型引擎暴露的接口路径和前端项目使用的路径经常不一致。前端按 OpenAI 的 /v1/chat/completions 习惯去写，模型引擎却可能挂在 /openai/v1/chat/completions 或者 /api/generate 这种路径上。
QCLAW 在配置里提供路由重写，就是为了把“前端希望用的路径”和“后端真实存在的路径”解耦。以后想换个模型引擎，只需要改配置里的一段映射，前端不用动。这个思路和 API 网关的路径转发是一个道理，只是范围小得多，只服务浏览器到本地服务这一小段。
3. 配置文件中每个字段的含义，以及怎么样算“配错了”
配置文件是 QCLAW 最容易出问题的地方，因为字段不复杂，正因为不复杂，很多人凭感觉填，填错了又不知道从哪里看。下面这份不是某个框架的官方配置，而是我实际在用的精简模板，你把关键字段弄明白之后，换成任何类似工具的配置格式都能很快上手。
3.1 一份最小可用配置的完整注释
code复制server:
host: "127.0.0.1"
port: 8765
engine:
base_url: "http://127.0.0.1:8000"
api_key_env: "QCLAW_ENGINE_KEY"
timeout_seconds: 60
origins:
- "http://localhost:5173"
- "http://127.0.0.1:5173"
routes:
- path: "/v1/chat/completions"
rewrite: "/openai/v1/chat/completions"
method: "POST"
stream: true
log:
level: "info"
这个文件的核心是四块：服务监听设置、模型引擎设置、页面来源白名单、路由规则。我会逐块说清楚为什么这么写，以及改动之后会有什么影响。
server.host 建议只填 127.0.0.1。它的意思是 QCLAW 只接受来自本机的连接，局域网里其他设备访问不到。如果你的页面跑在本机、模型也跑在本机，这是最稳妥的方式。有人贪省事填 0.0.0.0，结果局域网里任何设备都能访问你的模型服务，存在被滥用风险，不推荐。
server.port 用一个不太常用的高位端口，比如 8765。避开 8000、8080、3000 这些太常见的端口，理由是其他开发服务很可能占用这些端口。QCLAW 启动之前会检查端口是否被占用，如果占用会给出提示。我习惯把 Chrome、Edge 开发者工具里经常会开的 VSCode 服务端口都排除掉。
engine.base_url 指向模型引擎的基础地址。这里最容易犯的错误是路径重复。比如 QCLAW 的路由 rewrite 写成了 /openai/v1/chat/completions，而 base_url 又写成 http://127.0.0.1:8000/openai，拼出来的完整地址就变成了 /openai/openai/v1/...。我处理路径时给自己定了一条规矩：base_url 只写到服务根地址，最多写到版本前缀，具体接口路径全部由路由规则来拼。
3.2 模型密钥到底应该放在哪里
配置文件里有 api_key_env 这样一个字段，它不存密钥值，而是存一个环境变量名。实际运行时 QCLAW 会去当前进程的环境变量里读取 QCLAW_ENGINE_KEY。这样做的理由是，配置文件经常需要提交到 git 仓库里给同事共享，如果直接把密钥写进去，一次提交就等于把密钥公开了。
启动方式类似这样，在 bash 或 zsh 里先导出环境变量，再启动服务：
bash复制export QCLAW_ENGINE_KEY="sk-xxxx"
qclaw -c qclaw.yml
如果你用的是 Windows PowerShell，等价的写法是 $env:QCLAW_ENGINE_KEY="sk-xxxx"。要注意的是，环境变量只在当前终端会话里有效，如果你换了终端窗口重新启动，但忘了重新导出，模型引擎会返回鉴权失败。这是很常见的“配置没生效”假象。
3.3 页面来源白名单不只是为了 CORS
很多人觉得 origins 只是让浏览器跨域检查通过，其实它的作用更偏向“访问控制”。QCLAW 在收到请求时，会检查请求头里的 Origin 字段。如果请求来自一个不在白名单里的页面，会直接拒绝，而不是等浏览器自己判断。
这里有个容易被忽略的细节：http://localhost:5173 和 http://127.0.0.1:5173 是两个不同的源，即使它们指向同一个开发服务器。所以配置白名单时最好两个都写上，避免你一会儿用 localhost 打开页面、一会儿用 127.0.0.1 打开页面，行为不一致。
如果页面将来部署到测试服务器，域名是 http://your-internal-server.example.com，就必须把那个完整地址也加入白名单。忘了加的话，浏览器控制台会报 CORS 错误，但错误信息里不会直接告诉你“白名单缺了哪个源”，只提示没有 Access-Control-Allow-Origin 响应头，容易让人一头雾水。
3.4 流式响应配置比想象中重要
stream: true 表示这个接口会以 SSE（Server-Sent Events）形式流式返回数据。QCLAW 在转发流式响应时不能等全部数据组装完毕再返回，得边收边传，否则前端看到的是一段“卡了半天，然后一次性吐出一大段文字”，体验很差。
如果你发现页面里的回复总是迟迟不出现，但最终会一次性显示完整结果，大概率是 QCLAW 或者它后面的某个环节把流式响应缓冲了。QCLAW 的配置里应该有一个关闭缓冲的开关，同时对 text/event-stream 的响应要原样保留，不要做任何压缩或重组。
4. 联不通的高频现象排查顺序：从浏览器一路查到模型引擎
排查连接问题时，最忌讳上来就看代码。我的做法是：先确定问题出在链路哪一段，再动手改配置。浏览器、QCLAW、模型引擎三个点，每次只验证一个。
4.1 先建立一套可以重复执行的验证方法
假设 QCLAW 的地址是 http://127.0.0.1:8765。第一步不需要请求任何业务接口，先访问健康检查路径。如果没有专门健康接口，就随便访问根路径，看有没有 HTTP 响应。在终端里执行：
bash复制curl -v http://127.0.0.1:8765/
如果这个请求都失败，问题基本出在 QCLAW 没启动、监听地址写错、或者端口被占用。此时去确认 QCLAW 的启动日志，看它实际监听在哪个地址上。
第二步是用 curl 向 QCLAW 发一个真实的对话请求，绕过浏览器跨域限制，直接验证到模型引擎的通路：
bash复制curl -X POST http://127.0.0.1:8765/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"qwen3","messages":[{"role":"user","content":"你好"}]}'
如果这一步通了，说明 QCLAW 到模型引擎这一段正常。如果没通，看 QCLAW 日志里有没有记录转发失败原因，比如连接被拒绝、超时、鉴权失败。
前两步都通过之后，再回到浏览器刷新页面。如果还报错，几乎可以锁定是跨域白名单或者浏览器策略的问题。
4.2 高频故障场景和对应处理方法
我把实际开发中整理过的问题放在一张表里，方便你对照排查。
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
net::ERR_CONNECTION_REFUSED |
QCLAW 没监听该端口，或监听地址不是当前访问的地址 | 用 curl 验证目标地址，查看启动日志 |
CORS policy: No 'Access-Control-Allow-Origin' |
页面源不在白名单，或预检请求没被处理 | 把页面完整源加入 origins，确认 QCLAW 对 OPTIONS 返回 204 |
请求发出后一直 pending，最后超时 |
模型引擎无响应，或者超时阈值太短 | 直接请求模型引擎，确认它是否正常，调大 timeout_seconds |
| 提示鉴权失败 | QCLAW_ENGINE_KEY 环境变量未设置 |
在启动 QCLAW 的同一个终端里导出环境变量 |
| 页面一次性返回结果，没有逐字显示 | 流式响应被缓冲，或前端没正确解析 SSE | 检查 stream: true，关闭中间层缓冲 |
| 从无痕窗口能通，普通窗口不通 | 浏览器请求被旧缓存或扩展干扰 | 清理缓存、禁用可疑扩展 |
4.3 用 QCLAW 日志定位时，重点看哪几个字段
一份可用的 QCLAW 日志通常包含时间、请求来源、请求路径、响应状态、耗时等字段。我看到过很多人在排错时完全不看日志，只盯着浏览器控制台，这样会漏掉大量关键信息。
假设日志长这样：
code复制2025-01-12 14:02:11 INFO request from=http://localhost:5173 path=/v1/chat/completions status=200 elapsed=1203ms
2025-01-12 14:02:13 WARN block request from=http://evil.example.com path=/v1/chat/completions reason=origin-not-allowed
如果被拒绝，日志会明确告诉你 reason=origin-not-allowed，是白名单问题。如果状态是 200 但耗时很长，问题大概率在模型引擎本身。我之前遇到过一个很隐蔽的例子：模型引擎返回 200 但消息体只有错误说明，前端误以为成功，结果页面一直空白。后来把 QCLAW 的响应体日志打开，才发现模型引擎返回的实际内容是一条拼写错误导致的不合法请求。
5. 容易被忽略的浏览器端细节，以及它的对策
QCLAW 配好了、QCLAW 到模型引擎的通路也验证通顺了，浏览器还是可能出来拦路。下面这几个细节在特定场景下会变得很关键，值得提前了解。
5.1 本地网络访问的自动限制
现代浏览器对“从公网页面访问本地网络资源”这件事收得很紧。浏览器把本地地址段（比如 127.0.0.1、192.168.x.x）视为私网，如果某个页面的源是公网域名，而它尝试请求本地地址，浏览器会做额外的预检检查，甚至直接拦截。
这带来一个实际影响：如果你把前端页面部署在一台测试服务器上，页面的域名是内网域名，而 QCLAW 跑在你自己的电脑上，浏览器会认为“一个内网页面在访问另一个本地服务”，处理策略和两个服务都在同源时不一样。为了解决这个问题，最好保持页面、QCLAW、模型引擎都在同一台机器上或者同一个受控环境里。跨设备访问时，优先用同一个内网环境部署，而不是让页面在公网、服务在私网。
5.2 localhost 与 127.0.0.1 的安全上下文差异
浏览器把 http://localhost 当作安全上下文处理，但 http://127.0.0.1 在某些浏览器里有类似待遇，某些则不一定。如果你的页面用到本地模型服务，并且想使用一些较新的浏览器 API，建议统一用 localhost 作为页面访问地址，同时让 QCLAW 的源白名单同时包含 localhost 和 127.0.0.1 两种写法。
页面地址、请求地址里的主机名写法不一致，也常导致问题。页面运行在 http://localhost:5173，QCLAW 要求配置里列出 http://127.0.0.1:5173，两者看起来像同一个服务，但对浏览器来说完全不同源。我实际遇到过一次：从 localhost 打开页面，请求 QCLAW 一切正常；从局域网 IP 打开同一页面，跨域直接失败，原因就是 QCLAW 的白名单没有包含局域网 IP 对应的源。
5.3 预检请求和流式响应在浏览器里表现不同
QCLAW 在处理 OPTIONS 预检时有一个不能省的动作：返回的 Access-Control-Allow-Headers 必须包含前端实际会发送的自定义头。比如前端代码设置了 Authorization 头，而 QCLAW 返回的允许列表里没有 authorization，浏览器会拒绝后续请求。很多本地引擎的跨域配置只设置了来源，没设置允许请求头，于是看起来“来源明明对了，但还是不行”。
流式响应在浏览器端也经常被误解。浏览器对 text/event-stream 的读取方式和普通 JSON 不一样，前端代码需要用 ReadableStream 或专门的 SSE 库解析，不能简单地等 response.json()。QCLAW 能做的只是保证响应头和编码正确，真正把流逐段渲染出来的逻辑还得由前端去处理。
6. 我在实际环境中沉淀下来的配置习惯与最后的提醒
工具能用和用好之间，差的往往不是功能，而是使用习惯。下面几条是我基于 QCLAW 做浏览器到本地模型联通时，跌过跤之后才形成的配置习惯。
6.1 把“本机访问”作为默认边界，不要轻易扩大监听范围
我的原则是：只要模型引擎和浏览器跑在同一台电脑上，监听地址就只写 127.0.0.1，绝不为了图省事改成 0.0.0.0。原因前面已经提过：本机开发的模型服务没有复杂的访问控制，暴露给局域网等于让它裸奔。如果你确实需要手机或者其他设备调试，那就用防火墙规则只放行特定 IP，不要直接放开所有地址。
同样地，origins 白名单要按最小原则来加。开发阶段加上 http://localhost:5173 就够了，不要写 *。很多本地开发工具为了方便会默认允许所有来源，但 QCLAW 作为专门管连接的一层，边界清楚一点，后面上线或者接入敏感数据时才不会出大问题。
6.2 环境变量用单独的启动脚本管理
我最初总是手动在终端里执行 export，后来发现换终端窗口、重启电脑之后经常忘。现在我把启动命令收敛到一个脚本里，内容类似这样：
bash复制export QCLAW_ENGINE_KEY="sk-xxxx"
export QCLAW_LOG_LEVEL="debug"
qclaw -c ./configs/qclaw.local.yml
把这个脚本命名为 start-qclaw.sh，放到项目目录下，并加入 .gitignore。这样同事拿到代码后，会主动复制一份自己的环境配置，不会误把某个人的密钥提交上去。Windows 用户可以用 PowerShell 写一个 start-qclaw.ps1 做同样的事。
6.3 日志别只开到 info，排错时需要 debug
QCLAW 的日志级别如果设成 info，通常只能看到请求进出的摘要。真正要排查路径重写错误、CORS 预检细节、响应头是否正确，需要在短时间内把日志级别切到 debug。我习惯在 log.level 里写 info，但是启动脚本支持一个环境变量 QCLAW_LOG_LEVEL，可以临时覆盖配置：
bash复制QCLAW_LOG_LEVEL=debug qclaw -c qclaw.yml
等问题定位完再关掉 debug。一直开着 debug 日志，输出会非常嘈杂，反而容易把关键内容淹没。
6.4 换模型引擎时，先只改 base_url，别急着动路由
当你想把 QCLAW 从指向本地模型 A 切到本地模型 B 时，最可靠的做法是先只改 base_url，保持 routes 不变，启动后发一个 curl 请求验证响应格式。如果新引擎的接口路径和旧的不一样，再调整 routes 里的 rewrite。
我有一段时间图省事，同时改了 base_url、rewrite、模型名、页面路由，结果新引擎一直返回 404。后来逐项回退，才定位到是 rewrite 里的 /openai 前缀在 base_url 里重复了。单独改一项、验证一项，能让问题范围缩小很多。
QCLAW 这个连接层组件，本质上解决的是“浏览器期望的请求方式”和“模型引擎实际的接口方式”之间的适配问题。只要记住它的目标是把复杂的转发细节挡在配置外，让页面端保持稳定，实际使用中就不会被网上一堆零散技巧带偏。如果你正在做网页端调用本地模型，不妨按这篇的顺序先把链路验证一遍。遇到过几次问题之后你就会发现，浏览器报错的每一行，其实都在告诉你链路中某一环的真实状态。