在手机上玩转 Claude Code：用 Termux 把安卓变成「掌上 IDE」（含国内模型配置）

1. 为什么要在安卓手机上跑 Claude CodeClaude Code 是 Anthropic 推出的终端 AI 编程助手它不是一个带图形界面的编辑器插件而是一个跑在命令行里的 Agent你输入自然语言需求它读你当前目录的代码、改文件、跑命令、解释报错。很多人第一次听说「手机上跑 Claude Code」会觉得别扭但实际用下来碎片时间的价值被放大了——地铁上改一个函数、排队时让 AI 读一段日志、睡前把白天没想通的报错丢进去这些场景掏出手机就能干比等回到电脑前再打开 IDE 快得多。安卓手机能跑 Claude Code 的关键在于 Termux。Termux 是一个不需要 root 的终端模拟器它自带包管理器能装 Node.js、Git、Python 这些开发工具本质上就是把一个精简的 Linux 环境塞进了安卓应用里。Claude Code 是 Node.js 写的只要 Termux 里 Node 环境正常它就能跑起来。所以整条路径是Termux 提供 Linux 终端 → 装 Node.js → 全局装 Claude Code → 配置模型 API → 在终端里对话和改代码。这篇教程面向的是没接触过 Termux 的新手也照顾已经用过终端但没在手机上配过 AI 编程工具的人。我会把每一步的命令、配置文件片段、验证方法都写清楚尤其是国内模型 API 的接入参数——因为 Claude Code 默认走 Anthropic 官方接口国内直连不稳定用兼容 Anthropic 协议的国内模型服务或中转服务是更实际的选择。你跟着做最后能在手机上看到 Claude Code 的交互界面输入一句「帮我写个快排」它能返回代码就算打通了。需要提前说明的是Termux 里的 Claude Code 体验和桌面端有差异屏幕小、输入慢、没有图形化的 diff 预览适合轻量任务和快速验证不适合长时间大型重构。把它当成「掌上应急 IDE」而不是主力开发环境心态就对了。2. Termux 环境初始化与 Claude Code 安装全流程2.1 安装 Termux 并更新包列表Termux 不要从应用商店装商店版本往往停更包源也旧。去 GitHub 的 termux/termux-app releases 页面下载最新 APK。大多数安卓手机是 arm64-v8a 架构选对应的包如果不确定装个 CPU-Z 看一眼架构再下。安装时如果提示「应用与设备不兼容」基本就是架构选错了换一个包重试。装好打开第一件事是更新包列表和已装包pkg update pkg upgrade中途会问你是否覆盖配置文件一路回车默认即可。这一步在旧版本 Termux 上可能要跑几分钟耐心等。2.2 装 Node.js 和 GitClaude Code 依赖 Node.jsGit 用于版本管理和后续拉取项目pkg install nodejs git装完验证node -v npm -v git --versionNode 版本建议 18 以上Claude Code 对低版本 Node 支持不好。如果node -v显示的是 16 或更低先pkg upgrade nodejs升一下。2.3 全局安装 Claude Code一条命令npm install -g anthropic-ai/claude-code安装过程中如果 npm 报权限或网络错误先换国内镜像源再装npm config set registry https://registry.npmmirror.com npm install -g anthropic-ai/claude-code装完可以切回官方源避免后续其他包兼容问题npm config set registry https://registry.npmjs.org验证安装claude --version能打印版本号就说明二进制已经就位。2.4 首次启动与登录方式选择直接输入claude首次启动会引导你选择认证方式一种是 Anthropic 账号登录OAuth一种是 API key。如果你打算用国内模型或中转服务必须选 API key 这条路因为账号登录走的是官方 OAuth国内网络下大概率卡住。选 API key 后它会让你输入 key但更推荐的做法是先退出用环境变量统一配置这样每次启动自动生效不用重复输入。按 CtrlC 退出当前引导进入下一步配置。3. 国内模型 API 配置Base URL、Key 与 Model ID 三件套Claude Code 读取的是 Anthropic 风格的环境变量核心是三个ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。国内模型服务只要兼容 Anthropic 的/v1/messages协议就能通过改 Base URL 接进来。TaoToken 提供的就是这类兼容接入官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。3.1 把配置写进 shell 配置文件Termux 默认 shell 是 bash配置文件是~/.bashrc。先装个顺手的编辑器pkg install nano nano ~/.bashrc在文件末尾追加以下内容把 Key 换成你自己的export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的实际Key export ANTHROPIC_MODELclaude-sonnet-4-20250514保存退出Ctrl 组合键在 Termux 里通过顶部工具栏的 Ctrl 键触发按 CtrlX提示保存时按 Y回车确认文件名。让配置立即生效source ~/.bashrc3.2 用 settings.json 做项目级配置除了环境变量Claude Code 还支持项目级配置文件.claude/settings.json适合给不同项目配不同模型。在项目根目录建这个文件{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的实际Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这个文件里的配置会覆盖全局环境变量适合你同时维护多个项目、每个项目用不同模型或不同额度 Key 的情况。注意别把带真实 Key 的 settings.json 提交到公开仓库加进.gitignore。3.3 三件套参数对照参数作用示例值ANTHROPIC_BASE_URL接口地址决定请求发往哪里https://taotoken.net/apiANTHROPIC_AUTH_TOKEN鉴权 Key相当于通行证sk-xxxxxxxxANTHROPIC_MODEL指定调用的模型 IDclaude-sonnet-4-20250514三个缺一不可。只配 Base URL 不配 Key 会 401只配 Key 不配 Base URL 会走官方默认地址导致超时Model ID 写错会报模型不存在。Model ID 要以你所用服务实际提供的为准不同服务商命名可能不同。注意环境变量里等号两边不要有空格Key 不要加引号否则会被当成字符串的一部分传进去导致鉴权失败。4. 验证请求确认代码补全与对话交互生效配置写完重启 Termux 或source ~/.bashrc然后进入一个测试目录mkdir -p ~/test-claude cd ~/test-claude claude启动后如果看到欢迎信息里显示的 API base URL 是你配置的地址说明环境变量读到了。接下来做两个验证。4.1 验证对话交互在 Claude Code 交互界面里直接输入帮我写一个 Python 函数判断一个数是不是素数正常情况它会返回一段带解释的代码。如果卡住不动或报连接错误说明 Base URL 或网络有问题往下看第 5 节的排查。4.2 验证文件读写与代码补全让它实际改一个文件才能确认 Agent 能力生效。先建个文件echo def add(a, b): calc.py echo return a b calc.py然后在 Claude Code 里输入读取 calc.py给它加一个 subtract 函数并补一个简单的测试它会读文件、改文件、可能还会跑一下测试。完成后你cat calc.py看内容是否被正确修改。这一步能跑通说明 Claude Code 的读文件、写文件、执行命令这条链路在 Termux 里是通的。4.3 验证结果对照现象含义返回代码且无报错配置成功可正常使用401 UnauthorizedKey 错误或未生效Connection refused / timeoutBase URL 不通或网络问题Model not foundModel ID 写错一直转圈无响应网络慢或服务端限流5. 常见报错排查401、local proxy failed 与 OAuth 问题5.1 401 鉴权失败最常见的报错。先确认环境变量真的生效了echo $ANTHROPIC_AUTH_TOKEN echo $ANTHROPIC_BASE_URL如果输出为空说明~/.bashrc没写对或没 source。检查有没有多余空格、有没有把 Key 写成了占位符没替换。如果输出正常但还是 401去服务商控制台确认 Key 是否有效、额度是否用完。TaoToken 的 Key 可以在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里查看和管理。5.2 local proxy failed这个报错通常出现在 Claude Code 尝试走本地代理但代理没起来的时候。如果你没配代理检查环境里有没有残留的HTTP_PROXY、HTTPS_PROXY变量env | grep -i proxy有的话在~/.bashrc里 unset 掉unset HTTP_PROXY unset HTTPS_PROXY然后 source 重试。Termux 环境下不需要额外代理层直连 Base URL 即可。5.3 reading choices 相关报错这类报错一般是响应体解析失败常见原因是 Base URL 指向的接口返回的不是 Anthropic 标准格式。确认你用的地址是兼容/v1/messages的而不是 OpenAI 风格的/v1/chat/completions。两者协议不同Claude Code 只认前者。TaoToken 的 API 入口 https://taotoken.net/api 是 Anthropic 兼容的直接填这个即可。5.4 OAuth 登录卡住如果你不小心选了账号登录会卡在浏览器跳转或回调。退出 Claude Code删掉配置目录重新来rm -rf ~/.claude claude重新选 API key 方式。或者干脆靠环境变量启动时它检测到ANTHROPIC_AUTH_TOKEN就不会再走 OAuth 引导。5.5 npm 安装慢或失败换镜像源前面提过。如果npm install -g报 EACCES 权限错误Termux 里一般不会遇到因为它是用户空间。真遇到就加--force或检查 node 版本。5.6 环境变量改了不生效确认写在~/.bashrc而不是~/.profile或~/.zshrcTermux 默认 bash。改完必须source ~/.bashrc或重开 Termux。如果用了 tmux 或 screen新开的会话可能读的是旧环境重连一下。6. 长期使用建议与接入入口手机端跑 Claude Code几个实际经验值得说。第一Termux 后台容易被安卓杀长时间任务建议开termux-wake-lock防止休眠断连。第二输入长 prompt 很痛苦可以先把需求写在备忘录里粘贴进去。第三屏幕小claude的输出会刷屏善用CtrlL清屏或者把结果重定向到文件再cat。如果你打算长期在手机上做编码和 Agent 任务Coding Plan 比按量计费更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。只是想先验证模型对话效果可以用模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速试。Key 的创建和管理在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一句API Key 是账号凭证别截图发群、别提交到公开仓库。Termux 的~/.bashrc里存着明文 Key手机借人前留意一下。配置一次之后每次打开 Termux 输入claude就能用碎片时间写代码这件事算是真正落地了。