Termux上运行Claude Code：手机变AI编程工作站完整指南

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.js：Claude 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

逐个解释一下我在干什么：

• nodejs：Claude 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_PROXY="http://127.0.0.1:端口" export HTTPS_PROXY="http://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 user@your-server -p 22

Claude 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 的这些日子里，踩过不少坑，把高频问题和解决方案整理成表：

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 的 AndroidManifest：

aapt 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 Code

Claude 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 2>&1

claude -p是非交互模式，可以直接在脚本里调用，这是手机端自动化的核心入口。

8. 写在最后：几个真心话

这套方案跑通之后，我最大的感受不是“手机能编程了”，而是“编程助手这类工具，本质上终于从电脑桌面上解放出来了”。Claude Code 在电脑上解决的是“减少重复打码”，在手机上解决的是“把随时随地处理任务变成可能”。

最后补一个实测小技巧：如果你的手机内存偏小（比如 8G 以下），在运行 Claude Code 之前先把后台 App 清一遍，尤其是浏览器和短视频应用，它们吃内存比 Claude Code 还凶。实测在 8G 内存的机器上，只要保持 Termux 在前台，配合 wake-lock 防休眠，跑一晚上会话都没问题。

还有一点，每次升级 Claude Code 之后，建议重新跑一次claude --version确认版本正常。npm 全局安装偶尔会因为网络抖动留下半成品，出现奇怪行为时先重装一次，比查半天资料快得多。

这个项目后续我觉得可以继续折腾的方向是：把 Termux 里的 Claude Code 接到本地 SQLite 数据库，做一个移动端的个人知识库管理工具。手机上跑 AI 编程助手这件事，远不止“能跑”这么简单，它更像是一个随身携带的开发环境，用熟了之后，你很难再回去。