Ubuntu系统下Claude Code API新手入门指南：从环境搭建到第一个API调用

5次阅读

共计 2370 个字符，预计需要花费 6 分钟才能阅读完成。

推荐使用 Ubuntu 20.04 LTS 或更高版本。较新的系统版本能确保更好的兼容性和安全性支持。

检查 Python 版本：
```
python3 --version
```
建议使用 Python 3.8 及以上版本。

安装 pip（Python 包管理器）：

sudo apt update
sudo apt install python3-pip

如果系统中存在多个 Python 版本，可以使用 virtualenv 创建虚拟环境：
```
sudo apt install python3-venv
python3 -m venv claude-env
source claude-env/bin/activate
```

sudo apt install -y curl libssl-dev

登录 Claude 开发者平台
进入 ”API Keys” 页面
点击 ”Create new API key” 按钮
复制生成的密钥（注意保密）

最佳实践是将 API 密钥存储在环境变量中，而不是直接写在代码里：

export CLAUDE_API_KEY="your_api_key_here"

使用 curl 测试 API 是否正常工作：

curl -X POST https://api.claude.ai/v1/completions \
-H "Authorization: Bearer $CLAUDE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Hello, world","max_tokens": 5}'

安装 requests 库：

pip install requests

完整的 Python 代码示例：

import os
import requests

# 从环境变量获取 API 密钥
api_key = os.getenv("CLAUDE_API_KEY")
if not api_key:
    raise ValueError("请设置 CLAUDE_API_KEY 环境变量")

# API 端点
url = "https://api.claude.ai/v1/completions"

# 请求头
headers = {"Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# 请求数据
# temperature（温度）控制生成文本的随机性（0-1）# max_tokens 限制响应长度
payload = {
    "prompt": "写一首关于春天的诗",
    "temperature": 0.7,
    "max_tokens": 100
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()  # 检查错误

    # 解析响应
    result = response.json()
    print(result["choices"][0]["text"])

except requests.exceptions.HTTPError as err:
    # 处理 HTTP 错误
    if response.status_code == 429:
        print("请求过于频繁，请稍后再试")
    else:
        print(f"HTTP 错误: {err}")
except Exception as err:
    print(f"其他错误: {err}")

为了防止触发 Rate Limiting（速率限制），建议：

实现请求间隔控制（如每秒不超过 3 次请求）
使用指数退避算法处理 429 错误

方案	优点	缺点
环境变量	简单易用，不存储在代码中	重启后需要重新设置
配置文件	持久化存储，易于管理	需要确保文件安全
密钥管理服务	最安全，支持自动轮换	配置复杂，可能有额外成本

代码	含义	解决方案
400	请求参数错误	检查请求体格式
401	认证失败	检查 API 密钥
403	禁止访问	确认账户权限
429	请求过多	降低请求频率
500	服务器错误	稍后重试或联系支持

当遇到 429 错误时，可以实现指数退避重试：

import time

max_retries = 3
base_delay = 1  # 初始延迟 1 秒

for attempt in range(max_retries):
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        break
    except requests.exceptions.HTTPError as err:
        if response.status_code == 429:
            delay = base_delay * (2 ** attempt)  # 指数退避
            print(f"等待 {delay} 秒后重试...")
            time.sleep(delay)
            continue
        raise

流式响应（Streaming）适合需要即时显示结果的场景（如聊天应用），可以减少用户感知的延迟。普通响应则适合一次性获取完整结果的场景，处理更简单。

实现一个带历史对话记忆的 CLI 聊天工具：