1. 本地多 AI 工具调用为什么需要 Traefik 统一入口如果你同时用 Claude Code、Cline、Codex CLI、Continue 这类工具大概率遇到过同一个问题每个工具都要单独配 Base URL有的写https://taotoken.net/api有的要带/v1有的走 Anthropic 协议有的走 OpenAI 协议。时间一长配置文件散落在~/.claude/settings.json、~/.codex/auth.json、VS Code 的settings.json里改一个 Key 要翻五六个地方。Traefik 在这里的价值是把这些分散的 endpoint 收敛到一个本地入口。你在本机跑一个 Traefik 容器监听127.0.0.1:8080所有 AI 工具都指向这个地址。Traefik 通过 Entrypoints 接住请求用 Routers 按路径或 Header 分流Middlewares 统一注入鉴权头、限流、重试Services 再把请求转发到真正的上游。这样你只需要维护一份 Traefik 动态配置工具侧只改一个 Base URL。我试过在 macOS 上用 Docker Desktop 跑这套结构配合 TaoToken 的统一 API 通道把 Claude Code 和 Cline 的请求都收敛到http://localhost:8080。下面把 Entrypoints、Routers、Services、Middlewares 四层拆开讲每层都给可复制的配置片段最后用 curl 验证路由命中和鉴权头透传。先明确四个概念在本地调试场景里的分工。Entrypoints 是 Traefik 监听的端口比如:8080给 HTTP、:8443给 HTTPS。Routers 是匹配规则决定一个请求该走哪条链路规则可以基于 Host、PathPrefix、Headers。Middlewares 是请求在到达 Service 之前或之后执行的加工逻辑比如加Authorization头、去掉路径前缀、限流。Services 是最终转发目标指向 TaoToken 的 API 地址。四层是串联关系请求先进 Entrypoint被 Router 匹配过 Middleware 链最后到 Service。为什么不用 Nginx 或直接改 hostsNginx 配置改完要 reload动态性差hosts 只能改域名不能改路径和 Header。Traefik 的 file provider 支持热加载改完dynamic.yml保存即生效不用重启容器。对于本地调试这种频繁改配置的场景体验差别很明显。还有一个现实问题TaoToken 的 API 通道对 Anthropic 和 OpenAI 两种协议都有支持但不同工具默认拼的路径不一样。Claude Code 默认请求/v1/messagesCline 可能请求/v1/chat/completions。如果每个工具都直连你得记住每个工具的路径规则。用 Traefik 做一层路径重写和 Header 注入工具侧只认一个 Base URL路径差异在 Middleware 里消化掉。这一节先把场景和四层职责说清楚下一节讲 TaoToken 侧需要准备什么。2. TaoToken 统一 API 通道的前置准备TaoToken 在这里扮演的是上游服务提供方。你的 Traefik Service 最终要转发到https://taotoken.net/api所以需要先拿到一个可用的 API Key并确认你要调用的模型 ID。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完 Key 之后在 API Keys 页面可以查看和管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。你需要记下三样东西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api注意这个地址不带 UTM 参数是纯 API 端点。API Key 形如sk-开头的一串字符。Model ID 取决于你要用的模型比如claude-sonnet-4-20250514或gpt-4o这类具体以控制台模型列表为准。如果你不确定模型 ID 怎么写可以先用模型对话页面测一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。在对话界面选一个模型发一条消息确认通道可用再回到本地配 Traefik。这一步能排除掉 Key 本身的问题避免后面排障时把上游鉴权失败误判成 Traefik 配置错误。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面会说明不同协议的路径和 Header 要求。Anthropic 协议通常需要x-api-key和anthropic-version两个头OpenAI 协议用Authorization: Bearer key。Traefik 的 Middleware 可以帮你统一注入这些头这样工具侧就不用各自处理。关于 Coding Plan如果你打算长期用 Claude Code 或 Codex 做编码可以看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它和按量计费的 API Key 是两条线本地调试阶段用 API Key 就够了等稳定跑起来再考虑套餐。前置准备清单项目值用途Base URLhttps://taotoken.net/apiTraefik Service 转发目标API Keysk-xxxxMiddleware 注入鉴权头Model ID如claude-sonnet-4-20250514工具侧请求体里的 model 字段本地端口127.0.0.1:8080Traefik Entrypoint 监听拿到这三样之后就可以开始写 Traefik 配置了。下一节给完整的 docker-compose 和动态配置片段。3. 可复制的 docker-compose 与动态配置片段这一节是核心给两份配置docker-compose.yml负责起 Traefik 容器dynamic.yml负责定义 Routers、Middlewares、Services。两份文件放在同一个目录下比如~/traefik-ai/。先看docker-compose.ymlversion: 3.9 services: traefik: image: traefik:v3.1 container_name: traefik-ai restart: unless-stopped ports: - 127.0.0.1:8080:8080 - 127.0.0.1:8081:8081 volumes: - ./traefik.yml:/etc/traefik/traefik.yml:ro - ./dynamic.yml:/etc/traefik/dynamic.yml:ro extra_hosts: - host.docker.internal:host-gateway这里映射了两个端口8080是业务入口AI 工具请求打到这里8081是 Traefik Dashboard方便看路由是否命中。extra_hosts是为了容器内能访问宿主机服务如果你后面要转发到本机跑的 mock 服务会用到。静态配置traefik.ymlentryPoints: ai: address: :8080 api: dashboard: true insecure: true providers: file: filename: /etc/traefik/dynamic.yml watch: true log: level: INFO accessLog: {}entryPoints.ai定义了监听:8080名字叫ai后面 Router 要引用这个名字。providers.file.watch: true是关键改dynamic.yml后 Traefik 自动热加载不用重启容器。accessLog打开后能在容器日志里看到每个请求命中了哪个 Router。动态配置dynamic.yml是重点包含 Router、Middleware、Service 三部分http: routers: ai-anthropic: rule: PathPrefix(/v1/messages) entryPoints: - ai middlewares: - inject-anthropic-headers - rate-limit service: taotoken-api ai-openai: rule: PathPrefix(/v1/chat/completions) entryPoints: - ai middlewares: - inject-openai-headers - rate-limit service: taotoken-api middlewares: inject-anthropic-headers: headers: customRequestHeaders: x-api-key: sk-你的Key anthropic-version: 2023-06-01 inject-openai-headers: headers: customRequestHeaders: Authorization: Bearer sk-你的Key rate-limit: rateLimit: average: 30 burst: 15 services: taotoken-api: loadBalancer: servers: - url: https://taotoken.net/api passHostHeader: true逐段解释。routers.ai-anthropic的规则是PathPrefix(/v1/messages)意思是任何以/v1/messages开头的请求都走这条路由。它绑定了entryPoints: [ai]即只从:8080进来。中间件链先注入 Anthropic 需要的头再过限流。最后service: taotoken-api指向上游。inject-anthropic-headers用customRequestHeaders把x-api-key和anthropic-version写进请求头。这样 Claude Code 侧就不用在配置里放 KeyKey 只存在 Traefik 这一处。inject-openai-headers同理注入Authorization: Bearer。rate-limit设了平均 30 请求每秒、突发 15本地调试够用也能防止某个工具死循环把额度打满。services.taotoken-api的loadBalancer.servers指向https://taotoken.net/api。passHostHeader: true表示转发时保留原始 Host 头某些上游会校验这个。把 Key 替换成你自己的然后启动cd ~/traefik-ai docker compose up -d docker compose logs -f traefik日志里看到Configuration loaded from file和Starting provider *file.Provider就说明配置加载成功。打开http://127.0.0.1:8081能看到 Dashboard里面会列出ai-anthropic和ai-openai两条 Router。这里有个细节customRequestHeaders里的 Key 是明文写在dynamic.yml里的。本地调试可以接受但别把这个文件提交到 Git。更稳妥的做法是用环境变量Traefik 支持在配置里写${TAOTOKEN_KEY}然后在 compose 里通过environment传入。不过环境变量方式在 file provider 里需要额外开启本地调试先用明文、把文件加进.gitignore更省事。配置写完后工具侧只需要把 Base URL 改成http://localhost:8080。Claude Code 的settings.json里改ANTHROPIC_BASE_URLCline 的配置里改 OpenAI Base URL。Key 可以留空或填占位符因为 Traefik 会覆盖注入。下一节用 curl 验证路由命中和鉴权头透传。4. 用 curl 验证路由命中与鉴权头透传配置起好之后别急着改工具配置先用 curl 打一发确认 Traefik 这层是通的。这样出问题时能快速定位是 Traefik 的问题还是工具的问题。先测 Anthropic 路径。构造一个最小请求curl -i -X POST http://127.0.0.1:8080/v1/messages \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 32, messages: [{role: user, content: ping}] }注意这里没有手动加x-api-key因为 Traefik 的 Middleware 会注入。如果返回 200 并且 body 里有模型回复说明三件事都对了Router 匹配到了/v1/messagesMiddleware 注入了鉴权头Service 转发到了 TaoToken。如果返回 401先看 Traefik 日志docker compose logs traefik | grep v1/messagesaccess log 里会显示请求命中了哪条 Router、状态码多少。如果日志里根本没有这条请求说明请求没进 Traefik检查端口映射和 curl 地址。如果日志里有请求但状态码 401说明 Middleware 没注入成功检查dynamic.yml里customRequestHeaders的 Key 是否正确、缩进是否对。再测 OpenAI 路径curl -i -X POST http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o, max_tokens: 32, messages: [{role: user, content: ping}] }这条走ai-openaiRouterMiddleware 注入的是Authorization: Bearer。如果两条都通说明 Router 分流和 Middleware 注入都正常。想确认鉴权头到底有没有透传可以在 Traefik 前面再挂一个 echo 服务或者临时把 Service 指向一个能回显 Header 的地址。更简单的办法是看 TaoToken 返回的错误信息如果 Key 无效它会返回鉴权失败如果 Key 有效但模型 ID 错会返回模型不存在。两种错误能区分开就说明请求确实带着 Key 到了上游。验证限流是否生效可以快速打 50 次for i in $(seq 1 50); do curl -s -o /dev/null -w %{http_code}\n \ -X POST http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model:gpt-4o,max_tokens:8,messages:[{role:user,content:hi}]} done | sort | uniq -c如果看到部分 429说明rateLimit中间件起作用了。本地调试时如果被限流误伤把average调大或临时去掉这个中间件。验证 Router 规则是否按预期匹配可以故意打一个不存在的路径curl -i http://127.0.0.1:8080/v1/unknown预期返回 404因为没有任何 Router 的规则匹配/v1/unknown。如果返回了别的状态码说明有 Router 规则写得太宽比如用了PathPrefix(/)。Dashboard 也能辅助验证。打开http://127.0.0.1:8081在 HTTP Routers 页面能看到每条 Router 的状态、规则、绑定的 Service。请求打过去之后Dashboard 上对应 Router 的请求计数会增加。这个可视化对排查“请求到底走了哪条路由”很直观。到这里Traefik 这层的验证就完成了。下一节列出本地调试时最容易踩的几个坑。5. 本地调试常见报错与排查对照这一节按真实报错来。本地跑 Traefik 接 TaoToken最容易遇到的是下面几类。401 Unauthorized且 Traefik 日志显示请求已命中 Router说明请求到了 Traefik但 Middleware 注入的头没被上游认可。检查dynamic.yml里customRequestHeaders的 Key 值注意不要有多余空格或换行。Anthropic 协议要的是x-api-keyOpenAI 协议要的是Authorization: Bearer两者不能混。如果你把 Anthropic 的请求打到了 OpenAI 的 Router 上头就对不上。用 Dashboard 确认请求命中的是哪条 Router。404 Not FoundTraefik 日志里没有对应请求请求没进 Traefik或者进了但没匹配到 Router。先确认 curl 地址是http://127.0.0.1:8080而不是https。再确认docker-compose.yml里端口映射是127.0.0.1:8080:8080左边右边一致。如果端口映射写成了8080:80Traefik 监听的是容器内 8080映射到宿主机 80curl 打 8080 就打不通。local proxy failed 或 connection refused这类错误通常出现在工具侧不是 Traefik 本身。工具配置的 Base URL 写成了http://localhost:8080/v1但 Traefik 的 Router 规则是PathPrefix(/v1/messages)工具又自己拼了/v1/messages结果路径变成/v1/v1/messages匹配不上。解决办法是工具侧 Base URL 只写到http://localhost:8080路径由工具自己拼Traefik 按完整路径匹配。或者反过来工具侧写全路径Traefik 用Path精确匹配。reading choices 报错或返回体解析失败这通常是协议不匹配。工具按 OpenAI 格式发请求但 Router 把它转到了 Anthropic 端点返回体结构对不上工具解析choices字段就报错。检查 Router 规则和工具实际请求路径是否一致。Cline 默认走 OpenAI 格式Claude Code 走 Anthropic 格式别把两者的路径配混。OAuth 相关报错有些工具比如 Codex CLI默认走 OAuth 登录流程不走 API Key。如果你用 Traefik 注入 Key需要先把工具切到 API Key 模式。Codex 的~/.codex/auth.json里如果还是 OAuth 的 token 结构请求不会带Authorization头Traefik 注入的头可能被覆盖或冲突。把auth.json改成 API Key 模式或者确认工具支持自定义 Header。配置改了不生效dynamic.yml改完保存Traefik 应该自动热加载。如果没生效检查traefik.yml里providers.file.watch是否为true。另外确认挂载路径正确./dynamic.yml:/etc/traefik/dynamic.yml:ro冒号两边路径要对。改完可以看日志有没有Configuration reloaded字样。CC Switch / Cline MCP / Codex auth.json 三件套如果你用 CC Switch 管理多个 Claude Code 配置或者用 Cline 的 MCP 功能或者改 Codex 的auth.json记住三件套要写全Base URL、Key、Model ID。Base URL 填http://localhost:8080Key 填占位符Traefik 会覆盖Model ID 填真实模型名。三样缺一请求要么打不到 Traefik要么到了上游被拒。排障时优先看 Traefik 的 access log它能告诉你请求有没有进来、命中了哪条 Router、返回什么状态码。大部分问题看日志就能定位。如果日志里请求正常但上游报错问题在 TaoToken 侧检查 Key 和模型 ID。6. 把本地入口固定下来工具侧只改一处走到这里Traefik 的四层已经跑通了。Entrypoints 接住:8080的请求Routers 按/v1/messages和/v1/chat/completions分流Middlewares 注入鉴权头和限流Services 转发到 TaoToken。curl 验证过路由命中和 Header 透传常见报错也有对照。接下来把工具侧收敛。Claude Code 的settings.json里把ANTHROPIC_BASE_URL改成http://localhost:8080Key 留占位符。Cline 的 OpenAI Base URL 同样改成http://localhost:8080。Codex 的auth.json切到 API Key 模式Base URL 指向本地。这样所有工具的出口都是同一个本地地址Key 只在dynamic.yml里维护一份。如果后面要加新工具只需要在dynamic.yml里加一条 Router 规则匹配新工具的路径复用现有的 Middleware 和 Service。不用动其他工具的配置。这就是统一入口的价值变更点收敛到一处。长期用下来如果 API Key 调用量上来了可以看看 Coding Plan 是否更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。本地调试阶段先用 API Key等稳定了再评估。最后提醒一句dynamic.yml里有明文 Key记得加进.gitignore。如果要把配置分享给别人先把 Key 替换成占位符。Traefik 的 Dashboard 默认insecure: true只监听本地别把它暴露到公网。