1. Android 超级工具类接入 AI 能力的真实痛点Android 项目里用 AndroidUtilCode 这类超级工具类Utils 聚合层已经是很常见的做法implementation com.blankj:utilcodex:1.25.9一行依赖就能拿到 Activity、网络、SP、线程、加密等几百个静态方法。但当你想在 App 里加一个「AI 对话」「智能摘要」「代码补全」这类能力时问题就来了Key 写在哪请求参数怎么统一不同模块各自 new 一个 OkHttp 客户端鉴权头散落在十几个文件里改一次 BaseUrl 要全局搜索替换。我见过最典型的翻车场景三个业务模块各自维护一份 API Key测试环境切生产环境时漏改了一个线上直接 401还有人把 Key 硬编码进 BuildConfig反编译就能拿到。这些问题的根子不在网络库而在于没有把 AI 接入当成工具类层的一个统一能力来管理。这篇要解决的就是这件事在已有的超级工具类初始化入口通常是 Application.onCreate 或一个Utils.init()聚合方法里集中管理 AI 通道的鉴权与请求参数用一份config.toml骨架承载配置做到一次配置、全局复用。适合正在做 Android 工程化、想把 AI 能力接进现有 Utils 体系的开发者。下面从配置骨架到工具类代码、再到调用验证和报错排查一步步给可复制的方案。2. 前置准备TaoToken 统一 Key 与通道在动手改工具类之前先把「统一 Key」这件事落地。TaoToken 提供的是 OpenAI 兼容风格的 API 通道也就是说你现有的 OkHttp/Retrofit 请求结构基本不用大改只需要把 BaseUrl 和鉴权头指向它即可。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 这个地址不加 UTM 参数直接用于代码里的 BaseUrl。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制出来形如sk-xxxxxxxx。这个 Key 就是全局唯一凭据后面所有模块都复用它不再各自申请。创建入口https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。注意Key 不要提交到 Git。推荐放在local.properties或 CI 的环境变量里构建时通过buildConfigField注入而不是写死在config.toml的明文里。config.toml只放非敏感的通道参数BaseUrl、超时、默认模型名Key 走运行时注入。如果你还想先验证模型是否可用、返回格式对不对可以直接在模型对话页面手动发一条消息试试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认通道通了再往下写 Android 侧代码能省掉一半「到底是网络问题还是代码问题」的排查时间。3. config.toml 骨架与工具类初始化代码3.1 config.toml 骨架把 AI 通道的配置集中到一个 TOML 文件里放在app/src/main/assets/config.tomlApp 启动时读取解析。这样改配置不用重新编译代码逻辑只换资源文件即可。# app/src/main/assets/config.toml [ai] # 通道根地址末尾不要带斜杠 base_url https://taotoken.net/api # 默认模型按需替换 default_model gpt-4o-mini # 单次请求超时秒 connect_timeout 15 read_timeout 60 write_timeout 30 # 是否开启请求日志仅 Debug 建议 true enable_log true [ai.headers] # 固定请求头Key 在运行时注入不写这里 content_type application/json accept application/json [ai.retry] max_attempts 3 backoff_ms 5003.2 解析 TOML 并注入 KeyAndroid 原生没有 TOML 解析器加一个轻量依赖即可。在app/build.gradle里dependencies { implementation com.blankj:utilcodex:1.25.9 implementation com.moandjiezana.toml:toml4j:0.7.2 implementation com.squareup.okhttp3:okhttp:4.12.0 }然后在工具类聚合层里写一个AiConfig单例负责读 TOML、拼 Key、暴露配置对象public final class AiConfig { private static volatile AiConfig instance; private final String baseUrl; private final String defaultModel; private final int connectTimeout; private final int readTimeout; private final boolean enableLog; private final String apiKey; private AiConfig(Context context) { // 从 assets 读取 config.toml Toml toml new Toml().read(ResourceUtils.readAssets2String(config.toml)); Toml ai toml.getTable(ai); this.baseUrl ai.getString(base_url); this.defaultModel ai.getString(default_model); this.connectTimeout ai.getLong(connect_timeout).intValue(); this.readTimeout ai.getLong(read_timeout).intValue(); this.enableLog ai.getBoolean(enable_log); // Key 从 BuildConfig 注入不落盘明文 this.apiKey BuildConfig.AI_API_KEY; } public static AiConfig get(Context context) { if (instance null) { synchronized (AiConfig.class) { if (instance null) { instance new AiConfig(context.getApplicationContext()); } } } return instance; } public String getBaseUrl() { return baseUrl; } public String getDefaultModel() { return defaultModel; } public int getConnectTimeout() { return connectTimeout; } public int getReadTimeout() { return readTimeout; } public boolean isEnableLog() { return enableLog; } public String getApiKey() { return apiKey; } }BuildConfig.AI_API_KEY在build.gradle里这样注入从local.properties读def localProps new Properties() def localFile rootProject.file(local.properties) if (localFile.exists()) { localProps.load(new FileInputStream(localFile)) } android { defaultConfig { buildConfigField String, AI_API_KEY, \${localProps.getProperty(AI_API_KEY, )}\ } }3.3 统一请求客户端在超级工具类的初始化入口比如Utils.init()或自定义的AppUtils.init()里把 OkHttp 客户端建好全局复用public final class AiHttpClient { private static volatile OkHttpClient client; public static OkHttpClient get(Context context) { if (client null) { synchronized (AiHttpClient.class) { if (client null) { AiConfig cfg AiConfig.get(context); OkHttpClient.Builder builder new OkHttpClient.Builder() .connectTimeout(cfg.getConnectTimeout(), TimeUnit.SECONDS) .readTimeout(cfg.getReadTimeout(), TimeUnit.SECONDS) .addInterceptor(chain - { Request original chain.request(); Request req original.newBuilder() .header(Authorization, Bearer cfg.getApiKey()) .header(Content-Type, application/json) .build(); return chain.proceed(req); }); if (cfg.isEnableLog()) { builder.addInterceptor(new HttpLoggingInterceptor() .setLevel(HttpLoggingInterceptor.Level.BODY)); } client builder.build(); } } } return client; } }这样所有模块调用 AI 时只需要AiHttpClient.get(context)鉴权头、超时、日志全部统一改一处全局生效。4. 验证请求发一条对话看结果配置写完了得验证通道真的通。写一个最小的调用方法放在工具类里public static String chat(Context context, String prompt) throws IOException { AiConfig cfg AiConfig.get(context); JSONObject body new JSONObject(); body.put(model, cfg.getDefaultModel()); JSONArray messages new JSONArray(); JSONObject msg new JSONObject(); msg.put(role, user); msg.put(content, prompt); messages.put(msg); body.put(messages, messages); Request request new Request.Builder() .url(cfg.getBaseUrl() /v1/chat/completions) .post(RequestBody.create( body.toString(), MediaType.parse(application/json))) .build(); try (Response response AiHttpClient.get(context) .newCall(request).execute()) { if (!response.isSuccessful()) { throw new IOException(HTTP response.code() body (response.body() null ? : response.body().string())); } return response.body().string(); } }调用验证String result AiUtils.chat(getApplicationContext(), 用一句话解释什么是协程); LogUtils.d(result);成功时你会看到类似这样的返回结构截取关键字段{ id: chatcmpl-xxx, object: chat.completion, model: gpt-4o-mini, choices: [ { index: 0, message: { role: assistant, content: 协程是一种可以挂起和恢复执行的轻量级线程... }, finish_reason: stop } ], usage: { prompt_tokens: 12, completion_tokens: 30, total_tokens: 42 } }看到choices[0].message.content有内容说明通道、Key、请求体三件事都对了。如果返回 401往下看排查章节。5. 本篇常见报错排查5.1 401 Unauthorized最常见。先确认BuildConfig.AI_API_KEY是否为空——在local.properties里加了AI_API_KEYsk-xxx之后必须重新 Sync 并 Rebuild否则 BuildConfig 不会更新。其次检查请求头是不是Bearer加空格再加 Key少空格会直接 401。最后确认 Key 没有多余换行从控制台复制时容易带上尾部空白。5.2 404 Not Found多半是 BaseUrl 拼错了。config.toml里base_url末尾不要带斜杠代码里拼/v1/chat/completions。如果你写成了https://taotoken.net/api/拼出来就是双斜杠部分网关会返回 404。统一约定配置里不带尾斜杠代码里路径以斜杠开头。5.3 读取 config.toml 抛 FileNotFoundExceptionResourceUtils.readAssets2String(config.toml)的路径是相对 assets 根目录的。如果你放在assets/config/config.toml参数就要写config/config.toml。另外确认 build.gradle 里没有对 assets 做 exclude 过滤。5.4 超时或连接被重置先看read_timeout。AI 生成内容较慢默认 60 秒比较稳妥设成 10 秒很容易在长回复时超时。如果连接阶段就失败检查设备网络是否正常以及connect_timeout是否过短。注意不要在 OkHttp 里再叠加一层自定义 DNS 或拦截器改写 Host容易和通道地址冲突。5.5 返回 200 但 content 为空检查messages数组是否为空或者model字段填了一个不存在的模型名。有些网关对未知模型不报错直接返回空 choices。把default_model换成控制台里确认可用的模型名再试。6. 把 AI 能力沉淀进工具类体系走到这里你的 Android 工程已经有了一条统一的 AI 通道config.toml管非敏感参数BuildConfig注入 KeyAiHttpClient统一鉴权和超时AiUtils.chat()作为业务调用入口。后续要加「流式输出」「多轮对话」「函数调用」都只需要在这套骨架上扩展不用再动散落各处的请求代码。如果你还在验证阶段想快速确认某个模型返回格式对不对可以直接用模型对话页面手动测https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。等通道确认无误再回到 Android 侧接。Key 的创建和管理都在 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入过程中如果遇到请求格式、鉴权头、路径拼接的问题接入文档里有完整的参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。一个实用建议把AiUtils的调用全部收敛到工具类层业务模块只传 prompt 和回调不直接碰 OkHttp 和 JSON 拼装。这样将来换模型、加缓存、做限流都只改工具类一处业务代码零改动。这套结构我在几个中型 App 里跑过最直观的收益是排查问题时只需要看一个文件而不是全局搜索Authorization。