mirror of
https://github.com/NanmiCoder/claude-code-haha.git
synced 2026-10-10 03:43:11 +08:00
程序员阿江(Relakkes)
99 lines
5.3 KiB
Markdown
99 lines
5.3 KiB
Markdown
# 第三方模型
|
||
|
||
Claude Code Haha 可以连接 Anthropic Messages、OpenAI Chat Completions 和 OpenAI Responses 三类接口。对桌面端用户来说，最可靠的入口不是手写环境变量，而是 **设置 → Providers**：应用会保存认证方式、模型映射，并在需要时启动本机协议代理。
|
||
|
||
## 推荐配置流程
|
||
|
||
1. 打开桌面端的 **设置 → Providers**。
|
||
2. 选择内置预设，或新建自定义 Provider。
|
||
3. 填写 Base URL、认证信息和协议格式。
|
||
4. 至少配置主模型；服务商使用不同模型名时，再配置 Haiku、Sonnet 和 Opus 槽位。
|
||
5. 先点击测试，确认认证和模型可用，再激活 Provider。
|
||
6. 新建会话验证工具调用；只返回文本并不代表 Agent 工作流完整可用。
|
||
|
||
激活后，桌面端和由它启动的 CLI 会复用同一份 Provider 配置。不要再把另一套旧密钥写进 `.env` 或 `~/.claude/settings.json`。
|
||
|
||
## 选择正确的协议
|
||
|
||
| Provider 格式 | 上游接口 | 适用场景 |
|
||
|----------------|----------|----------|
|
||
| `anthropic` | Anthropic Messages | 服务商原生兼容 Anthropic 请求与响应 |
|
||
| `openai_chat` | `/v1/chat/completions` | 服务商提供 OpenAI Chat Completions |
|
||
| `openai_responses` | `/v1/responses` | 服务商提供 OpenAI Responses |
|
||
|
||
`anthropic` 会直接请求服务商，不替换协议。`openai_chat` 和 `openai_responses` 会由 Claude Code Haha 在本机启动回环代理，把 Claude Agent 流量转换成所选协议。这个代理只用于当前运行时，不需要把端口手工暴露到局域网。
|
||
|
||
如果提供商同时宣传“OpenAI 兼容”和“Anthropic 兼容”，以它实际实现完整、工具调用稳定的接口为准。不要仅根据 URL 中是否含有 `/v1` 推断协议。
|
||
|
||
## 认证与模型映射
|
||
|
||
认证头由服务商决定：
|
||
|
||
- Anthropic API Key 通常使用 `x-api-key`。
|
||
- Bearer Token 通常使用 `Authorization: Bearer`。
|
||
- OpenAI 兼容服务通常使用 Bearer Token，但私有网关可能不同。
|
||
|
||
模型槽位不是额外下载的模型，而是 Claude Agent 在不同任务中请求的逻辑档位。主模型必须能处理工具调用；其他槽位可以映射到同一个模型，也可以按成本和能力分别配置。某个服务商不支持的槽位可以留空。
|
||
|
||
模型名和服务商能力会持续变化，所以本文不维护一份容易过期的型号清单。请在 Provider 设置页使用服务商当前返回的模型 ID，并通过测试按钮确认。
|
||
|
||
## 内置运行时
|
||
|
||
Claude Code Haha 还提供 Claude、OpenAI 和 Grok 的内置运行时。可用的登录方式取决于当前版本和本机账号状态；按照 Provider 页面显示的授权流程完成登录即可。
|
||
|
||
内置运行时与“自定义兼容接口”是两条路径。已有官方账号时优先使用内置运行时；连接中转服务、自建网关或本地模型时再创建自定义 Provider。
|
||
|
||
## 仅使用 CLI
|
||
|
||
纯 CLI 用户可以直接配置 Anthropic Messages 兼容端点：
|
||
|
||
```bash
|
||
ANTHROPIC_AUTH_TOKEN=sk-example
|
||
ANTHROPIC_BASE_URL=https://provider.example.com/anthropic
|
||
ANTHROPIC_MODEL=provider-model
|
||
./bin/claude-haha
|
||
```
|
||
|
||
这个方式不会自动把 Anthropic 请求转换成 OpenAI 协议。OpenAI Chat Completions 或 Responses 服务应先在桌面端创建 Provider，让应用管理协议代理。完整变量和生效顺序见 [环境变量](./env-vars.md)。
|
||
|
||
Azure OpenAI 使用项目内置的专用 Responses 路径，配置项见 [Azure OpenAI 环境变量](./env-vars.md#azure-openai)。
|
||
|
||
## LiteLLM：进阶兼容层
|
||
|
||
只有在服务商没有可靠的 Anthropic 接口、又无法直接使用 Provider 协议转换时，才需要额外部署 LiteLLM。它会增加一个服务、一次协议转换和一层排查成本。
|
||
|
||
最小示例：
|
||
|
||
```yaml
|
||
model_list:
|
||
- model_name: provider-model
|
||
litellm_params:
|
||
model: openai/provider-model
|
||
api_base: https://provider.example.com/v1
|
||
api_key: os.environ/PROVIDER_API_KEY
|
||
```
|
||
|
||
启动 LiteLLM 后，把它的 Anthropic 兼容地址作为 `anthropic` Provider 接入。部署、鉴权和模型前缀以 [LiteLLM 官方文档](https://docs.litellm.ai/) 为准。
|
||
|
||
## 能力边界
|
||
|
||
第三方模型要稳定运行 Agent 工作流，至少需要：
|
||
|
||
- 正确处理多轮消息、system 内容和工具调用；
|
||
- 保留 tool call ID，并能接收对应的 tool result；
|
||
- 支持足够长的上下文和输出；
|
||
- 在流式模式下发送结构完整、顺序正确的事件。
|
||
|
||
思考模式、effort、Prompt Cache、图像输入和结构化输出是否可用，取决于所选协议、服务商和具体模型，不能统一认定为“支持”或“不支持”。遇到问题时先关闭可选能力，验证最小文本与工具调用，再逐项恢复。
|
||
|
||
## 常见问题
|
||
|
||
| 现象 | 优先检查 |
|
||
|------|----------|
|
||
| `401` / `403` | 认证头类型、Token 权限、Base URL 是否属于同一服务 |
|
||
| `404` | Provider 格式是否选错、Base URL 是否重复包含接口路径 |
|
||
| 模型不存在 | 使用服务商真实模型 ID，不要沿用其他平台的别名 |
|
||
| 一直输出文本但不执行工具 | 模型或网关是否完整支持工具调用 |
|
||
| 切换 Provider 后仍请求旧地址 | 是否同时在 `.env`、`settings.json` 和桌面端保存了配置 |
|
||
| 流式响应中断 | 先关闭可选能力，并检查网关是否改写或缓冲事件流 |
|