如果你在多人共用的 Linux 服务器上待过,应该能体会到“装一个全局软件”的压力:要 sudo 权限、要把路径写进系统级 PATH、要在 /usr/lib 和 /etc 里留一堆文件,离开的时候还得挨个清理。我最近越来越依赖 Claude Code 这种命令行 AI 编程助手,但偏偏多数工作环境不是我自己的笔记本:有时是客户现场的跳板机,有时是 CI 的临时容器,有时是共享开发机。在这些机器上,“免安装”就不再是偷懒,而是刚需。这篇文章就整理一下,在 Linux 上怎样不让 Claude Code 污染系统、不碰 root,用临时目录或用户目录把它跑起来,同时保留完整的配置、历史记录和模型切换能力。适合在受限环境里搞开发、又想把 Claude Code 用起来的朋友。
1. 为什么“免安装”在我的场景里是刚需,不是洁癖
1.1 全局安装的代价有多大
多数介绍 Claude Code 的文章会让你执行 npm install -g 或官方安装脚本。这两条路都会把文件写进系统目录(/usr/local 或 /opt 之类),还要修改 PATH。这在个人笔记本上没问题,在共享机器上就很尴尬:
- 没有 sudo 权限,连安装这一步都过不去
- 项目组其他人未必希望你改全局 Node 环境,因为全局依赖升级可能影响他们自己的工具链
- 团队的安全策略可能禁止在系统目录执行安装脚本,但允许在用户家目录放便携工具
npm 全局安装还会碰到一种很隐晦的问题:它把 CLI 的可执行文件放在 Node 的全局 bin 目录。如果你机器的 Node 是发行版自带的旧版本,Claude Code 可能要求更高版本,你又不能随便升级系统的 Node。这些坑加在一起,足够让“免安装”成为首选。
1.2 容器和 CI 环境逼着你这样做
CI 流水线里的容器一般用完即焚,你不可能把工具“装好”留着,只能在构建脚本里现拉现用。共享开发机则反过来:机器要塞满足够多的环境,但任何人都不愿意自己装的东西成为别人的负担。这时候,一切工具都应该符合一个原则:所有文件落在自己目录下,删除目录就等于卸载。
我在客户现场的跳板机上也吃过亏:机器是 CentOS 7,root 是不用想了,连 yum 的源都被限定。这种情况下,标准教程里的“curl 安装脚本”都不一定适用,反而是下载一个静态二进制或通过 node 的 npx 调用更可靠。
1.3 “免安装”到底免的是什么
我得先给这个词划个边界:免安装不是说没有任何文件落地,而是说不需要经过系统的安装流程,不需要 root,不写系统目录,不注册系统服务。所有东西可以放在一个自定义目录里,迁移时复制整个目录就走,删掉整个目录就什么都没了。
我实际在用的布局是这样:
text复制~/tools/
node/ # 当前用户使用的便携 Node
claude-code/ # Claude Code 的二进制或解压根目录
.claude/ # 配置、登录态、历史会话
所有环境变量只在当前用户的 shell 配置里生效,换台机器重新拉一下目录就好。后续所有操作都围绕这套布局展开。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 不碰系统的三种跑法:npx、官方二进制、容器
2.1 npx 是最快的“零安装”方案
如果你机器上已经有 Node(版本满足要求),npx 是零成本启动方式。npx 是 npm 自带的命令,它会在需要时从 registry 拉取包并缓存,执行完不会在项目里留下 node_modules。
bash复制npx @anthropic-ai/claude-code --version
npx @anthropic-ai/claude-code
这种方式叫“即用即走”,适合偶尔用一下。第一次执行会把整个包下载到 npm 缓存目录,之后再次使用会快很多。如果你希望每次执行都是同一个固定版本,可以给 npx 指定版本号:
bash复制npx @anthropic-ai/claude-code@1.0.0 --version
不过 npx 有两个烦人点:一是某些 npm 版本会交互式询问是否安装,在脚本里要加 --yes 跳过;二是每次都要经过 npm 解析,冷启动比直接从本地二进制启动慢。所以我只把它当成“临时应急”方案,日常更推荐第二种。
2.2 下载官方二进制包,放到自己的工具目录
Claude Code 安装脚本最终做的事,其实是去官方分发地址下载对应平台的压缩包,解压出一个 claude 可执行文件,再复制到 PATH 里的某个目录。明白这个逻辑之后,完全可以在不执行安装脚本的情况下,手动走一遍同样的流程。
大致步骤是:
- 在官方说明里找到当前版本的下载地址,确认你的 Linux 架构(x86_64 还是 aarch64)。
- 用 curl 把 tar.gz 下载到
~/tools/。 - 解压并把可执行文件放在
~/tools/claude-code/。 - 在自己 shell 的 PATH 中加入这个目录。
bash复制mkdir -p ~/tools/claude-code
curl -fsSL <下载地址> -o claude-code.tar.gz
tar -xzf claude-code.tar.gz -C ~/tools/claude-code
export PATH="$HOME/tools/claude-code:$PATH"
claude --version
这样得到的 claude 是个自包含执行文件,不需要系统包管理器参与。放进用户目录,不改任何系统配置,换机器时压缩这个目录就是一个便携包。
2.3 在容器里把“免安装”变成镜像层
容器场景其实比物理机更简单,因为镜像本身就是分发单位。你可以拉取一个基于 Node 的官方镜像或轻量基础镜像,把 Claude Code 的可执行文件打进镜像,或者干脆在容器里用 npx。
我常用的两个姿势:
- 开发容器:启动容器后挂载一个包含配置的目录(比如
~/.claude),然后把 claude 的二进制放到镜像的 /usr/local/bin,这样容器内直接claude。 - CI 一次性容器:在命令行里直接调用
npx @anthropic-ai/claude-code,配合--yes参数,用完容器即销毁,连缓存都不用特意清理。
bash复制docker run --rm -it \
-v ~/.claude:/root/.claude \
-e CLAUDE_CONFIG_DIR=/root/.claude \
node:20-slim \
npx --yes @anthropic-ai/claude-code
注意配置目录的挂载很关键。如果你不挂载,容器每次启动都是全新的登录态,会话历史也没有。挂载之后,本地和容器可以共享同一套 Claude Code 配置。
2.4 便携 Node:当系统里根本没有 Node
免安装的另一层意思,是连 Node 运行时也不依赖系统。很多最小化服务器、嵌入式环境、老 CentOS 上根本没有 node,或者版本太老。这种情况下我会放一个便携 Node:去 nodejs.org 下载 Linux 二进制包,解压到 ~/tools/node,然后把它加进 PATH。
bash复制curl -fsSL <nodejs二进制下载地址> -o node.tar.xz
tar -xJf node.tar.xz -C ~/tools/node --strip-components=1
export PATH="$HOME/tools/node/bin:$PATH"
export npm_config_prefix="$HOME/tools/node"
node -v
之后用这个 node 去跑 Claude Code 的 npm 包,整个链路都跟系统环境无关。其实 Claude Code 的安装脚本也会自动检测环境,但它需要执行 curl 管道到 bash,某些安全策略禁止这种执行方式;手动解压就没有这个问题。
3. 免安装不等于没配置:认证和配置目录怎么管
3.1 理解 CLAUDE_CONFIG_DIR 的作用
Claude Code 默认会把配置写到 ~/.claude。在免安装场景下,我强烈建议通过环境变量指定一个明确、可迁移的目录:
bash复制export CLAUDE_CONFIG_DIR="$HOME/tools/.claude"
这样,整个工具的“家”只有一处。登录凭据、历史命令、钩子设置都跟着这个目录走。复制这个目录到新机器,就等于把登录态和环境配置一并搬走。
不要小看这件事。多个项目、多台机器如果共享同一个默认配置目录,很容易出现“登录态串台”的问题。给每台机器或每个项目单独指定配置目录,是个值得养成的习惯。
3.2 登录认证在免安装模式下怎么做
Claude Code 第一次启动会要求登录。在无桌面环境的 Linux 跳板机上,通常的流程是:终端里显示一个授权链接,你去本地浏览器完成授权,再把授权码粘回终端。这类令牌相关操作,我会先确认信息该写到哪里,避免在 shell 历史里留下明文。
如果有多个账号或团队账号,不要只依赖交互式登录。我习惯把主账号的登录信息放在一个目录,团队账号放在另一个目录,切换时只改环境变量:
bash复制export CLAUDE_CONFIG_DIR="$HOME/tools/.claude-work"
claude
之后再用另一个终端跑个人目录,两边配置互不影响。这个小技巧在多项目同时接入的时候特别实用。
3.3 让可执行文件、配置、数据三层分离
我觉得一个清晰的免安装工具,最好做到三件事分离:
- 程序本体:只读,升级时整体替换
- 配置和凭据:用户专属,不随程序走
- 会话数据:按项目分,或单独放缓存目录
比如可以这样:
text复制~/tools/claude-code/bin/claude # 程序
~/tools/.claude/settings.json # 配置
~/tools/.claude/projects/ # 历史会话
~/tools/.claude/history.jsonl # 命令历史
程序升级时只替换第一层,配置和会话完全不动。如果某天不想用了,删除 ~/tools/claude-code 和 ~/tools/.claude 就彻底卸载,不会在系统里留下残余文件。
4. 免安装工作流里怎么接本地模型和第三方模型
4.1 为什么要接本地模型
有段时间我在调试工具调用兼容性,手头又有几块显卡,就在本地起了 LM Studio,顺便验证 Claude Code 能否复用已有模型。后来我发现,只要配置了符合 Anthropic API 格式的端点,Claude Code 可以把模型请求转发到其它兼容服务上,包括本地跑的 LM Studio、Ollama 这类工具,以及 DeepSeek、Qwen、GLM 等提供 Anthropic 兼容接口的云端模型。
这个能力很实用:团队里已有模型网关时,不需要单独申请新账号;本地有显卡时,可以直接压低推理延迟;做模型对比评测时,切换模型只改环境变量,不重新安装工具。
4.2 环境变量级别的模型路由
Claude Code 读取的标准环境变量包括:
ANTHROPIC_BASE_URL:接口地址ANTHROPIC_AUTH_TOKEN:认证令牌ANTHROPIC_MODEL:默认模型名ANTHROPIC_SMALL_FAST_MODEL:后台快速模型名
把这几项写进某个项目的 .env,再在免安装的环境里 source 一下,就能切换模型供应商。配合前面说的独立配置目录,模型切换和安全隔离可以同时完成。
bash复制export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"
export ANTHROPIC_MODEL="deepseek-chat"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek-chat"
npx --yes @anthropic-ai/claude-code
对本地 LM Studio 来说,接口地址一般是 http://localhost:1234,只要本地服务启动,Claude Code 就能复用本地显存里的模型,响应延迟低不少。这类配置适合放在用户级 shell 文件里,因为它跟具体项目无关。
4.3 用 cc-switch 在多个模型配置之间来回切
我早期是手改环境变量,烦了以后开始用 cc-switch 这类小工具。它本质是个配置管理工具,把不同模型的 API 地址、令牌、模型名组合成一条条“配置”,你选哪条,它就帮你把相应的环境变量设置好,或者更新 Claude Code 的配置文件。
实际用下来,cc-switch 最舒服的一点是,它不需要把模型路由写死在系统里。切换 DeepSeek、Qwen、GLM 这些模型时,只改配置文件,不碰 Claude Code 本体。也就是说,即使你的 Claude Code 是 npx 临时跑起来的,模型路由依然可以稳定复现。
要注意,不管用哪种模型路由,都要先确认目标模型对 Anthropic API 格式的兼容程度,尤其是工具调用。有些模型在普通聊天场景下回复正常,一旦让 Claude Code 执行多步骤工具调用,就会因为格式不匹配而卡住。
4.4 给本地模型接 Claude Code 时建议盯几个指标
- 上下文窗口:Claude Code 会把大量系统提示词塞进去,模型窗口不够大时,交互质量明显下降
- 工具调用支持:最好先跑一两条涉及文件读写、命令执行的测试
- 并发能力:本地模型同时处理多个工具请求时,显存占用会明显上涨
- 输出速度:本地小模型和云端大模型的速度差距很大,影响实际体验
我在开发机上用 LM Studio 跑模型时,得到的经验是:先把官方 Claude 模型跑通全套功能,再切到本地模型,比较同一个任务在两边的表现。这样能很快定位是模型能力问题还是接口兼容问题。
5. 免安装最容易踩的坑:PATH、版本、残留配置
5.1 PATH 没写对导致“command not found”
免安装最大的痛点是可执行文件不在系统 PATH 里。你以为 claude 已经可用了,换个 shell 或新开终端,命令就找不到了。
正确做法是把路径写进用户的 ~/.bashrc 或 ~/.zshrc,不是当前终端临时 export。临时 export 只对当前会话有效,新开的窗口不继承。另外要注意,不要在系统级 /etc/profile 里写,那又变成了需要 root 的操作,违背免安装的初衷。
我还习惯在 shell 配置开头做一个存在性判断:
bash复制if [ -d "$HOME/tools/claude-code" ]; then
export PATH="$HOME/tools/claude-code:$PATH"
fi
这样目录不存在时不报错,干净。
5.2 Node 版本不对时的连环报错
用 npx 方式跑时,Node 版本低于要求会直接报引擎错误。有些发行版的系统 node 是多年没升级的老版本,你又不想动系统,怎么办?
两个办法:
- 用 nvm 装一个用户级 Node,切换后跑 claude
- 使用便携 Node,按前面 2.4 的方法解压到用户目录
我个人推荐便携 Node,因为 nvm 虽然好用,但会在启动时加载 shell 函数,感觉偏重。便携 Node 就是一个目录,放进 PATH 就行。
5.3 多个实例共用配置目录导致的混乱
免安装的副作用是,你可能会同时用 npx、二进制、容器三种方式跑 Claude Code。三种方式默认都读写同一个 ~/.claude,于是出现很诡异的“跨环境同步”现象。
比如你在容器里改了设置,回到宿主机的 claude 里,发现 hooks 变了;或者在项目 A 里登录了账号 A,到项目 B 启动时发现还是账号 A。
解决办法就是给每种运行方式指定不同的配置目录:
bash复制CLAUDE_CONFIG_DIR="$HOME/tools/.claude-npx" npx --yes @anthropic-ai/claude-code
CLAUDE_CONFIG_DIR="$HOME/tools/.claude-bin" ~/tools/claude-code/claude
如果希望保持同一个身份,那就反过来,所有方式都显式指向同一个目录,不要依赖默认行为。显式总比隐式好。
5.4 下载缓存和临时文件怎么清理
npx 会把包缓存在 npm 缓存目录,虽然这不污染系统,但日积月累也会占空间。免安装的另一个好处是,清理起来目标明确:
- 删除
~/tools/claude-code - 删除自定义的配置目录
- 清理 npm 缓存里对应的包,或用
npm cache clean一次性清掉
容器场景更简单,容器销毁后所有东西自动消失,不需要额外清理。
5.5 在阉割版 Linux 环境里的缺失依赖
老服务器上偶尔会遇到缺动态库、缺 shell 组件的情况。Claude Code 的二进制版本对 glibc 有要求,如果机器太老,解压后直接运行会提示找不到某个 .so 文件。遇到这种情况,先确认系统的 glibc 版本,再看官方说明里对 glibc 的要求。多数老机上,换新内核的发行版或换用容器会更省事。
如果实在不能换环境,就选择在别处把命令生成好,把结果文件拷回老机器使用,这也是“免安装”思路的延伸。
6. 我沉淀下来的“免安装”最佳实践
6.1 目录即项目:一套标准布局
我现在所有机器上的布局保持完全一致,迁移成本几乎为零:
text复制~/tools/
claude-code/
node/
.claude/
换机器时,把这些目录打包传过去,改一下 PATH,然后把凭据目录的权限收紧:
bash复制chmod 700 ~/tools/.claude
6.2 用 alias 记住最常用的切换命令
因为我在不同项目里要用不同模型,alias 帮我省了很多事:
bash复制alias cc='claude'
alias ccd='cd ~/tools && npx --yes @anthropic-ai/claude-code'
alias cc-local='ANTHROPIC_BASE_URL=http://localhost:1234 npx --yes @anthropic-ai/claude-code'
6.3 把免安装当成一种纪律
免安装最大的价值不是“省掉安装步骤”,而是可预期、可清理、可迁移。一旦你习惯了这种纪律,就不会再愿意用那些在你机器上留下大量残余文件的方式。
对于新手,我建议先走 npx 路线,跑通再说。确认自己确实需要每天都用,再切换到二进制目录或容器方案。对于老手,可以考虑在公司内部搭建一个私有的分发点,把 Claude Code 的包和便携 Node 都放进去,团队成员拉取时速度更快、版本更统一。
我最后再说一个小技巧:如果你经常在多个 Linux 机器之间走动,不妨把 ~/tools 整个目录放进自己的备份同步清单里,而不要只同步 ~/.claude。这样不管走到哪台机器,只要拉下来,claude 二进制、便携 node、配置、历史会话都在,真正做到了“目录在手,环境我有”。
