Linux服务器 安装Claude Code教程
Linux服务器 安装Claude Code教程
1 | “ AI 不太可能取代你,但一个比你更会使用 AI 的人,可能会。 ” ————Jensen Huang(黄仁勋) |
Claude Code是由Anthropic公司开发的一款AI驱动型的编程Agent命令行工具。这类产品也已经成为当代程序员代码开发不可或缺的重要工具。本文将介绍如何在 Linux 服务器上部署、配置个人Claude Code,利用CC-Switch绕过Claude Code本身的订阅需求,并且无需sudo 权限。
本文主要分成两部分:
- 先安装并验证
Claude Code - 如果首次启动时遇到登录受限、地区限制,或者你本来就准备使用自定义 API provider,则继续安装并配置
cc-switch CLI
如果你只是想在服务器上快速把 Claude Code 跑起来,可以先看前半部分;如果你后续还需要切换 provider、配置 apikey、base_url、model,则重点看后半部分。
1 安装前准备
在正式安装之前,可以先确认当前 Ubuntu 环境里至少有 bash 和 curl。
1 | bash --version |
如果这两个命令都能正常输出版本号,通常就可以继续后面的安装流程。
2 安装 Claude Code
官方推荐的 Linux 安装方式如下:
1 | curl -fsSL https://claude.ai/install.sh | bash |
这条命令会下载官方安装脚本,并直接在当前用户环境中完成安装。对于没有 sudo 权限的服务器用户来说,这种方式最方便,因为它本身就是面向用户级安装的。
2.1 安装后是否需要手动配置环境变量
大多数情况下,不需要你手动写 export PATH=...,因为安装脚本通常会处理好命令的落盘和 shell 集成。
但是在服务器环境下,尤其是你当前 shell 没有刷新、或者用户环境比较精简的时候,仍然可能出现以下情况:
- 安装已经完成
- 但当前终端里执行
claude仍然提示command not found
这时建议按下面的顺序排查。
先验证 claude 是否已经被安装到用户目录:
1 | ls ~/.local/bin/claude |
再检查当前 PATH 里是否包含 ~/.local/bin:
1 | echo $PATH |
如果 ~/.local/bin 不在 PATH 里,可以先临时加入:
1 | export PATH="$HOME/.local/bin:$PATH" |
然后再次执行:
1 | claude --version |
如果这样可以正常识别 claude,说明问题只是当前 shell 环境变量没有生效。为了避免下次重新登录后还要重复设置,可以把它写入 ~/.bashrc:
1 | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc |
因此,关于“是否要手动 export 环境变量”这个问题,可以简单总结为:
- 正常情况下不用手动配置
- 如果安装后仍然找不到
claude,再手动把~/.local/bin加入PATH
3 验证 Claude Code 是否安装成功
安装完成后,最直接的验证方法就是查看版本号:
1 | claude --version |
如果能正常输出版本号,说明命令已经安装成功。
进一步还可以执行:
1 | claude doctor |
claude doctor 会帮助检查当前环境中的常见问题,比单纯看版本号更全面一些。
如果你只是想快速确认安装无误,那么至少确保上面这条 claude --version 命令能够正常执行。
4 首次启动 Claude Code
安装完成后,可以直接启动:
1 | claude |
按照官方流程,首次启动后通常会要求你登录账号,并在浏览器中完成认证。
这里需要注意两点:
Claude Code不是免费 Claude.ai 账号默认就能使用的功能,通常需要可用的 Pro、Max、Team、Enterprise 或 Console 账户- 某些服务器环境下,可能会遇到登录流程不方便、浏览器认证不顺畅,或者当前网络/地区不支持直接使用的情况
如果你这里可以顺利登录,那么后续直接使用官方账号方式即可;如果你在这一步遇到问题,就可以继续配置 cc-switch CLI,改为使用你自己可用的 API provider。
5 什么是 cc-switch CLI
cc-switch CLI 可以理解为一个专门用来管理 AI 编码工具配置的命令行工具。它可以帮助你统一管理不同 provider 的配置,并支持为 Claude Code 切换不同的 API 设置。
如果你在 Claude Code 首次登录这一步卡住了,或者你本来就准备使用自定义 API key / base URL / model,那么 cc-switch CLI 会非常方便。
cc-switch CLI 官方仓库地址如下:
https://github.com/saladday/cc-switch-cli
它的 README 里给出了多种安装方式。对于没有 sudo 权限的 Ubuntu 服务器用户,推荐优先考虑下面两种思路:
- 直接使用官方安装脚本
- 手动下载二进制到自己的用户目录
6 安装 cc-switch CLI
6.1 方法一:使用官方安装脚本
最简单的安装方式是:
1 | curl -fsSL https://github.com/saladday/cc-switch-cli/releases/latest/download/install.sh | bash |
这个方式默认会把程序安装到用户目录下,通常对没有 sudo 权限的环境更友好。
不过要注意,cc-switch CLI 的发布包在 Linux 下同时涉及不同的 libc 环境。如果你在 Ubuntu 上用默认方式安装失败,可以尝试显式使用 glibc 版本:
1 | curl -fsSL https://github.com/saladday/cc-switch-cli/releases/latest/download/install.sh | CC_SWITCH_LINUX_LIBC=glibc bash |
安装后同样建议先验证命令是否可用:
1 | cc-switch --version |
如果终端提示找不到 cc-switch,优先检查 ~/.local/bin 是否已经加入到 PATH。这一点和前面的 claude 安装逻辑是一样的。
6.2 方法二:手动安装到用户目录
如果你不想直接执行安装脚本,也可以手动下载二进制,然后放到自己的用户目录里。
下面给出一种适合 Ubuntu x64 且无 sudo 权限 的思路:
1 | mkdir -p "$HOME/.local/bin" |
如果你确认当前环境更适合 glibc 版本,也可以去仓库 release 页面选择对应压缩包再安装。
安装完成后,验证命令:
1 | cc-switch --version |
7 使用 cc-switch 为 Claude Code 配置 provider
安装好 cc-switch 之后,就可以开始给 Claude Code 配置 provider 了。
最推荐的用法是直接指定 --app claude,这样可以明确告诉 cc-switch:你现在要操作的是 Claude Code 的配置。
先看一下当前已有的 provider:
1 | cc-switch --app claude provider list |
如果你是第一次使用,通常列表里还没有你需要的配置。这时可以新增一个 provider:
1 | cc-switch --app claude provider add |
执行后,一般会进入交互式配置流程。不同版本界面可能略有差异,但你通常需要填写这些核心信息:
API Key:你的接口密钥Base URL:你所使用服务对应的接口地址Model:你准备使用的模型名称Provider Name:给这个配置起一个便于识别的名字
一个典型的思路如下:
Provider Name:自定义一个好记的名称,例如my-claude-providerAPI Key:填入你自己的 keyBase URL:填入你自己的服务地址Model:填入目标模型名
如果你已经有一个 provider,只是想修改其中的 apikey、base_url 或 model,可以直接编辑:
1 | cc-switch --app claude provider edit <id> |
其中 <id> 可以先通过下面这条命令查看:
1 | cc-switch --app claude provider list |
7.1 切换当前 provider
配置完成后,可以切换到目标 provider:
1 | cc-switch --app claude provider switch <id> |
切换后,可以查看当前正在使用哪个 provider:
1 | cc-switch --app claude provider current |
7.2 拉取可用模型列表
如果你不确定模型名该怎么填,可以尝试让 cc-switch 帮你拉取模型列表:
1 | cc-switch --app claude provider fetch-models <id> |
这样可以减少因为模型名拼错而导致的配置失败。
7.3 检查环境变量冲突
有些同学之前可能已经在 shell 配置文件里写过诸如 ANTHROPIC_API_KEY 或其他 API 相关环境变量,这会和 cc-switch 当前写入的配置产生冲突。
这时可以执行:
1 | cc-switch env check --app claude |
8 配置完成后再次启动 Claude Code
当 cc-switch 的 provider 配置好之后,可以重新启动:
1 | claude |
如果一切正常,这时 Claude Code 就会基于你当前的 provider 配置工作。
如果你修改过 shell 配置文件,建议先重新打开一个终端,或者执行:
1 | source ~/.bashrc |
然后再启动 claude,这样可以避免因为环境变量还没刷新而导致配置没有生效。
接着可以输入 /model,查看当前可选模型列表,确认 cc-switch 中配置的模型是否已经被正确识别出来。
最后,建议直接做一个最简单的功能测试,例如让 Claude Code 写一段冒泡排序代码。如果可以正常返回结果,基本就说明当前配置已经可以投入使用。
9 FAQ🚧🚧🚧
下面把这套流程里最常见的几个问题统一整理一下。
9.1 claude: command not found
这通常说明以下两种情况之一:
Claude Code没有真正安装成功- 程序已经安装到了
~/.local/bin,但当前PATH没有包含它
建议依次排查:
1 | ls ~/.local/bin/claude |
如果文件存在,但命令找不到,就执行:
1 | export PATH="$HOME/.local/bin:$PATH" |
确认无误后,再把它写进 ~/.bashrc。
9.2 cc-switch: command not found
这个问题和上面完全一样,本质上也是用户目录下的可执行文件没有被当前 shell 正确识别。
同样优先检查:
1 | echo $PATH |
9.3 已经安装成功,但执行 claude 时要求登录且无法完成认证
这种情况通常不是安装问题,而是认证方式问题。常见原因包括:
- 当前账号本身没有
Claude Code使用权限 - 当前环境下浏览器认证流程不方便完成
- 当前网络或地区环境不适合直接走官方登录流程
这时可以考虑改用 cc-switch 为 Claude Code 配置你已有权限的 API provider。
9.4 明明已经切换了 provider,但配置没有生效
这种情况很常见,尤其是在你之前手动写过环境变量的时候。
优先执行:
1 | cc-switch env check --app claude |
确认是否存在旧的 ANTHROPIC_API_KEY 或其他相关环境变量覆盖了当前配置。
9.5 模型名称填写错误
如果 model 名称填错,通常会表现为:
- 启动后请求失败
- provider 可以切换,但实际调用时报错
建议优先使用:
1 | cc-switch --app claude provider fetch-models <id> |
先拉取可用模型列表,再回头填写正确的模型名。
9.6 Ubuntu 上安装 cc-switch 失败
如果是使用安装脚本失败,优先怀疑 Linux 发布包与当前 libc 环境不匹配。对于 Ubuntu,可以先重试 glibc 方式:
1 | curl -fsSL https://github.com/saladday/cc-switch-cli/releases/latest/download/install.sh | CC_SWITCH_LINUX_LIBC=glibc bash |
如果还是不行,就改用手动下载二进制的方式,并检查当前机器架构是否为 x64。
10 小结
对于 没有 sudo 权限的 Ubuntu 服务器用户,安装 Claude Code 的思路并不复杂:
- 先用官方脚本安装
Claude Code - 用
claude --version验证是否安装成功 - 如果命令找不到,检查
~/.local/bin是否加入PATH - 如果首次登录不方便,或者你本来就要使用自定义 provider,则安装
cc-switch CLI - 通过
provider add、provider switch、provider fetch-models等命令完成配置
整体上,这套流程最大的关键并不是安装命令本身,而是两件事:
- 用户目录下的命令是否已经进入
PATH - 当前
Claude Code最终读取的是哪一套 provider / 环境变量配置
只要把这两个问题理顺,后面基本就可以稳定使用了。
如果在实际使用过程中还遇到其他问题,可以先自行查询相关资料进一步排查。本博客后续也会继续同步更多常见问题解答 FAQ,供大家参考。





