1. macOS 上从零跑通安卓开发环境到底卡在哪
如果你刚拿到一台 Mac，想写个安卓 App，大概率会在前两个小时里被三件事反复劝退：JDK 版本对不上、Gradle 同步转圈转到怀疑人生、SDK 路径找不到。这套「mac 安卓开发环境」的搭建流程本身不复杂，但坑都藏在版本匹配和网络下载上。我这次的目标很明确：在一台干净的 macOS 上，从 JDK 开始，把 Android Studio、SDK、Gradle 全部配好，跑通第一个 Empty Views Activity 项目，最后再把 AI 辅助编码的 Key 统一接进来，让后续写代码这件事顺手一点。
先说清楚这套环境适合谁。适合第一次在 Mac 上做安卓、之前只在 Windows 或 Linux 上折腾过的人；也适合环境装了一半、Gradle 一直同步失败想重新理一遍的人。不适合已经用命令行玩得很熟的老手，因为下面很多步骤是给图形界面操作准备的。
整个链路是这样的：JDK 提供 Java 运行时，Android Studio 是 IDE，SDK 是安卓平台的编译依赖，Gradle 负责构建，模拟器或真机负责运行。任何一环版本错位，报错都会以「看起来毫不相关」的方式出现。比如 JDK 版本太高，Gradle 会直接告诉你Unsupported class file major version；Gradle 下载源不通，就会卡在Downloading https://services.gradle.org/...不动。
我实测下来，最稳的组合是：JDK 17（LTS）、Android Studio 最新稳定版、Gradle 用国内镜像的 8.x 发行版。下面按顺序来，每一步都给可复制的命令和配置。
2. TaoToken 前置准备：把 AI 编码的 Key 统一管起来
环境搭好之后，你大概率会想用 AI 帮你写点安卓代码。这里我提前把 TaoToken 接进来，原因是它能把多个模型的调用统一到一个 Key 上，后面不管是在 Android Studio 里用插件，还是在终端里跑 Claude Code，都不用反复换配置。
TaoToken 是一个模型调用聚合服务，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。它的 API 入口是 https://taotoken.net/api ，注意这个地址不带任何查询参数，配置的时候直接填这个就行。
你需要先拿到一个 Key。打开控制台页面 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 页面创建一个新的 Key，复制出来保存好。这个 Key 就是后面所有接入的凭证。
如果你只是想先验证模型能不能通，可以用模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 直接发一条消息试试，不用写代码就能确认 Key 是否有效。
对于长期写代码、跑 Agent 的场景，Coding Plan 会更划算，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它的定位是给持续编码和自动化任务用的，不是按次调用那种。
这里要强调一个概念：TaoToken 提供的是统一的 Base URL 和 Key，你在不同工具里配置时，三件套永远是「Base URL + Key + Model ID」。Base URL 填https://taotoken.net/api，Key 填你刚创建的那串，Model ID 按你实际要用的模型填。后面在 Claude Code 和 Cline 里都会重复这个结构。
注意：Key 只创建一次就够，不要每个工具都去新建，统一用一个方便管理额度。
3. 可复制配置：JDK、Gradle 镜像与 Android Studio 全流程
这一节是核心，所有配置都能直接复制。先装 JDK。
macOS 上装 JDK 17 最省事的方式是用 Homebrew。打开终端：
brew install --cask temurin@17装完之后验证：
/usr/libexec/java_home -V这条命令会列出机器上所有 JDK。你应该能看到 17 那一行。然后把它设为默认：
export JAVA_HOME=$(/usr/libexec/java_home -v 17) echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 17)' >> ~/.zshrc echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc source ~/.zshrc验证一下：
java -version输出里出现17.0.x就对了。这里踩过的坑是：如果你之前装过 JDK 21 或更高，Android Studio 自带的 Gradle 可能不认，所以显式指定 17 最稳。
接下来装 Android Studio。去官网下载 macOS 版 dmg，拖进 Applications 就行。首次启动会走一个 Setup Wizard，选择 Standard 安装类型，它会自动帮你下 SDK 和必要的组件。这一步网络好的话十几分钟，网络差就挂个国内镜像，后面 Gradle 那节会讲。
装完打开 Android Studio，进 Settings，找到Appearance & Behavior > System Settings > Android SDK，确认 SDK Location 是一个真实存在的路径，通常是/Users/你的用户名/Library/Android/sdk。把 SDK Platforms 里 Android 14 或 13 勾上，SDK Tools 里确保Android SDK Build-Tools、Android SDK Platform-Tools、Android Emulator都装了。
然后是 Gradle 镜像，这是最容易卡住的地方。新建项目后，打开项目根目录下的gradle/wrapper/gradle-wrapper.properties，把 distributionUrl 改成国内镜像：
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip注意反斜杠转义不能少，这是 properties 文件的语法要求。改完之后 Gradle 下载会快很多。
如果你还想让依赖下载也走镜像，在项目根目录的settings.gradle（新版是settings.gradle.kts）里加仓库镜像。Groovy 版本长这样：
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url 'https://maven.aliyun.com/repository/google' } maven { url 'https://maven.aliyun.com/repository/public' } google() mavenCentral() } }Kotlin DSL 版本：
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven("https://maven.aliyun.com/repository/google") maven("https://maven.aliyun.com/repository/public") google() mavenCentral() } }改完点 Sync Now，正常情况下进度条会顺畅走完。
最后把 AI 编码接进来。如果你用 Claude Code，配置在~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }如果你用 Cline 这类 VS Code 插件，在设置里选 OpenAI Compatible，Base URL 填https://taotoken.net/api，API Key 填你的 Key，Model ID 填你要用的模型。三件套结构完全一致。
4. 验证请求：跑通第一个安卓项目并确认 AI 接入生效
配置改完，先验证安卓这边能跑。在 Android Studio 里新建项目，模板选Empty Views Activity，语言选 Kotlin，Minimum SDK 选 API 24。点 Finish 之后等 Gradle 同步。
同步成功的标志是底部 Build 窗口出现BUILD SUCCESSFUL。如果卡住，看它卡在哪一行，通常是下载依赖或 Gradle 发行版。
同步完成后，点顶部工具栏的绿色三角运行。第一次会让你选设备，可以创建一个模拟器：Device Manager > Create Device，选 Pixel 7，系统镜像选 API 34，下载完启动。模拟器起来后，App 会自动安装并打开，看到默认的 "Hello Android" 界面就说明整条链路通了。
打包 APK 也顺手验证一下。菜单Build > Build Bundle(s) / APK(s) > Build APK(s)，首次会让你创建 keystore，填个密码和别名就行。构建完成后，APK 在app/build/outputs/apk/debug/目录下，路径类似：
/Users/你的用户名/AndroidStudioProjects/你的项目名/app/build/outputs/apk/debug/app-debug.apk把这个文件传到真机上安装，能打开就彻底没问题了。
再验证 AI 接入。在终端里跑 Claude Code，随便问一句「帮我写一个安卓里点击按钮弹 Toast 的代码」。如果返回正常，说明 Base URL 和 Key 都对。如果报 401，就是 Key 错了；如果报连接失败，检查 Base URL 是不是写成了带路径的形式，正确写法就是https://taotoken.net/api。
你也可以在模型对话页面直接发消息做交叉验证，确认是 Key 的问题还是工具配置的问题。
5. 本篇常见错排查：401、Gradle 同步失败与 OAuth 报错
这一节把真实会遇到的报错列出来，对照着改。
401 Unauthorized。这个最常见，出现在 AI 工具调用时。原因有三种：Key 复制时带了空格、Key 已经失效、Base URL 写错。先检查 Base URL 是不是https://taotoken.net/api，注意结尾没有斜杠，也没有/v1之类的后缀。然后重新去控制台复制一次 Key，粘贴时确认首尾没有空白字符。如果还不行，去 API Keys 页面看这个 Key 的状态是不是被禁用了。
local proxy failed / connection refused。这个通常出现在你本地开了某个代理工具，但工具本身没启动或者端口不对。解决办法是关掉工具里的代理设置，或者确认代理端口和实际监听端口一致。安卓开发本身不需要代理，Gradle 镜像已经解决了下载问题。
Error reading choices / unexpected response format。这个报错说明请求发出去了，但返回的内容不是预期的 JSON 结构。常见原因是 Model ID 填错了，比如填了一个不存在的模型名。去模型对话页面确认你要用的模型 ID 拼写，然后原样填到配置里。
Gradle sync failed: Unsupported class file major version。这是 JDK 版本和 Gradle 不匹配。Gradle 8.5 支持 JDK 17 到 21，如果你用的是 JDK 22 或更高就会报这个。回到第 3 节，把 JAVA_HOME 显式指到 17。
Could not resolve com.android.tools.build:gradle。依赖下载失败，检查 settings.gradle 里的镜像仓库有没有加对，阿里云镜像的 google 和 public 两个都要加。
OAuth 相关报错。如果你在 Claude Code 里看到 OAuth 字样，说明它还在走默认的登录流程，没有读到你配置的 API Key。检查~/.claude/settings.json的 JSON 格式是否正确，特别是引号和逗号。可以用cat ~/.claude/settings.json | python3 -m json.tool验证格式。
模拟器启动黑屏。macOS 上如果是 Apple Silicon 芯片，确保下载的是 arm64 的系统镜像，x86 镜像跑不起来。在 Device Manager 里删掉重新创建一个 arm64-v8a 的。
APK 安装到真机失败。检查真机有没有开启「允许安装未知来源应用」，以及 APK 的 minSdkVersion 是否高于真机系统版本。
6. 后续怎么用：把 AI 编码接进日常安卓开发
环境跑通只是起点。真正提升效率的是把 AI 接进日常流程。我的做法是：在 Android Studio 里装 Cline 插件，配置好 TaoToken 的三件套，写业务代码时直接让它生成样板；遇到 Gradle 报错，把错误日志贴给它，让它给排查方向；写单元测试时让它根据现有类生成测试骨架。
如果你更习惯终端，Claude Code 配合 TaoToken 的配置已经在上文给过了，直接复用。需要看更细的接入文档，去 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。Key 的管理统一在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，建议只保留一个活跃 Key，避免混乱。
一个实用技巧：把JAVA_HOME和 Gradle 镜像配置写进~/.zshrc和项目模板里，下次新建项目就不用重复改。Android Studio 支持自定义项目模板，把镜像仓库预置进去，能省掉每次新建项目后的手动同步。
最后提醒一句，Gradle 版本和 Android Gradle Plugin 版本是绑定的，升级其中一个之前先查兼容表，不然同步失败会浪费很多时间。环境这东西，一次配稳，后面就只剩写代码了。
