1. 从「能对话」到「能管 Key」mac 智能问数客户端的接入痛点前几篇我们把 Electron React 的壳搭起来了窗口能开、页面能渲染、/health也能探测到后端。但真正跑一次问数请求时问题就冒出来了客户端里散落着好几处模型调用——问数走 Text-to-SQL 的 LLM、知识库问答走 RAG 的 LLM、SQL 生成阶段可能还想换个更便宜的模型。每处都硬编码一个base_url和api_key改一次要翻三个文件换模型要重新打包这在 mac 客户端这种「装一次用很久」的场景里非常难受。这一篇要解决的就是这件事把多模型 Key 收敛成一套统一通道用settings.json做运行时配置骨架用config.toml做模型路由骨架让客户端在不重新构建的前提下切换模型、切换通道。适合已经跑通基础对话、手里有不止一个模型 Key、想让 mac 客户端「配置化」而不是「硬编码化」的开发者。核心检索词先摆出来Codex 辅助开发、mac 客户端、Electron React、TaoToken 统一 Key、settings.json 配置骨架。读完你应该能做到客户端启动时读本地配置从统一通道拿模型能力发一次真实问数请求并看到 SQL 和结果表格返回。2. TaoToken 前置统一 Key 与 API 通道是什么在动手改代码之前先把「统一 Key」这件事讲清楚不然后面配置项为什么这么设计会看不懂。传统做法是每个模型厂商一个 Key、一个 endpoint。客户端里就会出现这样的代码智谱一个 client、DeepSeek 一个 client、OpenAI 一个 client每个都要处理鉴权头、超时、重试。模型一多配置管理成本指数上升。TaoToken 的思路是提供一个统一的 API 通道你只需要一个 Key通过同一个 base URL 访问模型名在请求体里指定。对 Electron 客户端来说这意味着api/client.ts里只需要维护一份鉴权逻辑模型切换变成改一个字符串。官网入口在这里注册和看文档都从这进https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_jsonAPI 基地址注意这个不带 UTM是给代码里用的https://taotoken.net/api你需要提前准备两样东西一个 API Key以及确认你要用的模型名。Key 在控制台的 API Keys 页面创建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_json注意Key 只显示一次创建后立刻复制到安全的地方。不要提交进 git后面我们会用.env和.gitignore把它挡在仓库外。模型名怎么确认最直接的办法是去模型对话页面手动发一条消息看它实际调用的是哪个模型标识https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_json接入文档里有完整的请求格式、SSE 事件说明和错误码配置骨架的字段设计就是照着它来的https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_json3. 可复制配置settings.json 与 config.toml 骨架这一节是全文的技术核心。我们设计两层配置settings.json管「运行时可变的东西」Key、base URL、超时、日志级别config.toml管「模型路由」哪个场景用哪个模型、温度多少、最大 token。为什么分两层因为 Key 和地址属于敏感 环境相关模型路由属于业务逻辑两者变更频率和权限不同。3.1 目录约定在项目根目录建一个config/目录开发时读本地文件打包后读用户目录。约定如下zhinengwenshu-mac-client/ ├── config/ │ ├── settings.json # 运行时配置开发用git 忽略 │ ├── settings.example.json # 模板提交进仓库 │ └── config.toml # 模型路由提交进仓库 ├── .env # 只放 VITE_API_BASE 等非敏感项 └── src/ └── api/ ├── client.ts # 统一请求层 └── config.ts # 配置加载器3.2 settings.json 骨架先看模板文件config/settings.example.json复制成settings.json后填入真实值{ provider: { baseUrl: https://taotoken.net/api, apiKey: sk-替换成你的Key, timeoutMs: 60000, maxRetries: 2 }, client: { apiBase: http://127.0.0.1:8001, healthIntervalMs: 30000 }, logging: { level: info, logSseEvents: true } }字段说明用表格对照更清楚字段类型作用建议值provider.baseUrlstring统一 API 通道地址https://taotoken.net/apiprovider.apiKeystring统一 Key控制台创建provider.timeoutMsnumber单次请求超时60000provider.maxRetriesnumber失败重试次数2client.apiBasestring问数后端地址http://127.0.0.1:8001client.healthIntervalMsnumber健康探测间隔30000logging.logSseEventsboolean是否打印 SSE 事件调试期 true注意settings.json必须加进.gitignore。仓库里只留settings.example.json别人 clone 后自己复制一份填 Key。3.3 config.toml 骨架config/config.toml负责模型路由。问数场景和知识库问答场景对模型的要求不一样问数要强 SQL 能力知识库问答要长上下文和稳定输出。分开配置[default] model deepseek-chat temperature 0.2 max_tokens 2048 [scenes.ask] model deepseek-chat temperature 0.1 max_tokens 2048 description Text-to-SQL 主模型低温度保证 SQL 稳定 [scenes.kb_qa] model glm-4-plus temperature 0.3 max_tokens 4096 description 知识库问答需要长上下文 [scenes.sql_repair] model deepseek-chat temperature 0.0 max_tokens 1024 description SQL 报错后的修复重试温度归零这样设计的好处客户端代码里只写scene ask具体用哪个模型由 toml 决定。想换模型改一行 toml不用碰 TypeScript。3.4 配置加载器实现在src/api/config.ts里写加载逻辑。Electron 主进程和渲染进程读文件的方式不同这里走 preload 暴露的 IPC 更稳但为了先跑通我们用 Vite 的import.meta.glob在构建期把配置打进去运行时用window.__APP_CONFIG__覆盖// src/api/config.ts export interface ProviderConfig { baseUrl: string; apiKey: string; timeoutMs: number; maxRetries: number; } export interface AppConfig { provider: ProviderConfig; client: { apiBase: string; healthIntervalMs: number }; logging: { level: string; logSseEvents: boolean }; } const FALLBACK: AppConfig { provider: { baseUrl: https://taotoken.net/api, apiKey: , timeoutMs: 60000, maxRetries: 2, }, client: { apiBase: http://127.0.0.1:8001, healthIntervalMs: 30000 }, logging: { level: info, logSseEvents: true }, }; let cached: AppConfig | null null; export function loadConfig(): AppConfig { if (cached) return cached; const injected (window as any).__APP_CONFIG__ as PartialAppConfig | undefined; cached { provider: { ...FALLBACK.provider, ...(injected?.provider ?? {}) }, client: { ...FALLBACK.client, ...(injected?.client ?? {}) }, logging: { ...FALLBACK.logging, ...(injected?.logging ?? {}) }, }; if (!cached.provider.apiKey) { console.warn([config] provider.apiKey 为空请检查 settings.json); } return cached; }主进程在创建窗口前把settings.json读出来通过additionalArguments或 preload 注入到window.__APP_CONFIG__。这样渲染进程拿到的就是合并后的配置且 Key 不出现在前端源码里。4. 统一请求层与一次真实问数验证配置有了接下来把src/api/client.ts改成走统一通道。核心是把原来散落的 fetch 收敛成一个chatCompletion函数SSE 解析逻辑复用现有的。4.1 统一请求函数// src/api/client.ts import { loadConfig } from ./config; export interface ChatMessage { role: system | user | assistant; content: string; } export interface ChatOptions { scene?: string; model?: string; temperature?: number; maxTokens?: number; signal?: AbortSignal; } export async function chatCompletion( messages: ChatMessage[], opts: ChatOptions {}, ): Promisestring { const cfg loadConfig(); const { baseUrl, apiKey, timeoutMs, maxRetries } cfg.provider; const body { model: opts.model ?? deepseek-chat, messages, temperature: opts.temperature ?? 0.2, max_tokens: opts.maxTokens ?? 2048, stream: false, }; let lastErr: unknown; for (let attempt 0; attempt maxRetries; attempt) { const ctrl new AbortController(); const timer setTimeout(() ctrl.abort(), timeoutMs); try { const res await fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey}, }, body: JSON.stringify(body), signal: opts.signal ?? ctrl.signal, }); clearTimeout(timer); if (!res.ok) { const text await res.text(); throw new Error(HTTP ${res.status}: ${text.slice(0, 200)}); } const data await res.json(); return data.choices?.[0]?.message?.content ?? ; } catch (err) { clearTimeout(timer); lastErr err; if (attempt maxRetries) { await new Promise((r) setTimeout(r, 500 * (attempt 1))); } } } throw lastErr; }4.2 接到问数流程里问数页原来的逻辑是「用户提问 → 调后端/ask→ SSE 流式返回 SQL 和结果」。现在把「生成 SQL」这一步改成走统一通道后端只负责执行 SQL 和返回数据。在AskPage里加一个前置步骤// src/pages/AskPage.tsx 片段 import { chatCompletion } from /api/client; async function generateSql(question: string, schema: string) { const content await chatCompletion( [ { role: system, content: 你是 SQL 生成器。根据表结构生成 MySQL 查询语句只输出 SQL不要解释。\n表结构\n${schema}, }, { role: user, content: question }, ], { scene: ask, temperature: 0.1, maxTokens: 1024 }, ); return content.trim().replace(/^sql\n?/, ).replace(/$/, ); }4.3 一次请求验证配置和代码都就位后做一次最小验证。先确认后端在跑curl -s http://127.0.0.1:8001/health返回{status:ok}说明后端正常。然后启动客户端开发模式cd /Users/mac/data/devwork/cc-wk/zhinengwenshu-mac-client npm run dev窗口打开后在问数页输入一个简单问题比如「统计上个月订单总数」。预期看到Header 状态显示「已连接后端 API」页面先出现 SQL 生成中的提示然后展示生成的 SQL最后是结果表格和图表。如果 SQL 生成这一步没反应打开 DevTools 看 Network找chat/completions请求。成功的话返回体里choices[0].message.content就是 SQL 文本。实测下来第一次请求因为要建立连接会慢一点后续基本在 1-2 秒内返回。5. 本篇常见错排查配置化改造最容易踩的坑集中在「配置没读到」和「请求格式不对」两类。下面按报错现象倒推。5.1 报 401 Unauthorized现象请求返回 401控制台提示鉴权失败。排查顺序先确认settings.json里provider.apiKey不是空字符串也不是模板里的sk-替换成你的Key。再看Authorization头是不是Bearer加 Key中间有空格。最后确认 Key 没有多余换行——从控制台复制时容易带上。5.2 报 404 Not Found现象请求打到https://taotoken.net/api/v1/chat/completions返回 404。大概率是 baseUrl 写错了。正确写法是https://taotoken.net/api代码里拼/v1/chat/completions。如果你在 settings.json 里写成了https://taotoken.net/api/v1就会变成/v1/v1/chat/completions。检查一下有没有重复路径段。5.3 配置改了不生效现象改了settings.json重启客户端行为没变。原因通常是配置在构建期被打进 bundle 了运行时注入没覆盖成功。检查主进程有没有在new BrowserWindow之前读文件并注入window.__APP_CONFIG__。另一个可能是 Vite 缓存删掉node_modules/.vite再启动。5.4 SSE 流式返回中断现象问数过程中 SQL 生成到一半停了。先看provider.timeoutMs是不是设太短。流式请求的总时长可能超过 60 秒超时设 60000 对长 SQL 偏紧可以调到 120000。另外确认maxRetries在流式场景下不要盲目重试否则会重复生成。流式请求建议单独走一个不带重试的函数。5.5 模型名不识别现象返回model not found或类似错误。去模型对话页面确认当前可用的模型标识把config.toml里的model字段改成实际存在的名字。注意大小写和连字符deepseek-chat和DeepSeek-Chat可能不通用。排障时如果拿不准是 Key 问题还是通道问题先去 API Keys 页面确认 Key 状态再对照接入文档核对请求格式。两个入口都在下面。6. 把配置骨架用起来下一步怎么走到这里mac 智能问数客户端的 AI 接入层已经从「硬编码」变成了「配置驱动」。settings.json管通道和 Keyconfig.toml管模型路由client.ts管统一请求三者职责清晰。你换模型只需要改 toml换 Key 只需要改 json都不用重新打包。如果你接下来要长期在这个客户端上做编码和 Agent 相关的功能迭代比如让客户端自己调工具、跑多轮 SQL 修复可以看看 Coding Plan它更适合这种持续性的开发场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_json如果只是想先验证某个模型在问数场景下的表现直接去模型对话页面手动试几条比改代码快https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_jsonKey 管理和接入细节分别在这两个页面建议收藏https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_json https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsettings_json最后留一个实操建议把settings.example.json里的字段注释写清楚团队里别人接手时不用问你 Key 填哪。配置文件的可读性往往比代码的可读性更影响协作效率。