NewAPI on 魔都水滴

别把 API Key 到处塞了：我用 NewAPI 搭了一个自用 AI 中转站

Fri, 10 Jul 2026 15:30:00 +0800

先说结论

NewAPI 不是一个“白嫖模型”的工具，也不是一个神秘代理。它更像我家里的“AI 前台”：所有 App 只认一个入口，前台负责转发到合法授权的上游模型，顺手做令牌、额度、分组、日志、模型限制和用量统计。对自用场景来说，最舒服的地方不是“多了一个网页”，而是终于不用把每个上游 Key 分散塞进十几个客户端。

本文会按我自己搭自用中转站的思路写：为什么需要它、容易误解在哪里、最小可用 Docker Compose 怎么跑、为什么我建议加持久化目录、Windows 11 / Ubuntu 26.04 / macOS 26 三套一键脚本怎么写，以及让 Agent 自动配置时应该给它什么边界。全文不放真实内网地址、完整主机名、私有域名和任何密钥。

一个 operator.write 把网关干翻：OpenClaw fallback 模型为什么突然全体认证失败？

Fri, 10 Jul 2026 08:00:00 +0800

这次问题表面上很像“模型供应商挂了”：OpenClaw 刚加完 NewAPI 的几个 fallback 模型，命令一跑，直接报 Provider authentication failed；进一步看网关调用，真正的错误是：

missing scope: operator.write

如果只看第一层现象，很容易把锅甩给模型密钥、NewAPI 地址、模型名、网络连通性。但这次真正的问题不在模型，也不在 NewAPI，而在 OpenClaw 走网关调用 fallback 模型时，某个 model override 分支把“设备身份”省掉了。结果服务端虽然看到了一个被授权的请求，却没有把它绑定到那台已经配对、已经拥有 operator.write 的设备上，最终在执行 agent RPC 时被权限系统拦下。

先说结论：这是一个典型的“令牌有了，钥匙串没带上”的问题。 模型直连能成功，网关调用失败；设备列表里明明能看到 operator.write，但真正发起网关请求时没有使用那份已配对设备身份，于是权限检查按未绑定请求处理，报出 missing scope: operator.write。

别再让 Agent 吞掉你的 Token：我把 Headroom 接到 NewAPI、OpenClaw 和 HermesAgent 的完整实战

Sat, 20 Jun 2026 12:30:00 +0800

先说结论

这次我没有替换原来的 NewAPI，也没有让 OpenClaw / HermesAgent 直接改用一个不确定的新网关。真正做法是：在 NewAPI 前面加一层 Headroom 代理，把所有已经使用 OpenAI-compatible 协议的调用改到 http://<headroom-host>:8787/v1，而原来的 NewAPI 入口继续保留。这样 Agent 发来的长上下文先经过 Headroom 压缩，再转发给 NewAPI，最后仍由 NewAPI 统一路由到后端模型。

最关键的原则只有一句：先测试，后修改；只迁移测试通过的 OpenAI-compatible 项；非 OpenAI 协议的 fallback 不碰。 这篇文章既是复盘，也是一份可以直接交给 Agent 或人工照着执行的操作指南。

一次流式响应被重复消费：NewAPI v1.0.0-rc.10 MiniMax 转发 Bug 排查实录

Sun, 31 May 2026 18:00:00 +0800

先说结论

问题现象：AI Agent 在 DingTalk 通道中回复了重复的文本。消息不是发送了两次，而是一条消息里的内容被复制了一遍。排障最终定位到 NewAPI（QuantumNous 维护的 OneAPI 分支）v1.0.0-rc.10 版本的一个流式响应 Bug：当通过 OpenAI Chat Completions 协议转发 MiniMax 模型时，finish chunk 会同时包含 delta.content 和 message.content，且两者内容完全一致。Agent 框架的流式处理器将两者都当作"可见文本"消费，导致最终文本被拼接两次。修复方案也很朴素：将 OpenClaw provider 协议从 openai-completions 切换到 anthropic-messages，OneAPI 原生支持该协议，且该路径下流式响应正常。

本文不会出现任何真实内网地址、Token、模型 ID 或私有路径。所有配置片段都已脱敏。

HermesAgent 为什么一直不回微信和企业微信？我最后排到的根因居然是本地 relay 的 3 秒超时

Sun, 31 May 2026 08:00:00 +0800

先说结论

这次故障看起来像“模型不行”或者“微信通道坏了”，但真正把消息链路掐断的，是我本地那层 relay 的超时设置。它把整条上游请求的等待窗口限制成了 3 秒，而真实的 WeChat / WeCom 消息 turn 往往需要更久才能从新 API 网关拿到完整回复。结果就是：relay 先断开，HermesAgent 只能看到 Connection error、RemoteProtocolError，然后主模型和 fallback 一起被耗尽。

更准确地说，这不是 HermesAgent 核心代码的问题，也不是模型名的问题，而是一个本地外置组件的连接策略问题。把 connect timeout 和 response wait 混成同一个超时，等于给长请求做了一个错误的截止时间。修复方式也不复杂：连接阶段保留短超时，连接成功后把 socket 切回阻塞等待；同时把 relay 做成独立、可持续启动的服务，不再把它绑死在临时 shell 里。

问题背景

HermesAgent 这条链路不是单机脚本，而是一条完整的消息生产线。用户从微信或企业微信发出一句话，消息会先进入 Hermes 的通道层，再进入 Gateway，接着经过本地 relay 转发到自建的 NewAPI 网关，最后才到模型服务。模型回来的内容还要经过 Hermes 的消息整理、工具调用处理、最终拼接，再发回原始通道。

这种结构的好处是灵活，坏处也很现实：任何一层都可能制造“看起来像模型故障”的表象。你看到的是“没有回复”或者“Connection error”，但根因可能在更外层的 relay、socket、超时、代理或者会话路由里。

这次我一开始也走了老路，先怀疑模型配置。因为从表象看，主模型和 fallback 都失败了，日志里反复出现：

Primary model failed
switching to fallback
API failed after 1 retries
Connection error
Max retries exhausted

如果你只看这一段，很容易得出“模型端不稳定”的结论。但这类结论通常太早。因为同一批模型在别的入口上是能正常工作的，/v1/models 也能返回，简单的 health check 也没有异常。真正出问题的是“真实消息 turn”。