#新手图文接入手册

这是一份给 AI 小白看的线性手册。你不需要先理解所有接口概念，只要按顺序完成：注册登录、创建令牌、选择客户端、填写三件套、发送第一条消息、查看日志。

如果你已经会使用 API，可以直接跳到三件套与第一个请求。如果你主要想配置某个客户端，可以直接查看客户端接入总览。

#你会完成什么

#第 0 步：先选一条路线

第一次使用推荐路线：在线调试台 → ChatBox 或 Cherry Studio → 再配置复杂工具。

#第 1 步：登录控制台

1. 打开控制台。
2. 完成登录。
3. 找到钱包、令牌管理、调用日志这几个入口。

图中重点看左侧侧边栏：API 密钥 用来创建和管理 Key，使用日志 用来排查请求是否真正打到平台，钱包 用来确认额度。

成功标志：

• 你能看到账号信息。
• 你能进入令牌管理页面。
• 你能找到调用日志页面。

#第 2 步：确认余额或额度

进入钱包或余额页面，确认账号有可用额度。没有额度时，客户端可能会报余额不足、quota exceeded 或 402。

建议同时看一下控制台里的模型或价格页面，确认你准备测试的模型在当前分组里可用。第一次测试不要选最贵或最慢的模型，先选一个稳定的聊天模型，目标只是证明链路能通。

#第 3 步：创建 API Key

1. 进入令牌管理。
2. 点击新建令牌。

3. 名称写清用途，例如 chatbox-test。
4. 选择分组和额度。

5. 保存后复制 sk-...。

保存后会回到 API 密钥列表。列表里会显示 Key 的打码形式和复制按钮，公开截图时不要露出完整 sk-...。

建议命名：

#第 4 步：理解三件套

把三件套和客户端字段对应起来：

最常见错误：

• Base URL 重复写 /v1。
• Key 少复制字符。
• 模型名按网上教程填，但你的分组不可用。
• Codex、Claude Code 这类工具协议选错。

#第 5 步：先用在线调试台验证

打开在线调试，填写：

成功标志：

• 页面返回模型回复。
• 控制台调用日志出现一条成功请求。

图中 Key 使用打码示例。你实际测试时要填完整 sk-...，发送后以下方返回内容和控制台调用日志作为成功标志。

如果这里失败，先不要配置客户端，去看认证与令牌和常见问题排查。

#第 6 步：选择客户端

完整列表见客户端接入总览。

如果你不知道先选哪个，按这个优先级：

1. ChatBox：字段少，适合验证三件套。
2. Cherry Studio：适合长期聊天和管理多个模型。
3. Codex / Claude Code / CCSwitch / Cline：适合开发者，但要先准备本地环境和协议。
4. Dify / AnythingLLM：适合应用和知识库，通常还要配置 Embedding 模型。

#第 7 步：按系统准备本地环境

如果你只是用网页调试台或桌面聊天客户端，可以跳过本地环境准备。下面这些场景需要：

系统入口：

• Windows：本地环境准备
• macOS：本地环境准备
• Linux：本地环境准备

#第 8 步：Codex 用户特别注意

很多用户本地没有安装 Codex，也没有 Node/npm。按这个顺序：

1. 安装 Git、Node.js / npm。
2. 安装 Codex。
3. 设置 WANMO_API_KEY。
4. 编辑 ~/.codex/config.toml。
5. 先让 Codex 做只读任务。

Codex 页已经按 Windows、macOS、Linux/WSL 写了安装方式：Codex 接入万模API。

如果你准备使用 npm 路线，先确认包名：

node -v
npm -v
npm view @openai/codex version
npm install -g @openai/codex
codex --version

如果 npm view 查不到包或网络失败，改用 Codex 官方安装器路线。

#第 9 步：看调用日志

每次请求后都建议看控制台调用日志。日志能告诉你：

如果客户端报错但日志里没有请求，说明请求没有打到万模API，重点检查客户端地址和网络。

排查问题时，重点看时间、模型、路径、状态码、Tokens 和费用这些列。

#第 10 步：常见错误怎么处理

#新用户最容易漏掉的检查

#快速自查清单

遇到请求失败时，按下面顺序确认：

1. API Key 是完整的 sk-...。
2. OpenAI 客户端 Base URL 是 https://www.wanmoapi.com/v1。
3. 自动补 /v1 的客户端 Base URL 是 https://www.wanmoapi.com。
4. 模型名来自控制台可用列表。
5. 控制台调用日志能看到请求。
6. 如果使用 Codex，协议是 Responses。
7. 如果使用 Claude Code，协议是 Claude Messages。

#下一步

• 跑通最小请求：三件套与第一个请求
• 选择客户端：客户端接入总览
• 统一管理编码 CLI：CCSwitch 接入万模API
• 查看完整接口：接口参考
• 继续排障：常见问题排查