一、概述
Claude Code 是由 Anthropic 开发的AI编程助手，支持在终端中通过自然语言进行代码编写、调试和项目开发。本文档详细介绍在 Ubuntu 系统上部署 Claude Code 的两种官方推荐方式（APT包管理器安装和原生安装脚本），以及安装后的实验环境搭建和 Claude Agent SDK 的核心使用介绍。
二、部署安装：两种方法
方法一：APT包管理器安装（推荐）
APT包管理器安装方式便于系统统一管理和更新，适合大多数用户。
步骤1：安装依赖并添加GPG密钥
如果系统没有 curl，先安装它：
sudo apt update
sudo apt install curl -y
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL
https://downloads.claude.ai/keys/claude-code.asc -o
/etc/apt/keyrings/claude-code.asc
步骤2：验证密钥指纹
验证密钥指纹是否匹配 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE：
gpg --show-keys /etc/apt/keyrings/claude-code.asc
步骤3：添加软件源并安装
配置 stable 渠道（适合大多数用户，更新约有一周延迟，稳定性高）：
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc]
https://downloads.claude.ai/claude-code/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install
claude-code -y
提示：若希望使用最新版本（latest 渠道），将上述命令中的 stable 替换为 latest 即可。
方法二：原生安装脚本
原生安装脚本方式更灵活，可指定版本或渠道。
安装最新版（默认）
curl -fsSL https://claude.ai/install.sh | bash
安装稳定版
curl -fsSL https://claude.ai/install.sh | bash -s stable
安装特定版本（如 2.1.89）
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
三、验证安装与认证
3.1 验证安装
安装完成后，检查版本确保命令可用：
claude --version
claude doctor # 查看更详细的配置状态
3.2 认证方式
Claude Code 需要 Pro、Max 或 Team 等付费账户。
交互式认证
直接运行 claude，根据提示在浏览器中完成 OAuth 登录。
无头服务器认证
运行 claude 会输出一个 URL，复制到本地浏览器完成认证即可。
自动化环境认证
设置 API Key 环境变量（适用于 CI/CD 等场景）：
export ANTHROPIC_API_KEY=sk-ant-api03-...
四、实验环境搭建：tmux + API Key
在远程 Ubuntu 服务器上进行实验时，tmux 是保持 Claude Code 会话在 SSH 断开后依然运行的标准工具。
4.1 安装 tmux
sudo apt-get install -y tmux
4.2 配置 tmux（可选）
创建 ~/.tmux.conf 文件，添加配置如启用鼠标、增大回滚缓冲区等。
4.3 使用工作流
# 1. 创建并进入一个名为 claude 的 tmux 会话
tmux new-session -s claude
# 2. 在会话中进入项目目录并启动 Claude Code
cd ~/your-project
claude
# 3. 需要断开时：按下 Ctrl+b，然后按 d 键，会话会在后台运行
# 4. 重新连接：执行
tmux attach-session -t claude
4.4 API Key 认证持久化
将 API Key 添加到 ~/.bashrc，确保在 tmux 会话中也生效：
echo 'export
ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.bashrc
source ~/.bashrc
五、Agent SDK 核心使用介绍
Agent SDK 允许通过 Python 代码编程控制 Claude Code，构建自动化 Agent。核心是理解 query() 和 ClaudeSDKClient 两种模式的区别，以及 @tool 装饰器的使用。
5.1 安装与导入
安装 Python SDK
pip install claude-agent-sdk
导入核心组件
import asyncio
from claude_agent_sdk import query, ClaudeSDKClient,
ClaudeAgentOptions, tool
5.2 核心接口抉择：query() vs. ClaudeSDKClient
根据任务类型选择合适的接口：
|
特性 |
query() 函数 |
ClaudeSDKClient 类 |
|
适用场景 |
一次性任务、独立问题、简单自动化脚本 |
多轮对话、需要记忆上下文的交互式应用 |
|
会话状态 |
无状态。每次调用都创建新会话，不记得历史 |
有状态。通过 async with 管理会话，上下文在多次 query 间保持 |
|
典型用法 |
async for msg in query(prompt="...", options=...) |
async with ClaudeSDKClient() as client: await client.query("...") |
5.3 核心概念与实验
配置行为（ClaudeAgentOptions）
通过 ClaudeAgentOptions 对象精细控制 Agent 行为，如设置系统提示词、工作目录、权限模式或指定模型：
options = ClaudeAgentOptions(
system_prompt="You are an expert Python
developer.",
permission_mode="acceptEdits", # 自动接受文件编辑
cwd="/home/user/project", # 指定项目目录
model="haiku" # 指定模型
)
实时监控
可以异步迭代 client.receive_response()，根据 ToolUseBlock 或 ToolResultBlock 等不同类型的事件，实时打印进度或执行逻辑。
定义工具（@tool 装饰器）
@tool 装饰器是 Agent SDK 最强大的功能之一。可以用装饰器将任何异步 Python 函数封装成一个 Claude 可以调用的工具：
@tool("greet", "Greet a
user", {"name": str})
async def greet(args):
return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
将工具添加到 options 中，Claude 就能在对话中自主决定调用它。
六、总结
|
方面 |
建议 |
|
安装方式 |
推荐使用 APT 包管理器安装 Claude Code，方便稳定 |
|
远程开发 |
请务必配合 tmux 管理会话，防止 SSH 断开导致任务中断 |
|
SDK 接口选择 |
一次性任务用 query()，多轮对话用 ClaudeSDKClient |
|
能力扩展 |
善用 @tool 装饰器来扩展 Claude 的能力 |
附录：常用命令速查
|
命令 |
说明 |
|
claude --version |
检查 Claude Code 版本 |
|
claude doctor |
查看详细配置状态 |
|
tmux new-session -s claude |
创建新 tmux 会话 |
|
tmux attach-session -t claude |
重新连接 tmux 会话 |
|
pip install claude-agent-sdk |
安装 Agent SDK |
|
export ANTHROPIC_API_KEY=xxx |
设置 API Key 环境变量 |
