跳到正文
CLI 编程工具

CLI 编程工具

新

将 Shannon 用作 Claude Code、Codex CLI 及其他智能体 CLI 背后的模型。

编程工具需要三项设置才能配合 Shannon 使用：API 的 base URL、你的 API 密钥，以及 Shannon 模型 id。本页给出 Claude Code 和 Codex CLI 的确切设置，说明编程模型 shannon-coder-1 如何计数，并列出这些工具会遇到的错误。

每个工具使用哪个端点

工具 端点 要设置的 base URL 备注
Claude Code POST /v1/messages
POST /v1/messages/count_tokens		 https://api.shannon-ai.com 工具会自行在 base URL 后添加 /v1/messages。
Codex CLI POST /v1/responses https://api.shannon-ai.com/v1 工具会在 base URL 后添加 /responses。
其他使用 OpenAI 聊天格式的智能体工具 POST /v1/chat/completions https://api.shannon-ai.com/v1 在工具自己的设置中填写 base URL、密钥和 Shannon 模型 id。

三个端点使用同一个 API 密钥，可作为 Authorization: Bearer 或 x-api-key 发送。这些工具发送的 anthropic-version、anthropic-beta 和 openai-beta 请求头会被接受。

选择 Shannon 模型

每个请求都必须指定 Shannon 已发布的模型 id。除非你另行设置，编程工具会发送它自己默认模型的名称，而 Shannon 未发布的名称会得到 400 和消息 unknown model: <name>。其他名称不会被映射到 Shannon 模型，因此请在第一个请求之前，先在工具中设置好模型。

GET /v1/models 列出每个 id 及其上下文窗口。无需密钥。 模型与定价

模型 计作 带来什么
shannon-coder-1 在 /v1/messages 和 /v1/chat/completions 上每个请求算一次调用。在 /v1/responses 上按 tokens 计。 编程模型。文本输入、工具调用、131,072 tokens 上下文窗口。
shannon-1.6-lite
shannon-1.6-pro		 从你的余额中扣除 tokens。 支持工具调用的通用模型。shannon-1.6-lite 适合工具发出的简短后台请求。
托管开源权重模型 从你的余额中扣除 tokens，缓存输入按输入价格的 25% 计费。 支持工具调用、适用于长会话的 prompt 缓存，以及来自 /v1/messages/count_tokens 的精确计数。

编程工具通过很长的系统提示词来引导模型。shannon-coder-1、shannon-1.6-lite、shannon-1.6-pro、shannon-2-lite、shannon-2-pro 以及托管开源权重模型会应用系统提示词，因此请为编程工具选择其中之一。

Claude Code

Claude Code 从环境变量读取其连接设置。可在启动它的 shell 中设置，或在 ~/.claude/settings.json 的 env 块中设置，使其对每个会话都生效。

# 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
变量 说明
ANTHROPIC_BASE_URL Claude Code 发送请求的地址。使用不带 /v1 的地址。
ANTHROPIC_AUTH_TOKEN 你的 Shannon API 密钥，以 Authorization: Bearer 发送。ANTHROPIC_API_KEY 同样可用：它以 x-api-key 发送密钥，Claude Code 会询问一次是否批准。
ANTHROPIC_MODEL 会话使用的模型。claude --model <id> 和 /model <id> 设置的是同一项。
ANTHROPIC_DEFAULT_HAIKU_MODEL 用于后台请求（如会话标题）以及任何请求 haiku 的场合的模型。
ANTHROPIC_DEFAULT_SONNET_MODEL 子智能体或命令请求 sonnet 时使用的模型。
ANTHROPIC_DEFAULT_OPUS_MODEL 子智能体或命令请求 opus 时使用的模型。
CLAUDE_CODE_MAX_CONTEXT_TOKENS Claude Code 为该模型假定的上下文窗口。请使用 GET /v1/models 为你所选 id 报告的 context_window。
  • 请设置全部三个 ANTHROPIC_DEFAULT_…_MODEL 变量。子智能体和某些命令会按内置名称请求模型，每个名称都必须解析为一个 Shannon id。
  • 该示例将后台请求指向按 tokens 计数的 shannon-1.6-lite。这样会话标题等类似请求就不会占用 Coder 调用。
  • Claude Code 通过 POST /v1/messages/count_tokens 询问上下文的大小。该端点对托管开源权重模型计数。对 Shannon id 它会返回 400；Claude Code 将 tokens 计数视为可选，会自行估算大小。 Token 计数

要在启动工具之前检查地址、密钥和模型 id，可手动发送一个请求：

cURL 
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 与 Responses API 通信。请在 ~/.codex/config.toml 中把 Shannon 描述为模型提供方，在其中选择一个 Shannon 模型 id，并把你的 API 密钥放入该提供方所指定的环境变量中。

~/.codex/config.toml 
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"
Shell 
# 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
键 说明
model Shannon 模型 id。codex --model <id> 为单次运行设置它。
model_provider 要使用的 provider 块的名称，这里是 shannon。
base_url 带 /v1 的 API 地址。
env_key 保存你的 Shannon API 密钥的环境变量名称。
wire_api responses：Codex 与 POST /v1/responses 通信。
model_context_window 模型的上下文窗口，使 Codex 能及时压缩长会话。请使用 GET /v1/models 报告的 context_window。
  • /v1/responses 不在服务器上保存对话：每个请求都在 input 中携带对话。为了兼容，previous_response_id 会被接受。
  • 函数工具（type: "function"）在 /v1/responses 上会提供给模型。
  • 在 /v1/responses 上，shannon-coder-1 按你余额中的 tokens 计数，而不是按 Coder 调用计数。

对 Responses 端点的同样检查：

cURL 
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."
  }'

编程模型及其计数方式

shannon-coder-1 是面向编程智能体的 Shannon 模型。GET /v1/models 报告它的上下文窗口为 131,072 tokens，支持工具调用、推理和文本输入。根据工具使用的端点不同，它有两种计数方式之一。

端点 一个请求的成本 扣自
/v1/messages 每个请求 1 次调用 你的计划的 Coder 调用额度。不会从你的余额中扣除 tokens。
/v1/chat/completions 每个请求 1 次调用 你的计划的 Coder 调用额度。不会从你的余额中扣除 tokens。
/v1/responses tokens，每 1M $8.00 你的余额，与其他任何模型一样。不使用调用额度。

一次调用就是一个请求，无论其大小。它在请求被接受时、模型作答之前计数。智能体会话的每一步都会发送一个请求，因此长任务会消耗很多次调用。额度取决于你的计划，每 4 小时重新开始，时间为 UTC 的 00:00、04:00、08:00、12:00、16:00 和 20:00。

计划 每个 4 小时窗口的调用次数
Free 3
Plus 20
Standard 40
Pro 60

计划页面显示当前的数字。 计划

当一个窗口内的调用次数用完时，请求会得到 429。在 /v1/messages 上，同一错误以 Anthropic 的结构给出。

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

上下文溢出

当对话超出模型的上下文窗口时，/v1/chat/completions 和 /v1/messages 会返回 400，类型为 invalid_request_error，代码为 context_length_exceeded，消息以 prompt is too long 开头。编程工具读取此错误后会压缩会话并重新发送请求。shannon-coder-1、shannon-1.6-lite 和 shannon-1.6-pro 会产生此错误。

400 /v1/chat/completions 
{
  "error": {
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "message": "prompt is too long: 140211 tokens > 131072 maximum",
    "param": null
  }
}
400 /v1/messages 
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "message": "prompt is too long: 140211 tokens > 131072 maximum",
    "param": null
  }
}

消息为 prompt is too long: <sent> tokens > <limit> maximum。当这两个数字未知时，消息为 prompt is too long. Please compact the conversation and try again.

在流上，状态码已经是 200，因此错误以事件形式到达，之后流按正常方式关闭：

/v1/chat/completions，流 
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]
/v1/messages，流 
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"}

智能体循环可以依赖什么

主题 行为
工具 schema 工具定义按工具发送的原样接收。在 shannon-coder-1 和 shannon-1.6-* 上，模型用不到的 JSON Schema 关键字（如 $schema、$ref、additionalProperties、default 和 title）不会出现在模型所读取的内容中，oneOf 按 anyOf 读取。不会因这些关键字而拒绝任何请求。
工具调用参数 在流中，工具调用的参数会在一个 delta 中完整到达：tool_calls[].function.arguments、input_json_delta.partial_json 或 response.function_call_arguments.delta。
工具轮次的结束 在 Chat Completions 接口上结束时为 finish_reason: "tool_calls"，在 Messages 接口上为 stop_reason: "tool_use"。
保活 模型工作期间，每 15 秒发送一次保活：/v1/messages 发送 event: ping，/v1/chat/completions 发送 : ping 注释行。
停止请求 关闭连接会停止流。该轮次本身会运行到结束并被计入用量。

故障排查

现象 原因 解决办法
400，带 unknown model: claude-… 或 unknown model: gpt-… 工具发送了它自己的默认模型名称。只提供已发布的 Shannon id，其他名称不会被映射到任何 id。 选择一个 Shannon id：在 Claude Code 中设置 ANTHROPIC_MODEL 和三个 ANTHROPIC_DEFAULT_…_MODEL 变量，在 Codex 配置中设置 model。
来自 Codex CLI 的 400，带 unknown model: 且没有名称 请求没有指定模型。/v1/responses 需要指定。 在 ~/.codex/config.toml 中设置 model，或传入 --model。
401，带 Missing authentication 或 Invalid API key 密钥没有到达 API，或者它不是当前密钥。Shannon 密钥以 sk- 开头。 检查启动工具的 shell 中是否设置了该变量。从密钥与用量页面重新复制密钥。
每个请求都返回 404 对于该工具，base URL 多了或少了一个 /v1。 Claude Code：使用不带 /v1 的地址。Codex CLI：使用带 /v1 的地址。
429，带 Shannon Coder call quota reached 当前 4 小时窗口内的 Coder 调用次数已用完。 等待下一个窗口，升级到调用次数更多的计划，或选择按 tokens 计数的模型。
429，带 Quota exceeded 你的余额不足以支付该请求。 充值，或等待你的计划的每日额度在 00:00 UTC 刷新。
400，带 prompt is too long 对话超出了模型的上下文窗口。 压缩会话（两个工具中都是 /compact）。告诉工具该模型的上下文窗口，使其更早压缩。
Claude Code 显示的是近似的上下文数字 /v1/messages/count_tokens 对托管开源权重模型计数。对 Shannon id 它会返回 400，Claude Code 会自行估算大小。 无需修复。如需精确计数，请选择托管开源权重模型。
粘贴的截图没有被考虑 shannon-coder-1 接受文本输入。 为该会话选择支持图片的模型。

你的密钥和余额在密钥与用量页面。 密钥与用量