一、前置条件与系统准备
1.1 系统要求确认
Claude Code 在 Ubuntu 20.04 及以上版本均受支持，Ubuntu 25.10 Server 完全兼容。硬件方面需要至少 4 GB RAM，处理器为 x64 或 ARM64 架构。网络方面需要能够访问 Anthropic API 端点（claude.ai 和 api.anthropic.com）。
1.2 更新系统与安装基础依赖
以 root 或具备 sudo 权限的用户登录服务器，依次执行：
bash
sudo apt update && sudo apt upgrade -y sudo apt install -y curl jq git build-essential
jq 用于后续 JSON 配置处理，git 用于 Agent 项目中的版本控制操作，build-essential 确保编译工具链完整。
注意事项：Ubuntu 25.10 的软件源可能包含较新版本的包，如果 apt upgrade 提示需要重启，建议先重启完成内核更新再继续。
二、安装 Claude Code
Claude Code 提供三种安装方式：原生脚本安装（推荐）、npm 全局安装、以及 Linux 包管理器安装（apt/dnf/apk）。推荐使用原生脚本方式，该方式自动处理依赖并在后台保持更新。
2.1 原生脚本安装（推荐）
bash
curl -fsSL https://claude.ai/install.sh | bash
安装完成后，刷新 Shell 配置以使 claude 命令生效：
bash
source ~/.bashrc
如果使用 zsh，则执行 source ~/.zshrc。
2.2 验证安装
bash
claude --version
如果命令未找到，检查 ~/.local/bin 是否在 PATH 中：
bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc
也可以运行内置诊断命令检查安装状态：
bash
claude doctor
该命令会检查 PATH 配置、安装状态和自动更新设置。
2.3 替代方式：npm 安装
如果原生脚本因网络原因失败，可使用 npm 方式。确保 Node.js 18+ 已安装：
bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node --version # 确认 >= 18
然后全局安装（不要使用 sudo npm，以避免权限问题）：
bash
npm install -g @anthropic-ai/claude-code
2.4 替代方式：Snap 安装
Ubuntu 25.10 Server 默认支持 Snap。社区维护的 Snap 包可用：
bash
sudo snap install claude-code
注意这是社区维护的封装包，不是 Anthropic 官方发布。
安装方式选择建议：优先使用原生脚本安装。Snap 方式因其严格沙箱限制，Agent 需要访问项目文件时可能需要额外配置文件系统权限。
三、配置 API Token
Claude Code 通过环境变量读取 API 密钥。API Key 需要从 Claude Console（platform.claude.com）创建和获取。
3.1 获取 API Key
-
访问
https://platform.claude.com/，使用 Anthropic 账户登录 -
进入 “API Keys” 页面
-
点击 “Create Key”，复制生成的密钥（格式为
sk-ant-api03-...）
重要：API Key 仅在创建时显示一次，务必立即保存到安全位置。
3.2 方式一：临时环境变量（适合测试）
bash
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"
这种方式仅在当前 Shell 会话中生效，关闭终端后失效。
3.3 方式二：写入 ~/.bashrc（推荐，持久生效）
bash
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"' >> ~/.bashrc source ~/.bashrc
验证设置是否生效：
bash
echo $ANTHROPIC_API_KEY
安全注意事项：~/.bashrc 中的密钥以明文存储，在多用户共享服务器上建议改用 .env 文件配合 dotenv 加载，或使用密钥管理工具。确保 .bashrc 文件权限为 600：
bash
chmod 600 ~/.bashrc
3.4 方式三：使用 .env 文件（适合 Agent 项目）
在 Agent 项目目录中创建 .env 文件：
bash
echo 'ANTHROPIC_API_KEY=sk-ant-api03-你的密钥' > .env
并添加 .env 到 .gitignore，防止密钥被提交到版本库：
bash
echo '.env' >> .gitignore
在 Python Agent 代码中通过 python-dotenv 加载：
bash
pip install python-dotenv
python
from dotenv import load_dotenv load_dotenv()
3.5 方式四：settings.json 全局配置
Claude Code 也支持通过 ~/.claude/settings.json 的 env 字段配置环境变量。创建或编辑该文件：
bash
mkdir -p ~/.claude cat > ~/.claude/settings.json << 'EOF' { "env": { "ANTHROPIC_API_KEY": "sk-ant-api03-你的密钥" } } EOF chmod 600 ~/.claude/settings.json
3.6 企业代理环境配置
如果服务器位于企业内网需要通过代理访问外网，配置标准代理环境变量：
bash
export HTTPS_PROXY=https://proxy.example.com:8080 export HTTP_PROXY=http://proxy.example.com:8080 export NO_PROXY="localhost,127.0.0.1"
同样建议将这些写入 ~/.bashrc 以持久生效。如果使用自建 LLM Gateway，可额外设置 ANTHROPIC_BASE_URL 指向网关地址。
四、部署 Agent 智能体
Claude Code 的 Agent 能力通过 Agent SDK 实现。Python SDK 和 TypeScript SDK 均捆绑了原生 Claude Code 二进制文件，安装 SDK 后无需单独安装 Claude Code。
4.1 创建 Agent 项目目录
bash
mkdir -p ~/my-agent && cd ~/my-agent
Agent 默认有权访问该目录及其子目录中的文件。
4.2 安装 Agent SDK
Python 方式（推荐） ：
bash
python3 -m venv .venv
source .venv/bin/activate pip install claude-agent-sdk
关键注意事项：Ubuntu 25.10 的 Python 启用了 PEP 668 的 externally-managed-environment 保护，必须使用虚拟环境，直接 pip install 到系统 Python 会报错。
TypeScript 方式：
bash
npm init -y npm pkg set type=module npm install @anthropic-ai/claude-agent-sdk npm install --save-dev tsx
4.3 编写 Agent 脚本
创建一个简单的代码审查 Agent。在项目目录下创建 agent.py：
python
import asyncio
import os from dotenv import load_dotenv from claude_agent_sdk import query load_dotenv() async def main(): prompt = """ 审查当前目录下的所有 Python 文件，找出以下问题： 1. 未处理的异常和边界条件 2. 安全漏洞（如硬编码密钥、SQL注入风险） 3. 性能瓶颈 对于每个问题，给出具体的文件路径、行号、问题描述和修复建议。 """ async for message in query(prompt=prompt): print(message) if __name__ == "__main__": asyncio.run(main())
Agent SDK 支持通过 env 选项传入自定义环境变量。Python SDK 会将 env 参数与继承的环境合并，因此父进程中已设置的 ANTHROPIC_API_KEY 会被自动传递。
4.4 运行 Agent
确保 API Key 已在当前 Shell 中设置：
bash
source .venv/bin/activate
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥" python agent.py
Agent 将自动读取目录中的代码文件，执行分析并输出结果。
4.5 在 Claude Code CLI 中直接使用 Agent
除了 SDK 编程方式，也可以在 Claude Code 交互式会话中直接调用 Agent 能力。启动 Claude Code：
bash
cd ~/my-agent
claude
在交互会话中，可以使用 /agents 命令查看和管理可用的子代理（subagent）。Claude Code 支持自定义子代理，当提示词中包含 @agent-name 时，该子代理会作为主会话代理运行。
4.6 创建 CLAUDE.md 项目上下文文件
在项目根目录创建 CLAUDE.md 文件，为 Agent 提供项目特定的上下文和约定：
markdown
# 项目约定 ## 代码风格 - Python 使用 PEP 8 - 函数必须包含类型注解 - 所有公共函数必须有 docstring ## 安全规则 - 禁止在代码中硬编码任何密钥 - 数据库查询必须使用参数化查询 ## 目录结构 - src/ 源代码 - tests/ 测试文件 - docs/ 文档
Claude Code 启动时会自动加载 CLAUDE.md 中的上下文。
五、测试与验证
5.1 基础功能测试
在项目目录中创建测试文件：
bash
cat > test_code.py << 'EOF' def divide(a, b): return a / b def get_user(db, user_id): query = f"SELECT * FROM users WHERE id = {user_id}" return db.execute(query) EOF
该文件包含两个典型问题：divide 函数未处理除零异常，get_user 函数存在 SQL 注入风险。
5.2 使用 Claude Code CLI 测试
bash
cd ~/my-agent
claude "分析 test_code.py 中的安全问题并给出修复方案"
预期输出应包含：除零异常未被捕获、SQL 注入风险、以及相应的修复代码。
5.3 使用 Agent SDK 测试
bash
source .venv/bin/activate
python agent.py
5.4 验证 API 连通性
如果上述测试失败，先确认 API 连通性：
bash
curl -s -o /dev/null -w "%{http_code}" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ https://api.anthropic.com/v1/messages \ -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
返回 200 表示 API 连通正常；返回 401 表示密钥无效；返回 403 表示地区限制或权限不足。
六、注意事项汇总
网络与地区限制：Anthropic API 对部分国家/地区有访问限制。如果服务器位于受限地区，需要配置代理或使用支持的 API 网关。安装和运行 Claude Code 需要能够访问 claude.ai 和 Anthropic API 端点。
Python 虚拟环境强制要求：Ubuntu 25.10 的 Python 3.13 启用了 PEP 668 保护，Agent SDK 必须安装在虚拟环境中。创建虚拟环境后，每次运行 Agent 前需先激活：source .venv/bin/activate。
密钥安全管理：API Key 应以明文出现在 .bashrc、.env 或 settings.json 中时，确保文件权限为 600。在多用户服务器上，考虑使用 env 命令通过进程环境传递密钥，避免写入磁盘文件。.env 必须加入 .gitignore，防止密钥泄露到版本库。
Snap 沙箱限制：如果使用 Snap 方式安装 Claude Code，Snap 的严格沙箱机制可能阻止 Agent 访问项目目录中的文件。需要按照 Snap 包文档配置文件系统访问权限，或将项目放在 Snap 允许访问的目录中。
代理环境变量优先级：Claude Code 按照 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 的顺序读取代理配置，第一个被设置的变量生效。同时设置大小写变体时注意优先级顺序。
Agent SDK 与 CLI 的关系：Agent SDK 捆绑了原生 Claude Code 二进制文件，安装 SDK 后无需单独安装 CLI。但如果 SDK 无法自动解析捆绑的 CLI 路径，可以手动指定：
bash
export CLAUDE_BIN="/usr/local/bin/claude"
自动更新：原生脚本安装的 Claude Code 会在后台自动更新。如果服务器环境要求版本锁定，需要禁用自动更新或使用 Snap/npm 方式安装并手动控制版本。
资源消耗：Agent 执行复杂任务时会进行大量文件读取和代码分析，在低配服务器上可能消耗较多内存。建议监控内存使用情况，必要时限制 Agent 的文件访问范围。
文章摘自：https://www.cnblogs.com/Johny-zhao/p/23101767
京ICP备14020293号-4