1. 项目概述为什么要在手机上跑 Claude Code先说结论Claude Code 在 Termux 里跑起来完全可行而且是目前移动端体验最接近桌面端的 AI 编程方案。这个项目本质上是把 Anthropic 官方的命令行编程助手移植到 Android 环境通过 Termux 模拟 Linux 运行时让手机变成一台能写代码、改代码、执行代码的便携工作站。我知道很多人第一反应是“手机写代码纯属折腾”但这个判断要分场景。我个人的使用体验是当你通勤、出差、躺床上突然想到一个 bug 的修法或者需要快速验证一段逻辑时掏出手机打开 Termux用自然语言描述需求Claude Code 直接在本地生成并执行代码——这个过程比打开电脑快得多。它不是要替代笔记本而是填补“人在外面但脑子还在工作”这个空白。这套方案适合三类人有 Android 手机且愿意折腾的开发者拿它当随身调试工具想尝鲜 AI 编程助手但手头没有 Linux 开发机的人需要快速验证代码片段、做小工具脚本、管理 Git 仓库的运维或测试人员正文里我会从环境准备、安装配置、实际使用到问题排查完整过一遍。整个过程不要求你掌握 Android 源码开发或编译内核之类的高级技能只需要有基础的 Linux 命令经验——如果你会用 cd、vim 和 npm那现在就足够了。2. 整体设计与方案选型2.1 为什么选 Termux 而不是其他方案想把 Claude Code 跑在手机上表面上有几个选择用云 IDE 中转、用网页版、用 Termux 本地跑。前两个方案不是不行但它们依赖网络链路交互延迟不可控而且写代码这种高频操作一旦断连就很抓狂。Termux 的价值在于它是一个真正的本地 Linux 环境包管理器、文件系统、终端能力都是完整的Claude Code 这种 Node.js CLI 工具可以直接在里面跑不需要中间商。选 Termux 还有一层考虑它对 Android 的适配做得比较细。Termux 默认只给了 data 目录下的私有空间不需要 root存储权限通过系统级弹窗授权安全性比一堆“手机 Linux 模拟器”靠谱。同类的 Termux 替代品比如 UserLAnd 我也试过但它们的性能损耗明显更大而且包源维护不如 Termux 活跃。从工程角度类比Termux 和 Android 系统的关系就像 Docker 容器和宿主机进程隔离、权限受限、但功能完整。你不需要刷系统、不需要 root、不会把手机变砖装错了删掉重来就行。2.2 技术组合与依赖链整个项目跑起来依赖一条清晰的链路Android 系统 - Termux 终端 - pkg 包管理器 - Node.js 运行时 - npm 全局安装 - Claude Code CLI每一层的选型都有讲究Android 版本建议 Android 10 及以上。Termux 新版要求 Android 7但低版本在文件权限和网络稳定性上问题比较多实测 Android 10 以上最省心。Termux必须从 F-Droid 或 GitHub Release 安装不要用 Google Play 版本后者从 2023 年起不再维护很多包装不上。Node.jsClaude Code 依赖 Node.js用 Termux 的 pkg 安装即可不要手动编译一是慢二是容易缺依赖。npm 全局路径这是整个项目里最坑的一步后面我会专门讲权限问题。这套组合的优点是每个组件都可以独立升级。Claude Code 更新频繁Termux 的 pkg 源也保持了不错的同步速度不像某些 Linux 发行版那样打包滞后严重。2.3 为什么这个方案能解决真实需求我刚开始折腾时也很犹豫手机屏幕小、键盘不好用、性能也一般Claude Code 在手机上体验能好到哪去但实操之后发现Claude Code 和普通 IDE 的使用方式完全不同。它不需要你盯着屏幕打代码核心交互是“你说需求 - 它生成代码 - 你确认结果”这是一个语音/文本驱动的工作流而不是键鼠驱动的工作流。这意味着手机性能不是瓶颈屏幕尺寸也不是核心痛点——你的手指只需要在关键节点上做确认和修改就行。最典型的场景是突然想到一个正则表达式怎么写直接对 Claude 说“帮我写个匹配邮箱的正则支持 .cn 域名”深夜发现线上日志的格式不对需要写个 Python 脚本做字段提取手边没有电脑想给开源项目提 PR 但人在外面用 Claude Code 做代码审查和 commit message 生成这些场景里手机装个 Termux 的成本远低于“找个地方打开电脑”。3. 环境准备与基础配置3.1 安装 Termux两个关键决策Termux 的安装是第一个可能劝退新手的地方因为网上一搜全是乱七八糟的教程有些还引导你装什么“美化版”“修改版”这里我强烈建议只用官方原版。第一步去 F-Droid 下载 Termux APK。F-Droid 是 Termux 官方推荐的渠道签名和源码都是透明的版本更新也快。GitHub Release 也可以但 F-Droid 胜在后续升级方便。有一个细节值得注意从 Android 12 开始系统会对“外部来源应用”有更严的提醒安装时需要在设置里允许“安装未知应用”装完之后可以立刻关掉权限降低安全风险。装完之后打开 Termux第一步先跑这串命令termux-setup-storage这个命令会弹出存储权限申请允许后会在手机内部存储生成~/storage目录映射到shared公共存储区、downloads、dcim等系统目录。这一步必须先做不然后面定位文件会疯掉。3.2 换镜像源国内环境的关键加速Termux 默认的软件源是 GitHub 和国外的镜像国内的网络访问速度极其不稳定。如果你不想在 pkg install 时看进度条卡半小时换镜像源是必须的操作。Termux 官方提供了一个一键切换源的工具termux-change-repo执行后会出现一个选择界面勾选你想要的镜像源。国内推荐清华源或中科大源实测清华源的同步速度和稳定性都还不错。选择完成后它会自动更新源索引之后执行pkg update pkg upgrade -y把索引和基础软件包都刷到最新状态。这一步建议在装任何东西之前完成不然后面和依赖版本相关的 bug 会层出不穷。3.3 安装基础工具链Claude Code 虽然只是一个 Node 程序但它要在 Termux 里干活依赖一些基础工具。我实际用到的包包括pkg install -y nodejs git python openssh nano curl逐个解释一下我在干什么nodejsClaude Code 的运行时必须装的git项目版本管理Claude Code 的代码操作和 PR 流程都依赖它python虽然 Claude Code 本身不依赖 Python但很多代码生成任务会用到解释器来验证效果openssh远程连接服务器用这个后面讲如何配合手机使用nano轻量文本编辑器比 vim 对新手友好一点改配置够了装完之后顺手验证一下核心工具node -v npm -v git --version正常来说node -v 显示的版本号在 18 以上就完全够用。如果版本太低用 pkg 升级 nodejs 一次。4. Claude Code 安装、配置与核心参数详解4.1 三步完成安装Termux 里安装 Claude Code 和桌面端几乎一样核心就是 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后确认是否成功claude --version能输出版本号说明安装成功。接着启动claude第一次启动时Claude Code 会引导你进行身份认证。这步在 Termux 里跟桌面端有个区别手机上没法像桌面浏览器那样轻松完成 OAuth 跳转。我的做法是直接用 API Key 完成认证后面我会列出具体步骤。4.2 认证配置与模型访问Claude Code 支持多种认证方式Anthropic 账号 OAuth、Claude Pro/Max 订阅、API Key以及部分第三方兼容模型网关。在 Termux 环境里最稳定的是 API Key 方式。你需要先到 Anthropic 控制台生成一个 API Key——官方控制台生成时记得选好权限范围别把 key 泄露给任何人。生成 key 之后在 Termux 里设置环境变量export ANTHROPIC_API_KEY你的key为了让它每次启动都生效我习惯把它写进~/.bashrc或者~/.zshrc取决于你的 shell这样以后打开 Termux 就能直接用。这里有一个重要提醒不要在生产环境的共享终端里硬编码 API Key那是给提桶跑路的人准备的。本地个人开发机还好但如果你准备在云主机、公司电脑、公共服务器上跑请用环境变量管理器或密钥服务。如果你用的是 Anthropic 账号 OAuth 方式Termux 里可能会卡在浏览器回调环节。我的建议是先走 API Key纯命令行最省心。4.3 环境变量与代理配置如果你所在的网络环境访问 Anthropic API 需要走代理Termux 里同样支持标准环境变量export HTTP_PROXYhttp://127.0.0.1:端口 export HTTPS_PROXYhttp://127.0.0.1:端口Termux 里没有类似桌面端的网络设置面板所有网络偏好都要通过环境变量传给终端应用。这也是我极力推崇 Termux 的原因之一它保留了你用 shell 解决问题的完整能力而不是像某些“手机 IDE”一样把系统网络层锁死。注意network_proxy 变量的设置需要和你的代理地址、端口保持匹配否则会直接报 ECONNREFUSED 之类的连接错误。遇到这种问题别急着怀疑 Claude Code先 curl 一下 API 网关测试连通性。4.4 能力开关与 hooks 机制Claude Code 的很多行为可以通过配置调优。进入交互界面后常用的命令包括/help # 查看命令列表 /model # 切换模型 /config # 查看当前配置 /status # 检查会话状态在~/.claude/settings.json中你可以定义自定义指令、hooks 和权限规则。这个文件是 Claude Code 的“行为总纲”核心作用是指定它碰文件、跑命令时应该自动同意还是每次都问。我自己的配置习惯是{ permissions: { allow: [ Read, Edit, Bash(npm:*), Bash(git:*), Bash(cat:*) ], deny: [ Write(/storage/emulated/0) ] } }注意最后那条deny不要允许 Claude Code 顺手改你手机公共存储区的文件尤其是/storage/emulated/0/Android/data/下面那一堆目录。Android 11 对这些目录有额外的访问限制乱授权轻则报权限错误重则让某些应用文件错乱。4.5 CLAUDE.md给 AI 的“工作手册”Claude Code 会读取仓库根目录或用户主目录下的CLAUDE.md作为项目级说明。这个概念类似 ChatGPT 的 system prompt但它只对当前项目生效。我建议在~下放一个基础的CLAUDE.md定义全局偏好比如- 代码风格保持简洁优先使用标准库 - 生成文件时不要包含绝对路径统一用相对路径 - 修改文件前先展示 diff 概要确认后再写入然后在每个项目的根目录再放各自的CLAUDE.md写清项目背景、目录结构、和常见禁忌。这招对手机端特别有用因为手机输入长指令太累了把这些话固定在配置里每次启动 Claude Code 它都会自动遵循。5. 手机端实操从日常开发到远程管理5.1 在手机上建第一个 Python 项目假设你现在想在手机里写一个小工具比如一个批量重命名文件的 Python 脚本。纯手动敲代码太慢我一般直接让 Claude Code 全程编码claude 帮我写一个Python脚本遍历当前目录下所有 .txt 文件按文件名前缀排序后统一重命名为 report_001.txt、report_002.txt 这样的格式。要处理中文文件名文件名里如果有空格要保留原样。Claude Code 会自己写代码、创建文件、展示 diff然后问你要不要执行。你确认后它直接调用 Python 跑完脚本并把结果打印出来。这个过程你在手机上全程不用写一行代码只需要确认和微调。如果后续想改逻辑直接说“改成只处理文件名里带 2025 的”它会在上次会话上下文里继续改不需要重新解释需求——这就是会话式编程助手和普通代码生成工具的最大区别。5.2 用 Claude Code 维护 Git 仓库我经常在手机上维护一些小仓库比如个人笔记、脚本集、甚至写这篇稿子时的一些临时项目。Claude Code 的 git 集成做得很好操作流程基本是1. 在仓库目录里启动 claude 2. 告诉它你改了哪些东西、想要什么效果 3. 它自动 git diff 审查改动 - 生成 commit message - 提交 4. 需要推到远端时它会执行 git push 并告诉你结果实测下来它生成的 commit message 比我自己写的好很多而且能自动识别哪些文件改动了、变动涉及什么模块。对 PR 流程它还能写 summary 和测试计划可以直接粘贴到 GitHub。5.3 SSH 远程管理服务器Termux 里装了 openssh 以后配合 Claude Code 可以做到一个很舒服的工作流用 Cladue Code 生成脚本然后通过 ssh 直接在远程服务器上执行。ssh useryour-server -p 22Claude Code 可以在生成完命令后把它交给 Termux 的 shell 执行等于你的手机变成了一台轻量运维终端。我自己最常用的场景是人在外面服务器告警群里抛了个问题我让 Claude Code 帮忙生成排查命令然后 ssh 上去对照执行当场处理完。5.4 Android 文件系统权限最容易翻车的环节Termux 的存储权限有个很让人抓狂的点。termux-setup-storage创建的映射目录默认指向/storage/emulated/0/但 Android 系统对应用访问公共存储区有各种限制。常见的一个坑是你通过文件管理器把代码仓库放到了/storage/emulated/0/Documents/然后在 Termux 里想用cd进去发现路径不通或权限被拒绝。解决办法是我前面提到的尽量把工作目录放在 Termux 私有空间。Termux 的家目录位于~/即/data/data/com.termux/files/home这个目录对 App 是私有的不受公共存储权限限制读写都顺畅。如果需要和手机其他 App 交换文件走~/storage/downloads/这类映射目录或者反过来把文件放到~/storage/shared/。Android 的Android/data目录也有一个隐蔽的坑特别是高版本 Android 上很多应用的数据目录被加了no_other_apps_access标志即使授权了存储权限也未必能直接访问第三方应用的数据目录。遇到这类问题不用试了Claude Code 也绕不过系统层面。6. 常见问题与排查速查表我在手机端跑 Claude Code 的这些日子里踩过不少坑把高频问题和解决方案整理成表问题现象解决方案npm 全局安装权限错误EACCES / npm prefix 无写权限Termux 里不要乱用 sudo设置 npm 全局路径为~/.npm-global并写入 PATHClaude Code 启动白屏/无响应claude 命令敲下去后卡住先检查 Node 版本是否 18再检查 API Key 环境变量是否已加载连不上 Anthropic API超时、ECONNRESET配置HTTP_PROXY和HTTPS_PROXY或更换网络环境测试连通性存储目录无法写入Permission denied写/storage/emulated/0/...把项目目录建在 Termux 私有~/下不要直接操作公共存储区Termux 包安装卡住pkg install 进度条很久不动执行termux-change-repo换源再pkg updateClaude Code 升级失败auto-update failed: no write permission to npm prefix切换 npm 全局目录到用户家目录或用brew方式安装Termux 里还是建议直接改 npm prefixGit 中文文件名乱码中文名变成反斜杠序列在~/.gitconfig里加[core] quotepathfalse手机休眠断连执行长时间任务时 Termux 被杀掉在 Termux 里执行termux-wake-lock保持前台唤醒6.1 npm 全局权限问题的根治方法上面那张表里npm 权限问题出现的频率最高。Termux 的默认 npm 全局路径在系统目录下没有 root 权限根本写不进去。我在第一次安装时也遇到了 auto-update failed 的报错查了半天发现是 npm prefix 的问题。解决方案是把 npm 全局路径改到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后打开~/.bashrc或~/.zshrc加上export PATH~/.npm-global/bin:$PATH改完之后重新source一下source ~/.bashrc再执行claude --version如果正常输出说明 Claude Code 及其所有全局依赖已经能正确找到自己的目录了。以后升级 Claude Code 只需要npm install -g anthropic-ai/claude-code一条命令再也不会出现 write permission 的错误。6.2 代理配置导致连接失败的几个坑如果你在移动网络手机蜂窝数据下使用网络环境的变化可能会导致代理配置失效。Termux 里没有图形化的网络连接管理一切靠系统代理环境变量这就意味着你换了 Wi-Fi 或切换到蜂窝数据时当前 shell 里的代理配置并不会自动刷新。排查步骤建议按这条链路走env | grep -i proxy # 检查当前代理变量 curl -I https://api.anthropic.com # 测试 API 连通性如果 curl 能通但 Claude Code 不通多半是 Claude Code 没有继承环境变量这时候检查你是在哪个 shell 会话里启动的 claude确认环境变量是否 export 了。6.3 Android 14 存储访问的新变化Android 14 和更高版本对文件访问权限做了进一步收紧。如果你在手机上还有其他文件管理类的 App会发现它们访问/storage/emulated/0/Android/data/目录会受限。Termux 也一样即使通过termux-setup-storage授权了某些目录依然进不去。对策非常明确所有项目的代码文件统一放~/下。如果非要放到公共存储区就放在Download目录映射为~/storage/downloads这个是所有 App 都不太受限的位置。6.4 终端选择怎么让手机端体验更好默认的 Termux 全屏终端比较简陋但也有很好的附加方案。我建议安装 Termux:Tasker 插件 或 Termux:Widget用于做定时任务、一键启动常用场景非常方便。更推荐的是Termux 自带的键盘行顶部可以显示 ESC、Tab、Ctrl 等按键长按数字可以输入特殊符号。按音量键和数字键组合可以快速呼出这些键。SSH 客户端如果你有重度远程需求配合 Blink Shell 或 Termius体验能再上一个台阶。我用下来Termux 自带的键位已经能满足 Claude Code 的日常输入需求偶尔需要很复杂的命令时直接用手机输入法的手写/语音转文字效率其实也不低。7. 项目扩展这套方案还能玩出什么花样Claude Code 在 Termux 里搭好之后能力边界其实比很多人想象中宽得多。我快速列几个我试过的扩展方向7.1 结合 Android 原生开发Termux 里也能装aapt、apktool之类的工具做 APK 资源解析。虽然跑完整 Android 编译链还不太实际但如果你只是想快速查看 APK 的包名、权限、版本信息Claude Code 配合这些命令行工具完全能胜任。常见操作是让 Claude Code 帮你分析 APK 的 AndroidManifestaapt dump badging app.apk | head -50然后直接对着输出提问Claude Code 能解释这个 App 申请了哪些权限、目标 SDK 版本等信息。7.2 跑轻量 Web 服务Termux 里跑python -m http.server或 Node 的express完全没问题。当你做一个本地小工具时可以在手机上直接起一个服务然后把手机当成局域网内的一台开发机电脑浏览器直接访问调试页面。配合 Claude Code 修改服务端代码改完自动重启服务整个调试闭环在手机上就能完成。7.3 其他模型接入 Claude CodeClaude Code 本身设计是面向 Anthropic 模型的但通过环境变量和配置也可以接入第三方的模型网关或者兼容 Anthropic API 的本地模型。这个扩展方向对国内用户特别有意义因为它能让 Claude Code 变成一个通用的终端编程代理而不只是绑死官方 API。方式是在环境变量里指定自定义的ANTHROPIC_BASE_URL或CLAUDE_CODE_API_BASE指向你需要的兼容端点。前提是对方实现的是 Anthropic 兼容协议否则没法直接工作。但这里有个务实的建议如果你没有特定的模型需求直接用官方 API Key 是最省心的。第三方模型在工具调用和代码生成的稳定性上目前和官方还是有差距。7.4 定时任务和自动化Termux 支持 cron 任务通过crontab或 termux-job-scheduler。你可以让 Claude Code 每天定时检查某个仓库的依赖更新或者定时生成日报总结推送到你的手机通知。这些操作都不需要电脑全在手机上闭环。例如crontab -e # 每天凌晨2点执行 0 2 * * * cd ~/repo claude -p 检查所有依赖的版本如果有更新自动升级并提交 /dev/null 21claude -p是非交互模式可以直接在脚本里调用这是手机端自动化的核心入口。8. 写在最后几个真心话这套方案跑通之后我最大的感受不是“手机能编程了”而是“编程助手这类工具本质上终于从电脑桌面上解放出来了”。Claude Code 在电脑上解决的是“减少重复打码”在手机上解决的是“把随时随地处理任务变成可能”。最后补一个实测小技巧如果你的手机内存偏小比如 8G 以下在运行 Claude Code 之前先把后台 App 清一遍尤其是浏览器和短视频应用它们吃内存比 Claude Code 还凶。实测在 8G 内存的机器上只要保持 Termux 在前台配合 wake-lock 防休眠跑一晚上会话都没问题。还有一点每次升级 Claude Code 之后建议重新跑一次claude --version确认版本正常。npm 全局安装偶尔会因为网络抖动留下半成品出现奇怪行为时先重装一次比查半天资料快得多。这个项目后续我觉得可以继续折腾的方向是把 Termux 里的 Claude Code 接到本地 SQLite 数据库做一个移动端的个人知识库管理工具。手机上跑 AI 编程助手这件事远不止“能跑”这么简单它更像是一个随身携带的开发环境用熟了之后你很难再回去。