Claude Agent SDK

Tìm tùy chọn base_url trong SDK sẽ không thấy kết quả nào; đây không phải thiếu sót trong tài liệu — tùy chọn đó không tồn tại. SDK chạy CLI Claude Code dưới dạng tiến trình con, và chính CLI đọc ANTHROPIC_BASE_URL cùng ANTHROPIC_AUTH_TOKEN. Thiết lập hai biến đó sẽ định tuyến mọi lệnh gọi mà tác tử thực hiện, không cần thay đổi mã của tác tử.

# The SDK has no base_url option. The CLI it spawns reads these, and the
# SDK passes the parent environment straight through — so exporting them
# before your program starts is enough.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves: the CLI's default and its opus/sonnet aliases
# follow Anthropic's newest models, and the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, those requests 404.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

python my_agent.py

Vì sao môi trường được chuyển đến CLI

Điều này đáng được giải thích trong một đoạn, vì đây là điểm khác biệt giữa một mẹo có thể ngừng hoạt động và một thuộc tính được ghi nhận mà bạn có thể dựa vào. Cơ chế truyền tải tiến trình con của SDK Python tạo môi trường cho tiến trình con từ os.environ của tiến trình cha, sau khi loại bỏ một khóa duy nhất — CLAUDECODE, để tiến trình con không nghĩ rằng nó đang chạy trong một phiên Claude Code — rồi hợp nhất với CLAUDE_CODE_ENTRYPOINT, tiếp đến là ClaudeAgentOptions.env, sau đó là phiên bản SDK.

Có hai hệ quả, và hệ quả thứ hai là điều nhiều người hiểu nhầm. Mọi thứ trong shell đều đến được CLI, vì vậy xuất hai biến này sẽ hoạt động. Và options.env được hợp nhất sau cùng vào môi trường kế thừa, nên cách thiết lập tường minh sẽ ghi đè biến đã xuất cũ thay vì bị biến đó ghi đè. Mã nguồn nằm trong subprocess_cli.py.

Cách thiết lập tường minh và khi nào cần dùng

Các biến đã xuất dùng được trên máy của bạn nhưng dễ gặp sự cố ở mọi nơi khác: điểm cuối của tác tử trở thành thuộc tính của cách tiến trình được khởi chạy; điều này sẽ gây lỗi khi lần đầu chạy dưới trình lập lịch, trong vùng chứa hoặc trong tác vụ CI không nạp cấu hình hồ sơ của bạn. Truyền env vào đối tượng tùy chọn khiến việc định tuyến trở thành một phần của chương trình.

import asyncio

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# The explicit form. options.env is merged ON TOP of the inherited
# environment, so this wins over whatever the shell happens to hold —
# which is what you want in anything that is not your own laptop.
options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
        "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
        "ANTHROPIC_MODEL": "claude-sonnet-5",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    },
)


async def main():
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Summarise the open TODOs in this repo")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Từng bước

1. Tạo khóa tại /app/keys rồi sao chép khóa — khóa chỉ hiển thị một lần.
2. Chọn nơi cấu hình định tuyến: dùng biến đã xuất khi làm việc cục bộ, dùng ClaudeAgentOptions(env=…) cho mọi tác vụ chạy không cần giám sát.
3. Đặt ANTHROPIC_BASE_URL thành https://api.kunavo.com và ANTHROPIC_AUTH_TOKEN thành khóa sk-kn-… của bạn.
4. Đặt ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL và ANTHROPIC_DEFAULT_SONNET_MODEL thành các ID được cung cấp: mặc định tích hợp của CLI cùng các bí danh opus và sonnet sử dụng các model mới nhất của Anthropic; model mà Kunavo không cung cấp — Sonnet 5.5, được bí danh sonnet yêu cầu — sẽ trả về 404.
5. Đồng thời đặt ANTHROPIC_DEFAULT_HAIKU_MODEL thành claude-haiku-4-5: nếu thiếu, bí danh haiku của CLI sẽ yêu cầu một model ID mà Kunavo không cung cấp (Haiku 5.5 từ v2.1.293), khiến các tác tử con khai báo model: haiku trả về 404. Dòng này cũng đưa các tác vụ phụ chạy nền mà CLI tự khởi chạy sang dòng mô hình rẻ nhất.
6. Chạy chương trình. Không cần thay đổi gì trong mã của tác tử.

Chọn bậc nào cho từng tác vụ phụ

Một tác tử phân tách công việc — một yêu cầu của bạn có thể tạo ra nhiều lượt gọi tính phí — vì vậy việc ánh xạ bậc giá quan trọng ở đây hơn trong ứng dụng trò chuyện. Mức giá tính bằng USD cho mỗi 1M token, đầu vào / đầu ra, được đọc trực tiếp từ danh mục.

Kiểm tra trước khi gỡ lỗi SDK

Chỉ cần một yêu cầu là đủ xác định lỗi nằm ở khóa, điểm cuối hay SDK. Nếu yêu cầu này trả về 200, cùng thông tin xác thực đó cũng dùng được cho CLI mà SDK khởi chạy; nếu vẫn có lỗi, nguyên nhân nằm ở nơi đặt biến chứ không phải giá trị của chúng.

# Settles whether a failure is the key, the endpoint, or the SDK.
# 200 here means the same credential works for the CLI the SDK spawns.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Tài liệu tham khảo

SDK là mã nguồn mở tại anthropics/claude-agent-sdk-python. Hành vi môi trường được mô tả ở đây dựa trên cơ chế truyền tải tiến trình con của SDK, được kiểm tra vào ngày 2026-09-04. SDK TypeScript có cùng kiến trúc — SDK điều khiển CLI thay vì gọi API — nên CLI vẫn đọc các biến định tuyến; README của SDK không ghi lại tùy chọn hay hành vi này, vì vậy hãy xác nhận tên tùy chọn trong các kiểu dữ liệu trước khi dựa vào cách thiết lập tường minh ở đó. Phía Kunavo sử dụng Messages API; các ứng dụng khách khác định tuyến theo cùng cách được liệt kê trên trang tổng hợp tích hợp.