Linux服务器 安装Claude Code教程

1
“ AI 不太可能取代你,但一个比你更会使用 AI 的人,可能会。 ”    ————Jensen Huang(黄仁勋)

Claude Code是由Anthropic公司开发的一款AI驱动型的编程Agent命令行工具。这类产品也已经成为当代程序员代码开发不可或缺的重要工具。本文将介绍如何在 Linux 服务器上部署、配置个人Claude Code,利用CC-Switch绕过Claude Code本身的订阅需求,并且无需sudo 权限。

本文主要分成两部分:

  1. 先安装并验证 Claude Code
  2. 如果首次启动时遇到登录受限、地区限制,或者你本来就准备使用自定义 API provider,则继续安装并配置 cc-switch CLI

如果你只是想在服务器上快速把 Claude Code 跑起来,可以先看前半部分;如果你后续还需要切换 provider、配置 apikey、base_url、model,则重点看后半部分。

1 安装前准备

在正式安装之前,可以先确认当前 Ubuntu 环境里至少有 bash 和 curl。

1
2
bash --version
curl --version

如果这两个命令都能正常输出版本号,通常就可以继续后面的安装流程。

检查 Bash 与 curl 的版本信息
图1. 检查 Bash 与 curl 的版本信息。

2 安装 Claude Code

官方推荐的 Linux 安装方式如下:

1
curl -fsSL https://claude.ai/install.sh | bash
使用官方安装脚本安装 Claude Code
图2. 使用官方安装脚本安装 Claude Code。

这条命令会下载官方安装脚本,并直接在当前用户环境中完成安装。对于没有 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
配置 PATH 后检查 Claude Code 命令
图3. 配置 PATH 后检查 Claude Code 命令。

如果这样可以正常识别 claude,说明问题只是当前 shell 环境变量没有生效。为了避免下次重新登录后还要重复设置,可以把它写入 ~/.bashrc:

1
2
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

因此,关于“是否要手动 export 环境变量”这个问题,可以简单总结为:

  • 正常情况下不用手动配置
  • 如果安装后仍然找不到 claude,再手动把 ~/.local/bin 加入 PATH

3 验证 Claude Code 是否安装成功

安装完成后,最直接的验证方法就是查看版本号:

1
claude --version
Claude Code 版本检查
图4. Claude Code 版本检查。

如果能正常输出版本号,说明命令已经安装成功。

进一步还可以执行:

1
claude doctor
Claude Code 环境诊断结果
图5. Claude Code 环境诊断结果。

claude doctor 会帮助检查当前环境中的常见问题,比单纯看版本号更全面一些。

如果你只是想快速确认安装无误,那么至少确保上面这条 claude --version 命令能够正常执行。

4 首次启动 Claude Code

安装完成后,可以直接启动:

1
claude
首次启动 Claude Code
图6. 首次启动 Claude Code。

按照官方流程,首次启动后通常会要求你登录账号,并在浏览器中完成认证。

这里需要注意两点:

  1. Claude Code 不是免费 Claude.ai 账号默认就能使用的功能,通常需要可用的 Pro、Max、Team、Enterprise 或 Console 账户
  2. 某些服务器环境下,可能会遇到登录流程不方便、浏览器认证不顺畅,或者当前网络/地区不支持直接使用的情况

如果你这里可以顺利登录,那么后续直接使用官方账号方式即可;如果你在这一步遇到问题,就可以继续配置 cc-switch CLI,改为使用你自己可用的 API provider。

Claude Code 登录与认证过程示例
图7. Claude Code 登录与认证过程示例。

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 服务器用户,推荐优先考虑下面两种思路:

  1. 直接使用官方安装脚本
  2. 手动下载二进制到自己的用户目录

6 安装 cc-switch CLI

6.1 方法一:使用官方安装脚本

最简单的安装方式是:

1
curl -fsSL https://github.com/saladday/cc-switch-cli/releases/latest/download/install.sh | bash
通过安装脚本安装 cc-switch CLI
图8. 通过安装脚本安装 cc-switch CLI。

这个方式默认会把程序安装到用户目录下,通常对没有 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 CLI 版本信息
图9. 检查 cc-switch CLI 版本信息。

如果终端提示找不到 cc-switch,优先检查 ~/.local/bin 是否已经加入到 PATH。这一点和前面的 claude 安装逻辑是一样的。

6.2 方法二:手动安装到用户目录

如果你不想直接执行安装脚本,也可以手动下载二进制,然后放到自己的用户目录里。

下面给出一种适合 Ubuntu x64 且无 sudo 权限 的思路:

1
2
3
4
5
mkdir -p "$HOME/.local/bin"
curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-x64-musl.tar.gz
tar -xzf cc-switch-cli-linux-x64-musl.tar.gz
chmod +x cc-switch
mv cc-switch "$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
查看 Claude Code 的 provider 配置列表
图10. 查看 Claude Code 的 provider 配置列表。

如果你是第一次使用,通常列表里还没有你需要的配置。这时可以新增一个 provider:

1
cc-switch --app claude provider add
通过交互式界面新增 provider
图11. 通过交互式界面新增 provider。

执行后,一般会进入交互式配置流程。不同版本界面可能略有差异,但你通常需要填写这些核心信息:

  • API Key:你的接口密钥
  • Base URL:你所使用服务对应的接口地址
  • Model:你准备使用的模型名称
  • Provider Name:给这个配置起一个便于识别的名字

一个典型的思路如下:

  • Provider Name:自定义一个好记的名称,例如 my-claude-provider
  • API Key:填入你自己的 key
  • Base URL:填入你自己的服务地址
  • Model:填入目标模型名
填写 provider 的 API 与模型配置
图12. 填写 provider 的 API 与模型配置。

如果你已经有一个 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>
查询 provider 提供的模型列表
图13. 查询 provider 提供的模型列表。

这样可以减少因为模型名拼错而导致的配置失败。

7.3 检查环境变量冲突

有些同学之前可能已经在 shell 配置文件里写过诸如 ANTHROPIC_API_KEY 或其他 API 相关环境变量,这会和 cc-switch 当前写入的配置产生冲突。

这时可以执行:

1
2
cc-switch env check --app claude
cc-switch env list --app claude

8 配置完成后再次启动 Claude Code

当 cc-switch 的 provider 配置好之后,可以重新启动:

1
claude
使用配置后的 provider 启动 Claude Code
图14. 使用配置后的 provider 启动 Claude Code。

如果一切正常,这时 Claude Code 就会基于你当前的 provider 配置工作。

如果你修改过 shell 配置文件,建议先重新打开一个终端,或者执行:

1
source ~/.bashrc

然后再启动 claude,这样可以避免因为环境变量还没刷新而导致配置没有生效。

接着可以输入 /model,查看当前可选模型列表,确认 cc-switch 中配置的模型是否已经被正确识别出来。

通过 /model 查看可选模型
图15. 通过 /model 查看可选模型。

最后,建议直接做一个最简单的功能测试,例如让 Claude Code 写一段冒泡排序代码。如果可以正常返回结果,基本就说明当前配置已经可以投入使用。

使用 Claude Code 生成冒泡排序代码的功能测试
图16. 使用 Claude Code 生成冒泡排序代码的功能测试。

9 FAQ🚧🚧🚧

下面把这套流程里最常见的几个问题统一整理一下。

9.1 claude: command not found

这通常说明以下两种情况之一:

  1. Claude Code 没有真正安装成功
  2. 程序已经安装到了 ~/.local/bin,但当前 PATH 没有包含它

建议依次排查:

1
2
ls ~/.local/bin/claude
echo $PATH

如果文件存在,但命令找不到,就执行:

1
export PATH="$HOME/.local/bin:$PATH"

确认无误后,再把它写进 ~/.bashrc。

9.2 cc-switch: command not found

这个问题和上面完全一样,本质上也是用户目录下的可执行文件没有被当前 shell 正确识别。

同样优先检查:

1
2
echo $PATH
ls ~/.local/bin/cc-switch

9.3 已经安装成功,但执行 claude 时要求登录且无法完成认证

这种情况通常不是安装问题,而是认证方式问题。常见原因包括:

  • 当前账号本身没有 Claude Code 使用权限
  • 当前环境下浏览器认证流程不方便完成
  • 当前网络或地区环境不适合直接走官方登录流程

这时可以考虑改用 cc-switch 为 Claude Code 配置你已有权限的 API provider。

9.4 明明已经切换了 provider,但配置没有生效

这种情况很常见,尤其是在你之前手动写过环境变量的时候。

优先执行:

1
2
cc-switch env check --app claude
cc-switch env list --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 的思路并不复杂:

  1. 先用官方脚本安装 Claude Code
  2. 用 claude --version 验证是否安装成功
  3. 如果命令找不到,检查 ~/.local/bin 是否加入 PATH
  4. 如果首次登录不方便,或者你本来就要使用自定义 provider,则安装 cc-switch CLI
  5. 通过 provider add、provider switch、provider fetch-models 等命令完成配置

整体上,这套流程最大的关键并不是安装命令本身,而是两件事:

  • 用户目录下的命令是否已经进入 PATH
  • 当前 Claude Code 最终读取的是哪一套 provider / 环境变量配置

只要把这两个问题理顺,后面基本就可以稳定使用了。

如果在实际使用过程中还遇到其他问题,可以先自行查询相关资料进一步排查。本博客后续也会继续同步更多常见问题解答 FAQ,供大家参考。