Công cụ lập trình CLI

Một công cụ lập trình cần ba thiết lập để hoạt động với Shannon: base URL của API, API key của bạn và một model id của Shannon. Trang này đưa ra các thiết lập chính xác cho Claude Code và Codex CLI, giải thích cách model lập trình shannon-coder-1 được tính, và liệt kê các lỗi mà những tool này gặp phải.

Mỗi tool dùng endpoint nào

Cả ba endpoint nhận cùng một API key, dưới dạng Authorization: Bearer hoặc x-api-key. Các header anthropic-version, anthropic-beta và openai-beta mà các tool này gửi đều được chấp nhận.

Chọn một model Shannon

Mỗi yêu cầu phải nêu một model id mà Shannon công bố. Công cụ lập trình gửi tên model mặc định của chính nó trừ khi bạn chỉ định khác, và tên mà Shannon không công bố được trả lời bằng 400 và thông báo unknown model: <name>. Không có tên nào khác được ánh xạ sang model Shannon, nên hãy đặt model trong tool trước yêu cầu đầu tiên.

GET /v1/models liệt kê mọi id cùng cửa sổ ngữ cảnh của nó. Không cần key. Model và giá

Các công cụ lập trình điều khiển model bằng một system prompt dài. System prompt được áp dụng bởi shannon-coder-1, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro và các model open-weight hosted, vì vậy hãy chọn một trong số này cho công cụ lập trình.

Claude Code

Claude Code đọc cấu hình kết nối từ biến môi trường. Hãy đặt chúng trong shell khởi chạy nó, hoặc trong khối env của ~/.claude/settings.json để giữ cho mọi phiên.

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Where to send requests, and your Shannon API key
export ANTHROPIC_BASE_URL=https://api.shannon-ai.com
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY

# Shannon model ids: the session model, and the model behind each built-in name
export ANTHROPIC_MODEL=shannon-coder-1
export ANTHROPIC_DEFAULT_OPUS_MODEL=shannon-coder-1
export ANTHROPIC_DEFAULT_SONNET_MODEL=shannon-coder-1
export ANTHROPIC_DEFAULT_HAIKU_MODEL=shannon-1.6-lite

# The context window of the session model
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=131072

claude

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.shannon-ai.com",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "shannon-coder-1",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "shannon-coder-1",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "shannon-coder-1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "shannon-1.6-lite",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "131072"
  }
}

• Hãy đặt cả ba biến ANTHROPIC_DEFAULT_…_MODEL. Subagent và một số lệnh yêu cầu model theo tên có sẵn của nó, và mỗi tên phải trỏ tới một id của Shannon.
• Mẫu này trỏ các yêu cầu nền tới shannon-1.6-lite, được tính theo token. Khi đó tiêu đề phiên và các yêu cầu tương tự không dùng lượt gọi Coder.
• Claude Code gọi POST /v1/messages/count_tokens để biết kích thước ngữ cảnh. Endpoint này đếm cho các model open-weight hosted. Với id của Shannon, nó trả lời 400; Claude Code coi việc đếm token là tùy chọn và tự ước tính kích thước. Đếm token

Để kiểm tra địa chỉ, key và model id trước khi khởi chạy tool, hãy gửi thử một yêu cầu bằng tay:

curl https://api.shannon-ai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-1.6-lite",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Say OK."}]
  }'

Codex CLI

Codex CLI trao đổi với Responses API. Hãy mô tả Shannon như một model provider trong ~/.codex/config.toml, chọn một model id của Shannon ở đó, và đặt API key của bạn vào biến môi trường mà provider nêu tên.

model = "shannon-coder-1"
model_provider = "shannon"
model_context_window = 131072

[model_providers.shannon]
name = "Shannon"
base_url = "https://api.shannon-ai.com/v1"
env_key = "SHANNON_API_KEY"
wire_api = "responses"

# Install Codex CLI
npm install -g @openai/codex

# Your Shannon API key, under the name given as env_key
export SHANNON_API_KEY=YOUR_API_KEY

# Start it; --model selects another Shannon id for one run
codex
codex --model shannon-1.6-pro

• /v1/responses không lưu cuộc hội thoại trên server: mỗi yêu cầu mang cuộc hội thoại trong input. previous_response_id được chấp nhận để tương thích.
• Function tool (type: "function") được cung cấp cho model trên /v1/responses.
• Trên /v1/responses, shannon-coder-1 được tính theo token từ số dư của bạn, không tính theo lượt gọi Coder.

Cách kiểm tra tương tự cho endpoint Responses:

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-1.6-lite",
    "input": "Say OK."
  }'

Model lập trình và cách nó được tính

shannon-coder-1 là model Shannon dành cho các agent lập trình. GET /v1/models báo nó với cửa sổ ngữ cảnh 131,072 token, gọi tool, suy luận và đầu vào văn bản. Nó được tính theo một trong hai cách, tùy endpoint mà tool sử dụng.

Một lượt gọi là một yêu cầu, bất kể kích thước. Nó được tính khi yêu cầu được chấp nhận, trước khi model trả lời. Một phiên agent gửi một yêu cầu cho mỗi bước nó thực hiện, nên một tác vụ dài dùng nhiều lượt gọi. Hạn mức tùy theo gói của bạn và bắt đầu lại sau mỗi 4 giờ, vào 00:00, 04:00, 08:00, 12:00, 16:00 và 20:00 UTC.

Trang gói hiển thị các con số hiện tại. Các gói

Khi các lượt gọi của một khung thời gian đã dùng hết, yêu cầu được trả lời bằng 429. Trên /v1/messages, cùng lỗi đó đến theo cấu trúc của Anthropic.

{
  "error": {
    "type": "rate_limit_error",
    "message": "Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan"
  }
}

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan"
  }
}

Tràn ngữ cảnh

Khi một cuộc hội thoại lớn hơn cửa sổ ngữ cảnh của model, /v1/chat/completions và /v1/messages trả lời bằng 400, loại invalid_request_error, mã context_length_exceeded và một thông báo bắt đầu bằng prompt is too long. Các công cụ lập trình đọc lỗi này để nén phiên và gửi lại yêu cầu. Lỗi này do shannon-coder-1, shannon-1.6-lite và shannon-1.6-pro tạo ra.

{
  "error": {
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "message": "prompt is too long: 140211 tokens > 131072 maximum",
    "param": null
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "message": "prompt is too long: 140211 tokens > 131072 maximum",
    "param": null
  }
}

Thông báo là prompt is too long: <sent> tokens > <limit> maximum. Khi không biết hai con số đó, thông báo là prompt is too long. Please compact the conversation and try again.

Trên stream, trạng thái đã là 200, nên lỗi đến dưới dạng một sự kiện và stream sau đó đóng lại bình thường:

data: {"error":{"message":"prompt is too long: 140211 tokens > 131072 maximum","type":"invalid_request_error","code":"context_length_exceeded","param":null}}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":…,"model":"shannon-coder-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{…}}

data: [DONE]

event: error
data: {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 140211 tokens > 131072 maximum"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{…}}

event: message_stop
data: {"type":"message_stop"}

Những gì một vòng lặp agent có thể dựa vào

Khắc phục sự cố

Key và số dư của bạn nằm ở trang Keys & usage. Keys & usage