lixin/vitepress
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: 移除死链接，修复构建错误

Browse Source 
- 删除已废弃的 skills 页面（ikuncode-aimcp, ikunimage）
- 删除售后页面并清理所有引用
- 修复 nano-banana.md 中 /skills/oneimage 死链接
- 修复 opencode.md 中损坏的图片路径

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shihao 2026-05-15 18:07:58 +08:00
parent 16c6279484
commit 3afad1525c
29 changed files with 2590 additions and 3728 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.claude/settings.local.json Normal file
View File

@ -0,0 +1,16 @@
{
"permissions": {
"allow": [
"Bash(git init *)",
"Bash(git remote *)",
"Bash(npm run *)",
"Bash(git *)",
"Bash(echo \"exit: $?\")",
"Bash(sed -i 's|\\\\[售后支持\\\\]\\(/support/after-sales\\)|售后支持|g' apidoc/apps/opencode.md apidoc/apps/openclaw.md apidoc/apps/alma.md apidoc/deploy/claude-code.md apidoc/deploy/codex.md apidoc/deploy/gemini-cli.md apidoc/intro/overview.md)",
"Bash(sed -i 's|\\\\[售后支持\\\\]\\(</support/after-sales>\\)|售后支持|g' apidoc/apps/opencode.md apidoc/apps/alma.md apidoc/intro/overview.md)",
"Bash(sed -i 's|\\\\[售前售后\\\\]\\(</support/after-sales>\\)|售前售后|g' apidoc/support/troubleshooting.md apidoc/guide/recharge.md apidoc/intro/welcome.md)",
"Bash(sed -i 's|\\\\[售前售后\\\\]\\(/support/after-sales\\)|售前售后|g' apidoc/support/faq.md)",
"Bash(sed -i 's|- \\\\[售后支持\\\\]\\(/support/after-sales\\)||g' apidoc/apps/cherry-studio.md)"
]
}
}

8
apidoc/.vitepress/config.mts
View File

@ -91,18 +91,10 @@ export default defineConfig({
{ text: 'Claude Code Hub', link: '/tools/claude-code-hub' }, { text: 'Claude Code Hub', link: '/tools/claude-code-hub' },
] ]
}, },
{
text: '技能',
items: [
{ text: 'IkunCode AI MCP', link: '/skills/ikuncode-aimcp' },
{ text: 'IkunImage', link: '/skills/ikunimage' },
]
},
{ {
text: '支持', text: '支持',
items: [ items: [
{ text: 'FAQ', link: '/support/faq' }, { text: 'FAQ', link: '/support/faq' },
{ text: '售后', link: '/support/after-sales' },
{ text: '故障排查', link: '/support/troubleshooting' }, { text: '故障排查', link: '/support/troubleshooting' },
] ]
}, },

321
apidoc/apps/alma.md
View File

@ -1,160 +1,161 @@
# Alma 客户端配置指南
# Alma 客户端配置指南
**功能强大的 AI 编程客户端工具**
**功能强大的 AI 编程客户端工具**
📋 简介
📋 简介
Alma 是一款功能强大且界面精美的 AI 客户端工具，集成了代码编写、终端操作、Git 管理、浏览器等多种功能，为开发者提供完整的 AI 辅助编程体验。
Alma 是一款功能强大且界面精美的 AI 客户端工具，集成了代码编写、终端操作、Git 管理、浏览器等多种功能，为开发者提供完整的 AI 辅助编程体验。
## 🔗 相关链接
## 🔗 相关链接
资源| 地址
---|--- 资源| 地址
Alma 官网| <https://alma.now/> ---|---
Alma 官网| <https://alma.now/>
## ✨ 功能特点
## ✨ 功能特点
Alma 提供以下强大功能：
Alma 提供以下强大功能：
* ✅ **代码编写** ：智能代码生成和补全
* ✅ **终端操作** ：集成终端，直接执行命令 * ✅ **代码编写** ：智能代码生成和补全
* ✅ **Git 管理** ：可视化 Git 操作 * ✅ **终端操作** ：集成终端，直接执行命令
* ✅ **浏览器集成** ：内置浏览器支持 * ✅ **Git 管理** ：可视化 Git 操作
* ✅ **多模型支持** ：支持 Claude、Gemini 等多种模型 * ✅ **浏览器集成** ：内置浏览器支持
* ✅ **自定义供应商** ：可接入自定义 API 提供商 * ✅ **多模型支持** ：支持 Claude、Gemini 等多种模型
* ✅ **自定义供应商** ：可接入自定义 API 提供商
![Alma 功能展示](https://minio.oneinai.com/oneinai/images/docs/alma/alma01.png)
![Alma 功能展示](https://minio.oneinai.com/oneinai/images/docs/alma/alma01.png)
## 🛠️ 安装与配置
## 🛠️ 安装与配置
### 第一步：安装 Alma
### 第一步：安装 Alma
访问 [Alma 官网](<https://alma.now/>) 下载并安装适合你操作系统的版本。
访问 [Alma 官网](<https://alma.now/>) 下载并安装适合你操作系统的版本。
### 第二步：设置中文界面
### 第二步：设置中文界面
为了更好的使用体验，建议将界面设置为中文：
为了更好的使用体验，建议将界面设置为中文：
1. 打开 Alma 应用
2. 进入 **Settins → General → Language** 1. 打开 Alma 应用
3. 选择「中文」 2. 进入 **Settins → General → Language**
4. 点击「保存」 3. 选择「中文」
4. 点击「保存」
![设置中文界面](https://minio.oneinai.com/oneinai/images/docs/alma/alma02.png)
![设置中文界面](https://minio.oneinai.com/oneinai/images/docs/alma/alma03.png) ![设置中文界面](https://minio.oneinai.com/oneinai/images/docs/alma/alma02.png)
![设置中文界面](https://minio.oneinai.com/oneinai/images/docs/alma/alma03.png)
### 第三步：添加 OneinAI 自定义供应商
### 第三步：添加 OneinAI 自定义供应商
**1\. 进入供应商设置**
**1\. 进入供应商设置**
点击 **选择供应商 → Add Custom Provider** （添加自定义提供商）
点击 **选择供应商 → Add Custom Provider** （添加自定义提供商）
![添加供应商](https://minio.oneinai.com/oneinai/images/docs/alma/alma04.png)
![添加供应商](https://minio.oneinai.com/oneinai/images/docs/alma/alma04.png)
**2\. 配置 OneinAI 供应商**
**2\. 配置 OneinAI 供应商**
![添加供应商](https://minio.oneinai.com/oneinai/images/docs/alma/alma05.png)
![添加供应商](https://minio.oneinai.com/oneinai/images/docs/alma/alma05.png)
填写以下信息：
填写以下信息：
* **Provider Name** ：OneinAI（或自定义名称）
* **Base URL** ：`https://api.oneinai.com/v1` * **Provider Name** ：OneinAI（或自定义名称）
* **API Key** ：粘贴你从 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 创建的 API Key * **Base URL** ：`https://api.oneinai.com/v1`
* **API Key** ：粘贴你从 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 创建的 API Key
💡提示
如果需要使用Claude模型，请选择Anthropic然后添加供应商 💡提示
如果需要使用Claude模型，请选择Anthropic然后添加供应商
**3\. 获取可用模型**
**3\. 获取可用模型**
添加完成后，在 OneinAI 供应商界面点击 **Fetch** （获取）按钮，系统会自动获取所有可用模型。
添加完成后，在 OneinAI 供应商界面点击 **Fetch** （获取）按钮，系统会自动获取所有可用模型。
![Fetch 获取模型](https://minio.oneinai.com/oneinai/images/docs/alma/alma06.png)
![Fetch 获取模型](https://minio.oneinai.com/oneinai/images/docs/alma/alma06.png)
选择你需要的模型即可开始使用。
选择你需要的模型即可开始使用。
![使用](https://minio.oneinai.com/oneinai/images/docs/alma/alma07.png)
![使用](https://minio.oneinai.com/oneinai/images/docs/alma/alma07.png)
### 使用技巧
### 使用技巧
**1\. 代码编写**
**1\. 代码编写**
* 描述你的需求，Alma 会生成对应代码
* 支持多文件操作和项目级别的修改 * 描述你的需求，Alma 会生成对应代码
* 可以实时预览和修改生成的代码 * 支持多文件操作和项目级别的修改
* 可以实时预览和修改生成的代码
**2\. 终端操作**
**2\. 终端操作**
* 集成终端直接执行命令
* 支持查看命令执行结果 * 集成终端直接执行命令
* 可以与 AI 互动调试问题 * 支持查看命令执行结果
* 可以与 AI 互动调试问题
**3\. Git 管理**
**3\. Git 管理**
* 可视化查看 Git 状态
* AI 辅助编写提交信息 * 可视化查看 Git 状态
* 支持分支管理和合并操作 * AI 辅助编写提交信息
* 支持分支管理和合并操作
**4\. 文件浏览**
**4\. 文件浏览**
* 浏览项目文件结构
* 快速定位和编辑文件 * 浏览项目文件结构
* 支持文件搜索和过滤 * 快速定位和编辑文件
* 支持文件搜索和过滤
## 🎯 最佳实践
## 🎯 最佳实践
### 1\. 选择合适的模型
### 1\. 选择合适的模型
* **Claude Sonnet** ：适合日常编码任务，速度快
* **Claude Opus** ：适合复杂的架构设计和难题 * **Claude Sonnet** ：适合日常编码任务，速度快
* **Gemini** ：适合需要多模态能力的任务（如图片理解） * **Claude Opus** ：适合复杂的架构设计和难题
* **Gemini** ：适合需要多模态能力的任务（如图片理解）
### 2\. 合理使用上下文
### 2\. 合理使用上下文
* 对于小型项目，可以「全选」所有文件
* 对于大型项目，选择相关的模块和文件 * 对于小型项目，可以「全选」所有文件
* 定期清理不相关的上下文，避免 token 浪费 * 对于大型项目，选择相关的模块和文件
* 定期清理不相关的上下文，避免 token 浪费
### 3\. 充分利用 Alma 的集成功能
### 3\. 充分利用 Alma 的集成功能
* 使用终端功能验证 AI 生成的代码
* 利用 Git 集成管理代码版本 * 使用终端功能验证 AI 生成的代码
* 通过浏览器功能查看文档和参考资料 * 利用 Git 集成管理代码版本
* 通过浏览器功能查看文档和参考资料
## 常见问题
## 常见问题
### 如何切换不同的 API 提供商？
### 如何切换不同的 API 提供商？
在聊天界面顶部的模型选择器中，可以随时切换不同的提供商和模型。
在聊天界面顶部的模型选择器中，可以随时切换不同的提供商和模型。
### 为什么有些模型无法使用？
### 为什么有些模型无法使用？
* 检查对应的 API Key 是否有权限访问该模型
* 确认账户余额是否充足 * 检查对应的 API Key 是否有权限访问该模型
* 查看 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 的令牌组设置 * 确认账户余额是否充足
* 查看 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 的令牌组设置
### Alma 和 Claude Code 有什么区别？
### Alma 和 Claude Code 有什么区别？
特性| Alma| Claude Code
---|---|--- 特性| Alma| Claude Code
界面| 图形化界面| 命令行界面 ---|---|---
适用场景| 全功能开发环境| 终端快速操作 界面| 图形化界面| 命令行界面
集成功能| 终端、Git、浏览器等| 纯命令行工具 适用场景| 全功能开发环境| 终端快速操作
学习曲线| 较低| 较高 集成功能| 终端、Git、浏览器等| 纯命令行工具
学习曲线| 较低| 较高
可以根据具体需求选择使用。
可以根据具体需求选择使用。
### 更多问题
### 更多问题
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。
请查看 [FAQ](</support/faq>)
## ✅ 完成
## ✅ 完成
🎉 **配置完成！现在你可以愉快地使用 Alma 进行 AI 辅助编程了！**
🎉 **配置完成！现在你可以愉快地使用 Alma 进行 AI 辅助编程了！**
记住以下要点：
记住以下要点：
* ✅ 选择「全选」上下文范围
* ✅ 根据任务选择合适的模型 * ✅ 选择「全选」上下文范围
* ✅ 充分利用 Alma 的集成功能 * ✅ 根据任务选择合适的模型
* ✅ 定期检查 API 余额 * ✅ 充分利用 Alma 的集成功能
* ✅ 定期检查 API 余额

351
apidoc/apps/cherry-studio.md
View File

@ -1,268 +1,281 @@
# CherryStudio 配置指南 # CherryStudio 配置指南
**全能的 AI 助手桌面客户端** **全能的 AI 助手桌面客户端**
> **官方网站** ：<https://www.cherry-ai.com/>**下载地址** ：<https://www.cherry-ai.com/download> | 资源 | 地址 |
|------|------|
| 官方网站 | [cherry-ai.com](https://www.cherry-ai.com/) |
| 下载地址 | [cherry-ai.com/download](https://www.cherry-ai.com/download) |
| oneinAI 控制台 | [api.oneinai.com/console/token](https://api.oneinai.com/console/token) |
📋 简介 ## 📋 简介
CherryStudio 是一款功能强大的 AI 助手桌面应用，支持多种主流 AI 模型（Claude、Gemini、GPT 等），为开发者和用户提供统一的 AI 交互界面。本教程将指导你如何配置 CherryStudio 接入 IkunCode 平台。 CherryStudio 是一款功能强大的 AI 助手桌面应用，支持 Claude、Gemini、GPT 等主流 AI 模型，为开发者和用户提供统一的 AI 交互界面。本教程将指导你如何配置 CherryStudio 接入 **oneinAI** 平台。
## ✨ 功能特点 ## ✨ 功能特点
CherryStudio 提供以下强大功能： - ✅ **多模型支持**：Claude、Gemini、GPT 等主流 AI 模型
- ✅ **统一界面**：一个应用管理所有 AI 服务
- ✅ **自定义 API**：支持接入自定义 API 提供商
- ✅ **跨平台**：支持 Windows、macOS、Linux
- ✅ **本地优先**：数据存储在本地，保护隐私
- ✅ **丰富功能**：对话管理、模型切换、参数调整等
* ✅ **多模型支持** ：支持 Claude、Gemini、GPT 等主流 AI 模型 ## 📋 配置快速参考
* ✅ **统一界面** ：一个应用管理所有 AI 服务
* ✅ **自定义 API** ：支持接入自定义 API 提供商
* ✅ **跨平台** ：支持 Windows、macOS、Linux
* ✅ **本地优先** ：数据存储在本地，保护隐私
* ✅ **丰富功能** ：对话管理、模型切换、参数调整等
## 🛠️ 安装步骤 | 模型 | 提供商类型 | API 地址 | 令牌组 |
|------|-----------|---------|--------|
| Claude | `Anthropic` | `https://api.oneinai.com` | Claude 分组 |
| Gemini | `Gemini` | `https://api.oneinai.com/v1beta/models` | Gemini 分组 |
### 第一步：下载安装 CherryStudio ---
1. 访问 [CherryStudio 下载页面](<https://www.cherry-ai.com/download>) ## 🛠️ 安装步骤
2. 根据你的操作系统选择对应的安装包： ### 第一步：下载安装 CherryStudio
* **Windows** ：下载 `.exe` 安装程序 1. 访问 [CherryStudio 下载页面](https://www.cherry-ai.com/download)
* **macOS** ：下载 `.dmg` 镜像文件 2. 根据你的操作系统选择对应的安装包：
* **Linux** ：下载 `.AppImage` 或 `.deb` 包 - **Windows**：下载 `.exe` 安装程序
3. 下载完成后，按照系统提示完成安装 - **macOS**：下载 `.dmg` 镜像文件
- **Linux**：下载 `.AppImage` 或 `.deb` 包
3. 下载完成后，按照系统提示完成安装
💡 macOS 用户注意 > 💡 **macOS 用户注意**
> 如果提示"无法打开，因为它来自身份不明的开发者"，请在系统偏好设置 → 安全性与隐私中允许打开。
如果提示"无法打开，因为它来自身份不明的开发者"，请在系统偏好设置 → 安全性与隐私中允许打开。 ### 第二步：获取 oneinAI API Key
### 第二步：获取 OneinAI API Key 在配置 CherryStudio 之前，需要先从 oneinAI 平台获取 API Key：
在配置 CherryStudio 之前，需要先从 IkunCode 平台获取 API Key： 1. 访问 [oneinAI 控制台](https://api.oneinai.com/console/token)
2. 登录你的账户
3. 根据需要创建对应的令牌组：
- **Claude 模型**：选择 Claude 分组
- **Gemini 模型**：选择 Gemini 分组
4. 保存生成的 API Key（请妥善保管，不要泄露）
1. 访问 [OneinAI 控制台](<https://api.oneinai.com/console/token>) ![创建 API Key](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio01.png)
2. 登录你的账户
3. 根据需要创建对应的令牌组：
* **Claude 模型** ：选择 Claude分组
* **Gemini 模型** ：选择 Gemini分组
![Claude](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio01.png) > ⚠️ Claude 和 Gemini 的 API Key 必须使用**不同的令牌组**，两者不能通用。
4. 保存生成的 API Key ---
📋 配置快速参考 ## 🔧 配置 Claude 模型
模型| 提供商类型| API 地址| 令牌组 ### 第一步：进入设置页面
---|---|---|---
Claude| `Anthropic`| `https://api.oneinai.com/v1/messages`| Claude分组
Gemini| `Gemini`| `https://api.oneinai.com/v1beta/models`| Gemini分组
## 🔧 配置 Claude 模型
### 第一步：进入设置页面 1. 打开 CherryStudio 应用
2. 点击左下角的「设置」或「偏好设置」
3. 选择「模型配置」或「API 配置」选项
1. 打开 CherryStudio 应用 ### 第二步：选择 Claude 模型类型
2. 点击左下角的「设置」或「偏好设置」
3. 选择「模型配置」或「API 配置」选项
### 第二步：选择 Claude 模型类型 ![Claude 类型选择](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio02.png)
![Claude 类型选择](https://docs.ikuncode.cc/images/apps/CherryStudio/claudeleixing.png) 在模型列表中选择你需要的 Claude 模型。
在模型列表中选择你需要的 Claude 模型 ### 第三步：配置 Claude API
### 第三步：配置 Claude API
在 Claude 配置界面中填写以下信息： 在 Claude 配置界面中填写以下信息：
![Claude 配置界面](https://docs.ikuncode.cc/images/apps/CherryStudio/claude.png) ![Claude 配置界面](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio03.png)
**配置参数** ： **配置参数：**
* **提供商类型** ：选择 `Anthropic` | 字段 | 填写内容 |
* **API 地址** ：`https://api.oneinai.com` |------|---------|
* **API Key** ：粘贴你从 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 获取的 Claude API Key | 提供商类型 | `Anthropic` |
* **模型名称** ：输入上一步选择的模型名称（如 `claude-sonnet-4-6`） | API 地址 | `https://api.oneinai.com` |
| API Key | 从 [oneinAI 控制台](https://api.oneinai.com/console/token) 获取的 Claude API Key |
| 模型名称 | 例如 `claude-sonnet-4-6`、`claude-opus-4-5-20251101` |
## 🔧 配置 Gemini 模型 ---
### 第一步：选择 Gemini 模型类型 ## 🔧 配置 Gemini 模型
![Gemini 类型选择](https://docs.ikuncode.cc/images/apps/CherryStudio/geminileixing.png) ### 第一步：选择 Gemini 模型类型
![Gemini 类型选择](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio04.png)
在模型列表中选择你需要的 Gemini 模型： 在模型列表中选择你需要的 Gemini 模型：
* **Gemini 3 Flash Preview** ：`gemini-3-flash-preview` \- 最新版本，速度快，性能优秀（推荐） - **Gemini 3 Flash Preview**：`gemini-3-flash-preview` — 最新版本，速度快，性能优秀（推荐）
* **Gemini 3 Pro Preview** ：`gemini-3-pro-preview` \- 高性能，适合复杂任务 - **Gemini 3 Pro Preview**：`gemini-3-pro-preview` — 高性能，适合复杂任务
* **Gemini 2.0 Flash** ：快速响应，适合简单对话 - **Gemini 2.0 Flash**：快速响应，适合简单对话
⚠️ 注意 ### 第二步：配置 Gemini API
* Gemini 和 Claude 需要使用不同的 API Key（不同的令牌组）
* 确保你在 IkunCode 平台创建了对应的令牌组
### 第二步：配置 Gemini API
在 Gemini 配置界面中填写以下信息： 在 Gemini 配置界面中填写以下信息：
![Gemini 配置界面](https://docs.ikuncode.cc/images/apps/CherryStudio/gemini.png) ![Gemini 配置界面](https://minio.oneinai.com/oneinai/images/docs/cherrystudio/cherrystudio05.png)
**配置参数** ： **配置参数：**
* **提供商类型** ：选择 `Gemini` | 字段 | 填写内容 |
* **API 地址** ：`https://api.oneinai.com/v1beta/models` |------|---------|
* **API Key** ：粘贴你从 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 获取的 Gemini API Key | 提供商类型 | `Gemini` |
* **模型名称** ：输入上一步选择的模型名称（如 `gemini-3-flash-preview`） | API 地址 | `https://api.oneinai.com/v1beta/models` |
| API Key | 从 [oneinAI 控制台](https://api.oneinai.com/console/token) 获取的 Gemini API Key |
| 模型名称 | 例如 `gemini-3-flash-preview` |
## 💬 开始使用 > ⚠️ **注意**：Gemini 和 Claude 需要使用不同的 API Key（不同的令牌组），确保你在 oneinAI 平台已创建对应的令牌组。
### 创建新对话 ---
1. 点击「新建对话」或「New Chat」按钮 ## 💬 开始使用
2. 在模型选择器中选择已配置的模型
3. 开始与 AI 对话
### 切换模型 ### 创建新对话
1. 点击「新建对话」或「New Chat」按钮
2. 在模型选择器中选择已配置的模型
3. 开始与 AI 对话
### 切换模型
在对话过程中，你可以随时切换不同的模型： 在对话过程中，你可以随时切换不同的模型：
1. 点击顶部的模型选择器 1. 点击顶部的模型选择器
2. 选择其他已配置的模型 2. 选择其他已配置的模型
3. 继续对话（上下文可能会保留或重置，取决于应用设置） 3. 继续对话（上下文可能会保留或重置，取决于应用设置）
### 调整参数 ### 调整参数
CherryStudio 通常支持调整以下参数： CherryStudio 通常支持调整以下参数：
* **Temperature** （温度）：控制回复的随机性（0-1） - **Temperature**（温度）：控制回复的随机性（0-1）
* **Max Tokens** （最大令牌数）：控制回复长度 - **Max Tokens**（最大令牌数）：控制回复长度
* **Top P** ：控制采样范围 - **Top P**：控制采样范围
💡 参数建议 > 💡 **参数建议**
> - 编程任务：Temperature `0.2-0.5`（更准确）
> - 创意写作：Temperature `0.7-0.9`（更有创意）
> - 日常对话：Temperature `0.5-0.7`（平衡）
* 编程任务：Temperature 0.2-0.5（更准确） ---
* 创意写作：Temperature 0.7-0.9（更有创意）
* 日常对话：Temperature 0.5-0.7（平衡）
## 🎯 最佳实践 ## 🎯 最佳实践
### 1\. 合理选择模型 ### 1. 合理选择模型
不同任务使用不同模型： 不同任务使用不同模型：
* **代码编写** ：Claude Sonnet 4.5（`claude-sonnet-4-5-20250929`） | 任务类型 | 推荐模型 | 模型标识 |
* **快速对话** ：Gemini 3 Flash Preview（`gemini-3-flash-preview`） |---------|---------|---------|
* **复杂推理** ：Claude Opus 4.5（`claude-opus-4-5-20251101`） | 代码编写 | Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929` |
* **多模态任务** ：Gemini 3 Pro Preview（支持图片） | 快速对话 | Gemini 3 Flash Preview | `gemini-3-flash-preview` |
| 复杂推理 | Claude Opus 4.5 | `claude-opus-4-5-20251101` |
| 多模态（图片） | Gemini 3 Pro Preview | `gemini-3-pro-preview` |
### 2\. 管理 API 使用 ### 2. 管理 API 使用
* 定期检查 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 的余额 - 定期检查 [oneinAI 控制台](https://api.oneinai.com/console/token) 的余额
* 为不同用途创建不同的 API Key - 为不同用途创建不同的 API Key，便于管理和审计
* 避免在公共场合泄露 API Key - 避免在公共场合或代码仓库中泄露 API Key
### 3\. 优化对话体验 ### 3. 优化对话体验
* 使用清晰的提示词 - 使用清晰、具体的提示词
* 合理设置上下文长度 - 合理设置上下文长度，避免过长影响响应速度
* 善用对话历史管理功能 - 善用对话历史管理功能，及时归档或清理
## 🔍 与其他客户端的对比 ---
特性| CherryStudio| Alma| Hapi ## 🔍 与其他客户端的对比
---|---|---|---
界面类型| 桌面应用| 桌面应用| Web/PWA
多模型支持| ✅| ✅| ✅
代码编辑| 部分支持| ✅| ✅
终端集成| ❌| ✅| ✅
远程访问| ❌| ❌| ✅
学习曲线| 低| 中| 中
**选择建议** ：
* **纯对话需求** ：CherryStudio（界面简洁，易上手） | 特性 | CherryStudio | Alma | Hapi |
* **编程开发** ：Alma 或 Hapi（功能更强大） |------|:------------:|:----:|:----:|
* **远程控制** ：Hapi（独有功能） | 界面类型 | 桌面应用 | 桌面应用 | Web/PWA |
| 多模型支持 | ✅ | ✅ | ✅ |
| 代码编辑 | 部分支持 | ✅ | ✅ |
| 终端集成 | ❌ | ✅ | ✅ |
| 远程访问 | ❌ | ❌ | ✅ |
| 学习曲线 | 低 | 中 | 中 |
## 常见问题 **选择建议：**
### 提示 API Key 无效？ - **纯对话需求**：CherryStudio（界面简洁，易上手）
- **编程开发**：Alma 或 Hapi（功能更强大）
- **远程控制**：Hapi（独有功能）
**可能原因** ： ---
* API Key 输入错误 ## ❓ 常见问题
* 令牌组选择错误（只允许逆向分组的 Key 不能用于 Gemini）
* 余额不足
**解决方法** ： ### 提示 API Key 无效？
1. 检查 API Key 是否完整复制 **可能原因：**
2. 确认在 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 创建了正确的令牌组（Claude 用 只允许逆向分组，Gemini 用 gemini分组）
3. 查看账户余额是否充足
### 模型列表为空？ - API Key 输入错误或前后有空格
- 令牌组选择错误（Claude 的 Key 不能用于 Gemini，反之亦然）
- 账户余额不足
**可能原因** ： **解决方法：**
* Base URL 配置错误 1. 重新复制 API Key，确保完整且无多余空格
* 网络连接问题 2. 在 [oneinAI 控制台](https://api.oneinai.com/console/token) 确认创建了正确的令牌组
* API Key 权限不足 3. 查看账户余额是否充足
**解决方法** ： ### 模型列表为空？
1. 确认 Claude 的 API 地址为 `https://api.oneinai.com/v1/messages` **可能原因：**
2. 确认 Gemini 的 API 地址为 `https://api.oneinai.com/v1beta/models`
3. 检查网络连接
4. 重新获取 API Key 并确保令牌组权限正确
### 对话响应速度慢？ - Base URL 配置错误
- 网络连接问题
- API Key 权限不足
**可能原因** ： **解决方法：**
* 网络延迟 1. 确认 Claude 的 API 地址为 `https://api.oneinai.com`
* 选择的模型较大 2. 确认 Gemini 的 API 地址为 `https://api.oneinai.com/v1beta/models`
* 上下文过长 3. 检查网络连接是否正常
4. 重新获取 API Key 并确认令牌组权限正确
**解决方法** ： ### 对话响应速度慢？
1. 检查网络连接质量 **可能原因：**
2. 尝试使用更快的模型（如 Gemini Flash）
3. 清理或减少对话历史
### 如何同时使用多个模型？ - 网络延迟
- 选择的模型较大（如 Opus 系列）
- 上下文过长
在 CherryStudio 中： **解决方法：**
1. 分别配置不同的模型提供商 1. 检查网络连接质量
2. 在新建对话时选择对应的模型 2. 尝试使用更快的模型（如 Gemini Flash 或 Claude Haiku）
3. 可以创建多个对话窗口，每个使用不同模型 3. 清理或缩短对话历史
### 更多问题 ### 如何同时使用多个模型？
请查看： 1. 在设置中分别配置不同的模型提供商
2. 在新建对话时选择对应的模型
3. 也可以创建多个对话窗口，每个使用不同模型
* [IkunCode 控制台](<https://api.oneinai.com/console/token>) ### 更多问题
* [IkunCode FAQ](</support/faq>)
* [售后支持](</support/after-sales>)
* [CherryStudio 官方文档](<https://www.cherry-ai.com/>)
## ✅ 完成 - [oneinAI 控制台](https://api.oneinai.com/console/token)
- [oneinAI FAQ](/support/faq)
- [CherryStudio 官方文档](https://www.cherry-ai.com/)
---
## ✅ 完成
🎉 **配置完成！现在你可以使用 CherryStudio 愉快地与 AI 对话了！** 🎉 **配置完成！现在你可以使用 CherryStudio 愉快地与 AI 对话了！**
记住以下要点： **核心要点回顾：**
* ✅ 不同模型使用不同的 API Key（不同令牌组） - ✅ Claude 与 Gemini 必须使用**不同的 API Key**（不同令牌组）
* ✅ Claude API 地址：`https://api.oneinai.com/v1/messages` - ✅ Claude API 地址：`https://api.oneinai.com`
* ✅ Gemini API 地址：`https://api.oneinai.com/v1beta/models` - ✅ Gemini API 地址：`https://api.oneinai.com/v1beta/models`
* ✅ 根据任务选择合适的模型 - ✅ 根据任务特性选择合适的模型
* ✅ 定期检查 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 的余额 - ✅ 定期检查 [oneinAI 控制台](https://api.oneinai.com/console/token) 的余额
* ✅ 妥善保管你的 API Key - ✅ 妥善保管你的 API Key，避免泄露
* * * ---
**相关教程** ： **相关教程：**
* [Alma 客户端配置](</apps/alma>) - [Alma 客户端配置](/apps/alma)
* [Hapi 远程控制](</apps/hapi>) - [Hapi 远程控制](/apps/hapi)
* [IkunCode 控制台](<https://api.oneinai.com/console/token>) - [oneinAI 控制台](https://api.oneinai.com/console/token)

650
apidoc/apps/hapi-advanced.md
View File

@ -1,325 +1,325 @@
# Hapi 进阶配置：Cloudflare 优选 IP 高速穿透 # Hapi 进阶配置：Cloudflare 优选 IP 高速穿透
**没有公网 IP？使用 Cloudflare 优选 IP，打造高速内网穿透通道** **没有公网 IP？使用 Cloudflare 优选 IP，打造高速内网穿透通道**
> **适用场景** ：已配置 Cloudflare Tunnel，但访问速度慢、延迟高 **解决方案** ：利用 Cloudflare for SaaS + 优选 IP 服务，绕过拥堵节点 **前置要求** ：已完成 [Hapi 基础配置](</apps/hapi>)，拥有两个域名 > **适用场景** ：已配置 Cloudflare Tunnel，但访问速度慢、延迟高 **解决方案** ：利用 Cloudflare for SaaS + 优选 IP 服务，绕过拥堵节点 **前置要求** ：已完成 [Hapi 基础配置](</apps/hapi>)，拥有两个域名
## 📺 视频教程 ## 📺 视频教程
推荐观看 推荐观看
[没有公网IP？cloudflare优选IP，高速内网穿透 - 哔哩哔哩](<https://www.bilibili.com/video/BV1PPy6YzE5C>) [没有公网IP？cloudflare优选IP，高速内网穿透 - 哔哩哔哩](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
视频详细演示了完整的配置过程，强烈建议先观看视频再进行操作。 视频详细演示了完整的配置过程，强烈建议先观看视频再进行操作。
## 🎯 你正在解决什么问题？ ## 🎯 你正在解决什么问题？
### 默认 Tunnel 的痛点 ### 默认 Tunnel 的痛点
当你直接使用 Cloudflare Tunnel 绑定域名时： 当你直接使用 Cloudflare Tunnel 绑定域名时：
* ❌ Cloudflare 分配的 Anycast IP 在国内可能被绕路（绕到美国、欧洲） * ❌ Cloudflare 分配的 Anycast IP 在国内可能被绕路（绕到美国、欧洲）
* ❌ 运营商 QoS 限速，访问速度慢 * ❌ 运营商 QoS 限速，访问速度慢
* ❌ 延迟高达几百毫秒，严重影响使用体验 * ❌ 延迟高达几百毫秒，严重影响使用体验
![优选 IP 前的访问速度](https://docs.ikuncode.cc/images/apps/hapi/%E4%BC%98%E9%80%89%E5%89%8D.png) ![优选 IP 前的访问速度](https://minio.oneinai.com/oneinai/images/docs/hapi-advanced/hapi-advanced01.png)
### 优选 IP 方案的优势 ### 优选 IP 方案的优势
通过本教程的配置： 通过本教程的配置：
* ✅ 强制流量走对国内网络友好的节点（香港、新加坡等） * ✅ 强制流量走对国内网络友好的节点（香港、新加坡等）
* ✅ 大幅提升访问速度，延迟降低到几十毫秒 * ✅ 大幅提升访问速度，延迟降低到几十毫秒
* ✅ 完全免费，利用 Cloudflare 企业级功能 * ✅ 完全免费，利用 Cloudflare 企业级功能
* ✅ 稳定性高，自动切换最优路由 * ✅ 稳定性高，自动切换最优路由
![优选 IP 后的访问速度](https://docs.ikuncode.cc/images/apps/hapi/%E4%BC%98%E9%80%89%E5%90%8E.png) ![优选 IP 后的访问速度](https://minio.oneinai.com/oneinai/images/docs/hapi-advanced/hapi-advanced0.png)
🚀 速度提升对比 🚀 速度提升对比
从上面两张图可以看到，优选 IP 后访问速度得到了**显著提升** ，延迟从几百毫秒降低到几十毫秒，页面加载也更加流畅！ 从上面两张图可以看到，优选 IP 后访问速度得到了**显著提升** ，延迟从几百毫秒降低到几十毫秒，页面加载也更加流畅！
## 🔍 原理解析 ## 🔍 原理解析
### 流量走向链路 ### 流量走向链路
当用户访问你的域名时，流量是这样流转的： 当用户访问你的域名时，流量是这样流转的：
用户浏览器 用户浏览器
↓ ↓
DNS 解析：hapi.justdo.xin DNS 解析：hapi.justdo.xin
↓ ↓
CNAME → cdn.ttdk.fun CNAME → cdn.ttdk.fun
↓ ↓
CNAME → isp.qzz.io（优选 IP 调度器） CNAME → isp.qzz.io（优选 IP 调度器）
↓ ↓
返回最优 Cloudflare IP（根据用户运营商） 返回最优 Cloudflare IP（根据用户运营商）
↓ ↓
Cloudflare 边缘节点（通过 Host Header 识别） Cloudflare 边缘节点（通过 Host Header 识别）
↓ ↓
SaaS 路由：hapi.justdo.xin → hapi.ttdk.fun SaaS 路由：hapi.justdo.xin → hapi.ttdk.fun
↓ ↓
Cloudflare Tunnel（加密隧道） Cloudflare Tunnel（加密隧道）
↓ ↓
你的本地服务器 localhost:3006 你的本地服务器 localhost:3006
1 1
2 2
3 3
4 4
5 5
6 6
7 7
8 8
9 9
10 10
11 11
12 12
13 13
14 14
15 15
16 16
17 17
💡 提示 💡 提示
[isp.qzz.io](<https://isp.qzz.io/>) 在这里充当"智能交警"的角色，根据你的网络环境自动选择最优路线。 [isp.qzz.io](<https://isp.qzz.io/>) 在这里充当"智能交警"的角色，根据你的网络环境自动选择最优路线。
### 核心技术要点 ### 核心技术要点
1. **优选 IP 调度器** ：[isp.qzz.io](<https://isp.qzz.io/>) 会根据用户的网络环境（电信/联通/移动），返回当前速度最快、延迟最低的 Cloudflare 官方 CDN 节点 IP 1. **优选 IP 调度器** ：[isp.qzz.io](<https://isp.qzz.io/>) 会根据用户的网络环境（电信/联通/移动），返回当前速度最快、延迟最低的 Cloudflare 官方 CDN 节点 IP
2. **Cloudflare for SaaS** ：通过 Custom Hostnames 功能，把"访问域名"和"隧道域名"解耦，实现"走优选 IP 进隧道" 2. **Cloudflare for SaaS** ：通过 Custom Hostnames 功能，把"访问域名"和"隧道域名"解耦，实现"走优选 IP 进隧道"
3. **DNS 链式解析** ：通过 CNAME 链，把用户请求引导到优选 IP，同时保持 Cloudflare 对域名的正确识别 3. **DNS 链式解析** ：通过 CNAME 链，把用户请求引导到优选 IP，同时保持 Cloudflare 对域名的正确识别
💡 关于优选 IP 调度器 💡 关于优选 IP 调度器
[isp.qzz.io](<https://isp.qzz.io/>) 是一个社区维护的 Cloudflare 优选 IP 调度服务，它会自动测速并返回对你当前网络环境最优的 Cloudflare CDN 节点。访问该网站可以查看更多信息和使用说明。 [isp.qzz.io](<https://isp.qzz.io/>) 是一个社区维护的 Cloudflare 优选 IP 调度服务，它会自动测速并返回对你当前网络环境最优的 Cloudflare CDN 节点。访问该网站可以查看更多信息和使用说明。
## 🛠️ 配置步骤 ## 🛠️ 配置步骤
### 前置准备 ### 前置准备
你需要准备： 你需要准备：
1. **主力域名** ：用于展示给用户访问（例如：`hapi.justdo.xin`） 1. **主力域名** ：用于展示给用户访问（例如：`hapi.justdo.xin`）
2. **辅助域名** ：用于承载 Cloudflare Tunnel（例如：`ttdk.fun`） 2. **辅助域名** ：用于承载 Cloudflare Tunnel（例如：`ttdk.fun`）
3. 两个域名都需要托管在 Cloudflare 3. 两个域名都需要托管在 Cloudflare
⚠️ 重要说明 ⚠️ 重要说明
* 主力域名和辅助域名**不能是同一个域名** * 主力域名和辅助域名**不能是同一个域名**
* 辅助域名需要是你自己拥有的，不能用别人的 * 辅助域名需要是你自己拥有的，不能用别人的
* 两个域名都必须在 Cloudflare 上管理 * 两个域名都必须在 Cloudflare 上管理
### 第一步：配置 Cloudflare Tunnel（辅助域名） ### 第一步：配置 Cloudflare Tunnel（辅助域名）
在辅助域名（例如 `ttdk.fun`）上设置 Tunnel： 在辅助域名（例如 `ttdk.fun`）上设置 Tunnel：
1. 登录 Cloudflare，选择辅助域名 1. 登录 Cloudflare，选择辅助域名
2. 进入 **Zero Trust → Access → Tunnels** 2. 进入 **Zero Trust → Access → Tunnels**
3. 创建隧道并安装 cloudflared 3. 创建隧道并安装 cloudflared
4. 配置公共主机名： 4. 配置公共主机名：
* **子域名** ：`hapi` * **子域名** ：`hapi`
* **域名** ：`ttdk.fun` * **域名** ：`ttdk.fun`
* **服务** ：`http://localhost:3006` * **服务** ：`http://localhost:3006`
完成后你应该能通过 `hapi.ttdk.fun` 访问你的 Hapi 服务。 完成后你应该能通过 `hapi.ttdk.fun` 访问你的 Hapi 服务。
### 第二步：启用 Cloudflare for SaaS（辅助域名） ### 第二步：启用 Cloudflare for SaaS（辅助域名）
在辅助域名（`ttdk.fun`）上启用 SaaS 功能： 在辅助域名（`ttdk.fun`）上启用 SaaS 功能：
1. 进入 Cloudflare 控制台 1. 进入 Cloudflare 控制台
2. 选择 `ttdk.fun` 域名 2. 选择 `ttdk.fun` 域名
3. 进入 **SSL/TLS → Custom Hostnames** 3. 进入 **SSL/TLS → Custom Hostnames**
4. 点击 **Add Custom Hostname** 4. 点击 **Add Custom Hostname**
5. 填写： 5. 填写：
* **Custom Hostname** ：`hapi.justdo.xin`（主力域名） * **Custom Hostname** ：`hapi.justdo.xin`（主力域名）
* **Wildcard** ：不勾选 * **Wildcard** ：不勾选
6. 点击 **Add Custom Hostname** 6. 点击 **Add Custom Hostname**
💡 提示 💡 提示
添加后会生成 2 条 TXT 验证记录，先不着急配置，继续下一步。 添加后会生成 2 条 TXT 验证记录，先不着急配置，继续下一步。
### 第三步：配置 DNS 解析（主力域名） ### 第三步：配置 DNS 解析（主力域名）
在主力域名（`justdo.xin`）的 DNS 设置中添加以下记录： 在主力域名（`justdo.xin`）的 DNS 设置中添加以下记录：
#### 3.1 添加 SSL 验证记录 #### 3.1 添加 SSL 验证记录
从第二步中复制 Cloudflare 生成的 2 条 TXT 记录，添加到主力域名的 DNS： 从第二步中复制 Cloudflare 生成的 2 条 TXT 记录，添加到主力域名的 DNS：
类型| 名称| 内容| 代理状态 类型| 名称| 内容| 代理状态
---|---|---|--- ---|---|---|---
TXT| `_acme-challenge.hapi`| `xxxxxxxxxx`（从 SaaS 页面复制）| 仅限 DNS TXT| `_acme-challenge.hapi`| `xxxxxxxxxx`（从 SaaS 页面复制）| 仅限 DNS
TXT| `_acme-challenge.hapi`| `yyyyyyyyyy`（从 SaaS 页面复制）| 仅限 DNS TXT| `_acme-challenge.hapi`| `yyyyyyyyyy`（从 SaaS 页面复制）| 仅限 DNS
#### 3.2 添加 CNAME 记录 #### 3.2 添加 CNAME 记录
类型| 名称| 目标| 代理状态 类型| 名称| 目标| 代理状态
---|---|---|--- ---|---|---|---
CNAME| `cdn`| `isp.qzz.io`| 仅限 DNS ⚠️ CNAME| `cdn`| `isp.qzz.io`| 仅限 DNS ⚠️
CNAME| `hapi`| `cdn.justdo.xin`| 仅限 DNS ⚠️ CNAME| `hapi`| `cdn.justdo.xin`| 仅限 DNS ⚠️
🚨 关键配置 🚨 关键配置
**必须关闭小黄云（代理状态设为 "仅限 DNS"）！** **必须关闭小黄云（代理状态设为 "仅限 DNS"）！**
如果开启代理，会导致 DNS 解析链中断，无法触发优选 IP。 如果开启代理，会导致 DNS 解析链中断，无法触发优选 IP。
### 第四步：配置回退源（辅助域名） ### 第四步：配置回退源（辅助域名）
在辅助域名（`ttdk.fun`）的 DNS 设置中： 在辅助域名（`ttdk.fun`）的 DNS 设置中：
类型| 名称| 目标| 代理状态 类型| 名称| 目标| 代理状态
---|---|---|--- ---|---|---|---
CNAME| `hapi`| `[你的隧道ID].cfargotunnel.com`| 已代理 ✅ CNAME| `hapi`| `[你的隧道ID].cfargotunnel.com`| 已代理 ✅
💡 提示 💡 提示
这条记录通常在创建 Tunnel 时自动生成。确保小黄云是**开启** 状态（已代理）。 这条记录通常在创建 Tunnel 时自动生成。确保小黄云是**开启** 状态（已代理）。
### 第五步：等待 SSL 证书生效 ### 第五步：等待 SSL 证书生效
1. 回到辅助域名的 **SSL/TLS → Custom Hostnames** 页面 1. 回到辅助域名的 **SSL/TLS → Custom Hostnames** 页面
2. 查看 `hapi.justdo.xin` 的状态 2. 查看 `hapi.justdo.xin` 的状态
3. 等待几分钟，状态变为 **Active（有效）** 即表示配置成功 3. 等待几分钟，状态变为 **Active（有效）** 即表示配置成功
⏳ 耐心等待 ⏳ 耐心等待
SSL 证书签发通常需要 5-15 分钟，请耐心等待。如果超过 30 分钟仍未生效，检查 TXT 记录是否正确添加。 SSL 证书签发通常需要 5-15 分钟，请耐心等待。如果超过 30 分钟仍未生效，检查 TXT 记录是否正确添加。
## ✅ 验证配置 ## ✅ 验证配置
### 测试访问 ### 测试访问
在浏览器中访问：`https://hapi.justdo.xin` 在浏览器中访问：`https://hapi.justdo.xin`
如果能正常打开 Hapi 界面，说明配置成功！ 如果能正常打开 Hapi 界面，说明配置成功！
### 测试速度提升 ### 测试速度提升
使用 ping 或测速工具对比： 使用 ping 或测速工具对比：
**优化前** ： **优化前** ：
bash bash
ping hapi.ttdk.fun ping hapi.ttdk.fun
# 延迟通常 200-500ms # 延迟通常 200-500ms
1 1
2 2
**优化后** ： **优化后** ：
bash bash
ping hapi.justdo.xin ping hapi.justdo.xin
# 延迟通常 20-100ms # 延迟通常 20-100ms
1 1
2 2
## 🎓 角色分配总结 ## 🎓 角色分配总结
角色| 域名示例| 作用 角色| 域名示例| 作用
---|---|--- ---|---|---
**主力域名**| `hapi.justdo.xin`| 你最终展示给用户访问的地址 **主力域名**| `hapi.justdo.xin`| 你最终展示给用户访问的地址
**辅助域名**| `hapi.ttdk.fun`| 承载 Tunnel 的"回退源"，用户不直接感知 **辅助域名**| `hapi.ttdk.fun`| 承载 Tunnel 的"回退源"，用户不直接感知
**优选 IP 调度器**| [isp.qzz.io](<https://isp.qzz.io/>)| 像"交警"，告诉流量该走哪条不堵的路 **优选 IP 调度器**| [isp.qzz.io](<https://isp.qzz.io/>)| 像"交警"，告诉流量该走哪条不堵的路
**中转域名**| `cdn.justdo.xin`| 作为跳板，把主力域名引向优选 IP 池 **中转域名**| `cdn.justdo.xin`| 作为跳板，把主力域名引向优选 IP 池
## 🔧 故障排查 ## 🔧 故障排查
### SSL 证书一直显示 Pending？ ### SSL 证书一直显示 Pending？
**可能原因** ： **可能原因** ：
* TXT 记录添加错误或未生效 * TXT 记录添加错误或未生效
* DNS 传播未完成 * DNS 传播未完成
**解决方法** ： **解决方法** ：
1. 使用 [DNS 检查工具](<https://dnschecker.org/>) 验证 TXT 记录 1. 使用 [DNS 检查工具](<https://dnschecker.org/>) 验证 TXT 记录
2. 等待 DNS 全球传播（最多 24 小时） 2. 等待 DNS 全球传播（最多 24 小时）
3. 重新添加 Custom Hostname 3. 重新添加 Custom Hostname
### 访问显示 526 错误？ ### 访问显示 526 错误？
**可能原因** ： **可能原因** ：
* 辅助域名的 `hapi` 记录未开启代理（小黄云） * 辅助域名的 `hapi` 记录未开启代理（小黄云）
* Tunnel 未正确配置 * Tunnel 未正确配置
**解决方法** ： **解决方法** ：
1. 确保 `hapi.ttdk.fun` 的小黄云是**开启** 状态 1. 确保 `hapi.ttdk.fun` 的小黄云是**开启** 状态
2. 检查 Tunnel 是否正常运行 2. 检查 Tunnel 是否正常运行
### 访问仍然很慢？ ### 访问仍然很慢？
**可能原因** ： **可能原因** ：
* 主力域名的 CNAME 记录开启了代理 * 主力域名的 CNAME 记录开启了代理
* DNS 解析链断裂 * DNS 解析链断裂
**解决方法** ： **解决方法** ：
1. 确保 `hapi.justdo.xin` 和 `cdn.justdo.xin` 的小黄云都是**关闭** 状态 1. 确保 `hapi.justdo.xin` 和 `cdn.justdo.xin` 的小黄云都是**关闭** 状态
2. 使用 `nslookup` 检查 DNS 解析链是否完整 2. 使用 `nslookup` 检查 DNS 解析链是否完整
## 🚀 进阶优化 ## 🚀 进阶优化
### 自建优选 IP 服务 ### 自建优选 IP 服务
如果你追求极致稳定，可以： 如果你追求极致稳定，可以：
1. 使用 CloudflareSpeedTest 工具本地测速 1. 使用 CloudflareSpeedTest 工具本地测速
2. 手动选择最优 IP 2. 手动选择最优 IP
3. 创建自己的优选域名，替代 `isp.qzz.io` 3. 创建自己的优选域名，替代 `isp.qzz.io`
### 多运营商优化 ### 多运营商优化
可以针对不同运营商配置不同的优选路径： 可以针对不同运营商配置不同的优选路径：
* 电信用户：`cdn-ct.yourdomain.com` * 电信用户：`cdn-ct.yourdomain.com`
* 联通用户：`cdn-cu.yourdomain.com` * 联通用户：`cdn-cu.yourdomain.com`
* 移动用户：`cdn-cm.yourdomain.com` * 移动用户：`cdn-cm.yourdomain.com`
通过 DNS 智能解析（GeoDNS），根据用户运营商返回不同的 CNAME 记录。 通过 DNS 智能解析（GeoDNS），根据用户运营商返回不同的 CNAME 记录。
## 📚 相关资源 ## 📚 相关资源
* [Cloudflare for SaaS 官方文档](<https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/>) * [Cloudflare for SaaS 官方文档](<https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/>)
* [Cloudflare Tunnel 文档](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/>) * [Cloudflare Tunnel 文档](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/>)
* [isp.qzz.io - 优选 IP 调度器](<https://isp.qzz.io/>) * [isp.qzz.io - 优选 IP 调度器](<https://isp.qzz.io/>)
* [视频教程：cloudflare优选IP配置](<https://www.bilibili.com/video/BV1PPy6YzE5C>) * [视频教程：cloudflare优选IP配置](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
## ⚠️ 安全提醒 ## ⚠️ 安全提醒
1. 不要泄露你的 Tunnel 令牌 1. 不要泄露你的 Tunnel 令牌
2. 定期检查 Custom Hostnames 配置 2. 定期检查 Custom Hostnames 配置
3. [isp.qzz.io](<https://isp.qzz.io/>) 是社区维护的优选 IP 服务，虽然可靠但非官方服务，你也可以选择自建优选服务 3. [isp.qzz.io](<https://isp.qzz.io/>) 是社区维护的优选 IP 服务，虽然可靠但非官方服务，你也可以选择自建优选服务
4. 建议配合 Cloudflare Access 限制访问来源 4. 建议配合 Cloudflare Access 限制访问来源
## 💡 总结 ## 💡 总结
通过这套配置，你： 通过这套配置，你：
* ✅ 不花一分钱 * ✅ 不花一分钱
* ✅ 利用 Cloudflare 企业级 SaaS 功能 * ✅ 利用 Cloudflare 企业级 SaaS 功能
* ✅ 把原本几百毫秒延迟的内网穿透，优化到接近直连的体验 * ✅ 把原本几百毫秒延迟的内网穿透，优化到接近直连的体验
* ✅ 打造了一条"高速内网穿透通道" * ✅ 打造了一条"高速内网穿透通道"
这就是目前免费方案中，提升 Cloudflare 内网穿透速度的**天花板级别配置** ！ 这就是目前免费方案中，提升 Cloudflare 内网穿透速度的**天花板级别配置** ！
* * * * * *
**下一步** ：配置完成后，你可以愉快地在任何地方高速访问你的 Hapi 服务了！🎉 **下一步** ：配置完成后，你可以愉快地在任何地方高速访问你的 Hapi 服务了！🎉

394
apidoc/apps/hapi.md
View File

@ -1,197 +1,197 @@
# Hapi 远程控制配置指南 # Hapi 远程控制配置指南
**随时随地远程控制你的 AI 编程助手** **随时随地远程控制你的 AI 编程助手**
> **作者** ：[weishu](<https://github.com/tiann>)**官方文档** ：<https://hapi.run/> > **作者** ：[weishu](<https://github.com/tiann>)**官方文档** ：<https://hapi.run/>
📋 简介 📋 简介
Hapi 是一个本地优先的应用程序，可以让你在本地运行 Claude Code / Codex / Gemini 会话，并通过 Web / PWA / Telegram Mini App 进行远程控制。这意味着你可以在手机或浏览器上监控和管理你的 AI 编程任务。 Hapi 是一个本地优先的应用程序，可以让你在本地运行 Claude Code / Codex / Gemini 会话，并通过 Web / PWA / Telegram Mini App 进行远程控制。这意味着你可以在手机或浏览器上监控和管理你的 AI 编程任务。
## 🔗 相关链接 ## 🔗 相关链接
资源| 地址 资源| 地址
---|--- ---|---
Hapi 官网| <https://hapi.run/> Hapi 官网| <https://hapi.run/>
Hapi 仓库| <https://github.com/tiann/hapi> Hapi 仓库| <https://github.com/tiann/hapi>
快速开始| [官方快速开始文档](<https://hapi.run/docs/guide/quick-start>) 快速开始| [官方快速开始文档](<https://hapi.run/docs/guide/quick-start>)
Cloudflare Tunnel 文档| [创建远程隧道](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>) Cloudflare Tunnel 文档| [创建远程隧道](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>)
## ✨ 核心功能 ## ✨ 核心功能
Hapi 提供以下强大功能： Hapi 提供以下强大功能：
* ✅ **无缝切换** ：在本地原生环境和远程控制之间无缝切换 * ✅ **无缝切换** ：在本地原生环境和远程控制之间无缝切换
* ✅ **远程会话** ：从任何设备发起远程会话 * ✅ **远程会话** ：从任何设备发起远程会话
* ✅ **移动监控** ：通过手机或浏览器监控和管理任务 * ✅ **移动监控** ：通过手机或浏览器监控和管理任务
* ✅ **权限控制** ：远程批准/拒绝工具权限 * ✅ **权限控制** ：远程批准/拒绝工具权限
* ✅ **文件浏览** ：浏览文件和查看 git diff * ✅ **文件浏览** ：浏览文件和查看 git diff
* ✅ **进度跟踪** ：通过待办事项列表跟踪进度 * ✅ **进度跟踪** ：通过待办事项列表跟踪进度
* ✅ **多后端支持** ：支持 Claude Code、Codex、Gemini * ✅ **多后端支持** ：支持 Claude Code、Codex、Gemini
## 🛠️ 安装步骤 ## 🛠️ 安装步骤
### 第一步：安装 Hapi ### 第一步：安装 Hapi
💡 前置要求 💡 前置要求
请确保已安装 Node.js 18+ 环境。如需安装，请参考 [Node.js 环境安装](</node/windows>)。 请确保已安装 Node.js 18+ 环境。如需安装，请参考 [Node.js 环境安装](</node/windows>)。
访问 [Hapi 官方快速开始文档](<https://hapi.run/docs/guide/quick-start>) 了解详细的安装方法。 访问 [Hapi 官方快速开始文档](<https://hapi.run/docs/guide/quick-start>) 了解详细的安装方法。
推荐使用 npx 快速启动 Hapi 服务器： 推荐使用 npx 快速启动 Hapi 服务器：
bash bash
npx @twsxtd/hapi server npx @twsxtd/hapi server
1 1
启动后会显示 Token 凭证和访问地址。 启动后会显示 Token 凭证和访问地址。
⚠️ 重要提示 ⚠️ 重要提示
**请务必保存好 Token 凭证！** 这是你连接和控制 Hapi 服务的唯一凭证。 **请务必保存好 Token 凭证！** 这是你连接和控制 Hapi 服务的唯一凭证。
![保留 Token 凭证](https://docs.ikuncode.cc/images/apps/hapi/image.png) ![保留 Token 凭证](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi01.png)
### 第二步：启动 AI 会话 ### 第二步：启动 AI 会话
在项目目录下执行以下命令启动对应的 AI 服务： 在项目目录下执行以下命令启动对应的 AI 服务：
**启动 Claude Code** ： **启动 Claude Code** ：
bash bash
hapi claude hapi claude
1 1
**启动 Codex** ： **启动 Codex** ：
bash bash
hapi codex hapi codex
1 1
**启动 Gemini** ： **启动 Gemini** ：
bash bash
hapi gemini hapi gemini
1 1
![启动命令](https://docs.ikuncode.cc/images/apps/hapi/image%201.png) ![启动命令](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi02.png)
启动成功后，前端界面会显示连接状态： 启动成功后，前端界面会显示连接状态：
![前端连接状态](https://docs.ikuncode.cc/images/apps/hapi/image%202.png) ![前端连接状态](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi03.png)
🎉 局域网访问 🎉 局域网访问
此时你已经可以在本地局域网内通过 `http://<server-ip>:3006` 访问和控制你的 AI 编程助手了！ 此时你已经可以在本地局域网内通过 `http://<server-ip>:3006` 访问和控制你的 AI 编程助手了！
## 🌐 配置 Cloudflare 内网穿透 ## 🌐 配置 Cloudflare 内网穿透
如果你想在任何地方（包括外网）访问你的 Hapi 服务，可以通过 Cloudflare Tunnel 实现内网穿透。 如果你想在任何地方（包括外网）访问你的 Hapi 服务，可以通过 Cloudflare Tunnel 实现内网穿透。
### 前置要求 ### 前置要求
* 一个域名（任意域名均可） * 一个域名（任意域名均可）
* Cloudflare 账号（免费账号即可） * Cloudflare 账号（免费账号即可）
### 配置流程 ### 配置流程
按照 [Cloudflare Tunnel 官方文档](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>) 进行配置： 按照 [Cloudflare Tunnel 官方文档](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>) 进行配置：
**1\. 登录 Cloudflare Zero Trust 控制台** **1\. 登录 Cloudflare Zero Trust 控制台**
![配置步骤 1](https://docs.ikuncode.cc/images/apps/hapi/image%203.png) ![配置步骤 1](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi04.png)
**2\. 创建新的 Tunnel** **2\. 创建新的 Tunnel**
![配置步骤 2](https://docs.ikuncode.cc/images/apps/hapi/image%204.png) ![配置步骤 2](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi05.png)
**3\. 安装 cloudflared 客户端** **3\. 安装 cloudflared 客户端**
![配置步骤 3](https://docs.ikuncode.cc/images/apps/hapi/image%205.png) ![配置步骤 3](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi06.png)
**4\. 配置隧道名称** **4\. 配置隧道名称**
![配置步骤 4](https://docs.ikuncode.cc/images/apps/hapi/image%206.png) ![配置步骤 4](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi07.png)
**5\. 配置公共主机名** **5\. 配置公共主机名**
![配置步骤 5](https://docs.ikuncode.cc/images/apps/hapi/image%207.png) ![配置步骤 5](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi08.png)
**6\. 设置服务地址** **6\. 设置服务地址**
将服务地址设置为 `localhost:3006`（Hapi 默认端口） 将服务地址设置为 `localhost:3006`（Hapi 默认端口）
![配置步骤 6](https://docs.ikuncode.cc/images/apps/hapi/image%208.png) ![配置步骤 6](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi09.png)
**7\. 完成配置** **7\. 完成配置**
![配置步骤 7](https://docs.ikuncode.cc/images/apps/hapi/image%209.png) ![配置步骤 7](https://minio.oneinai.com/oneinai/images/docs/hapi/hapi10.png)
## ✅ 使用 Hapi ## ✅ 使用 Hapi
配置完成后，你可以： 配置完成后，你可以：
1. **本地访问** ：`http://localhost:3006` 1. **本地访问** ：`http://localhost:3006`
2. **局域网访问** ：`http://<server-ip>:3006` 2. **局域网访问** ：`http://<server-ip>:3006`
3. **公网访问** ：`https://your-domain.com`（如果配置了 Cloudflare Tunnel） 3. **公网访问** ：`https://your-domain.com`（如果配置了 Cloudflare Tunnel）
使用步骤： 使用步骤：
1. 打开浏览器访问 Hapi 地址 1. 打开浏览器访问 Hapi 地址
2. 输入 Token 登录 2. 输入 Token 登录
3. 选择要启动的 AI 后端（Claude / Codex / Gemini） 3. 选择要启动的 AI 后端（Claude / Codex / Gemini）
4. 开始远程控制你的 AI 编程助手 4. 开始远程控制你的 AI 编程助手
💡 使用技巧 💡 使用技巧
* 在手机浏览器中访问可以随时随地监控任务进度 * 在手机浏览器中访问可以随时随地监控任务进度
* 可以安装为 PWA 应用，获得类似原生应用的体验 * 可以安装为 PWA 应用，获得类似原生应用的体验
* 支持多设备同时连接和控制 * 支持多设备同时连接和控制
## 🔒 安全建议 ## 🔒 安全建议
* 不要将 Token 泄露给他人 * 不要将 Token 泄露给他人
* 如果使用公网访问，建议启用 Cloudflare 的安全功能（如 Access 策略） * 如果使用公网访问，建议启用 Cloudflare 的安全功能（如 Access 策略）
* 定期更换 Token * 定期更换 Token
* 仅在可信网络环境下使用 * 仅在可信网络环境下使用
## 常见问题 ## 常见问题
### 提示无法连接到服务器？ ### 提示无法连接到服务器？
* 检查 Hapi 服务是否正常运行 * 检查 Hapi 服务是否正常运行
* 确认防火墙未阻止 3006 端口 * 确认防火墙未阻止 3006 端口
* 检查 Token 是否正确 * 检查 Token 是否正确
### Cloudflare Tunnel 配置失败？ ### Cloudflare Tunnel 配置失败？
* 确认域名已正确添加到 Cloudflare * 确认域名已正确添加到 Cloudflare
* 检查 cloudflared 客户端是否正确安装 * 检查 cloudflared 客户端是否正确安装
* 查看 cloudflared 日志排查问题 * 查看 cloudflared 日志排查问题
### 更多问题 ### 更多问题
请查看 [FAQ](</support/faq>) 或访问 [Hapi GitHub Issues](<https://github.com/tiann/hapi/issues>)。 请查看 [FAQ](</support/faq>) 或访问 [Hapi GitHub Issues](<https://github.com/tiann/hapi/issues>)。
## 🚀 进阶优化 ## 🚀 进阶优化
如果你想进一步提升 Hapi 的访问速度（特别是在国内网络环境下），可以配置 Cloudflare 优选 IP： 如果你想进一步提升 Hapi 的访问速度（特别是在国内网络环境下），可以配置 Cloudflare 优选 IP：
💡 速度优化 💡 速度优化
通过配置 Cloudflare 优选 IP，可以将访问延迟从几百毫秒降低到几十毫秒，实现接近直连的体验。 通过配置 Cloudflare 优选 IP，可以将访问延迟从几百毫秒降低到几十毫秒，实现接近直连的体验。
👉 查看详细教程：[Hapi 进阶：Cloudflare 优选 IP 高速穿透](</apps/hapi-advanced>) 👉 查看详细教程：[Hapi 进阶：Cloudflare 优选 IP 高速穿透](</apps/hapi-advanced>)

667
apidoc/apps/openclaw.md
View File

@ -1,498 +1,339 @@
# OpenClaw 配置指南 # OpenClaw 配置指南
**多平台 AI 编程代理，支持终端 TUI、Web Dashboard 和 Telegram Bot** **多平台 AI 编程代理，支持终端 TUI、Web Dashboard 和 Telegram Bot**
📋 简介 ## 📋 简介
OpenClaw 是一款功能丰富的 AI 编程代理工具，支持终端 TUI 交互、Web Dashboard 管理和 Telegram Bot 远程访问。适合需要在服务器环境中运行 AI 编程助手的开发者。 OpenClaw 是一款功能丰富的 AI 编程代理工具，支持终端 TUI 交互、Web Dashboard 管理和 Telegram Bot 远程访问。适合需要在服务器环境中运行 AI 编程助手的开发者。
⚠️ 适用环境 > ⚠️ **适用环境**
> 本教程适用于 **Linux 云服务器** 和 **macOS** 系统用户。
此教程适合 **Linux 云服务器** 和 **macOS** 系统用户。 > 🚨 **遇到 403 Your request was blocked？**
> 使用 oneinai 渠道时，**必须**在供应商配置中添加 `headers` 字段，否则请求会被拦截返回 403：
>
> ```json
> "headers": {
> "User-Agent": "claude-cli/2.0.76 (external, cli)",
> "Authorization": "Bearer sk-xxxx"
> }
> ```
>
> - `Authorization` 的值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥`
> - `User-Agent` 必须保持示例中的格式，不可省略或随意修改
> - 修改后执行 `openclaw gateway restart` 重启网关生效
>
> 详见下方[完整配置实例](#-完整配置实例)。
🚨 遇到 403 Your request was blocked？ ## 🔗 相关链接
使用 OneinAI 渠道时，**必须** 在供应商配置中添加 `headers` 字段，否则请求会被拦截返回 403： | 资源 | 地址 |
| --- | --- |
| OpenClaw 官网 | <https://openclaw.ai> |
| oneinai 控制台 | <https://api.oneinai.com/console/token> |
json ## ✨ 功能特点
"headers": {
"User-Agent": "claude-cli/2.0.76 (external, cli)",
"Authorization": "Bearer sk-xxxx"
}
1 - ✅ **终端 TUI**：命令行交互界面，适合 SSH 环境
2 - ✅ **Web Dashboard**：浏览器可视化管理面板
3 - ✅ **Telegram Bot**：支持通过 Telegram 远程对话
4 - ✅ **多模型支持**：Claude、GPT、Gemini 等多种模型
- ✅ **Gateway 网关**：内置网关服务，支持反向代理
- ✅ **Skill 扩展**：可通过 Dashboard 安装扩展技能
* `Authorization` 的值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥` ## 🛠️ 安装与初始化
* `User-Agent` 必须保持示例中的格式，不可省略或随意修改
* 修改后执行 `openclaw gateway restart` 重启网关生效
详见下方 完整配置实例。 ### 第一步：运行安装脚本
## 🔗 相关链接
资源| 地址
---|---
OpenClaw 官网| <https://openclaw.ai>
## ✨ 功能特点
* ✅ **终端 TUI** ：命令行交互界面，适合 SSH 环境
* ✅ **Web Dashboard** ：浏览器可视化管理面板
* ✅ **Telegram Bot** ：支持通过 Telegram 远程对话
* ✅ **多模型支持** ：Claude、GPT、Gemini 等多种模型
* ✅ **Gateway 网关** ：内置网关服务，支持反向代理
* ✅ **Skill 扩展** ：可通过 Dashboard 安装扩展技能
## 🛠️ 安装与初始化
### 第一步：运行安装脚本
登录服务器 SSH 或在 macOS 终端中运行以下命令： 登录服务器 SSH 或在 macOS 终端中运行以下命令：
bash ```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
curl -fsSL https://openclaw.ai/install.sh | bash
1
耐心等待安装流程结束。 耐心等待安装流程结束。
### 第二步：初始化配置 ### 第二步：初始化配置
安装过程中会依次出现以下选项，按照说明操作： 安装过程中会依次出现以下选项，按说明选择：
步骤| 选择| 说明 | 步骤 | 选择 | 说明 |
---|---|--- | --- | --- | --- |
启动方式| **QuickStart**| 快速开始模式 | 启动方式 | **QuickStart** | 快速开始模式 |
供应商设置| **Skip for now**| 先跳过，后续手动编辑配置文件 | 供应商设置 | **Skip for now** | 先跳过，后续手动编辑配置文件 |
适配器选择| **anthropic**| 选择 Anthropic 适配器 | 适配器选择 | **anthropic** | 选择 Anthropic 适配器 |
模型选择| **opus-4.5**| 或选择你需要的模型 | 模型选择 | **opus-4.5** | 或选择你需要的模型 |
社交适配器| 按需选择| 如 Telegram（可选） | 社交适配器 | 按需选择 | 如 Telegram（可选） |
Skill 安装| 跳过| 后续可通过 Dashboard 安装 | Skill 安装 | 跳过 | 后续可通过 Dashboard 安装 |
Hook 选择| 全选| 使用空格键全选后回车确认 | Hook 选择 | 全选 | 使用空格键全选后回车确认 |
打开方式| 跳过| 先跳过 | 打开方式 | 跳过 | 先跳过 |
Shell 补全| **yes**| 安装命令行自动补全 | Shell 补全 | **yes** | 安装命令行自动补全 |
## ⚙️ 渠道与模型配置
### 第一步：编辑配置文件 ## ⚙️ 渠道与模型配置
### 第一步：编辑配置文件
打开 OpenClaw 的配置文件进行编辑： 打开 OpenClaw 的配置文件进行编辑：
bash ```bash
vim ~/.openclaw/openclaw.json
```
vim ~/.openclaw/openclaw.json
1 参照下方[完整配置实例](#-完整配置实例)填入供应商和模型信息。
参照下方 完整配置实例 填入你的供应商和模型信息。 ### 第二步：填入 API Key
### 第二步：填入 API Key 在 `models.providers` 中配置供应商信息，将 `apiKey` 和 `headers.Authorization` 替换为你在 [oneinai 控制台](https://api.oneinai.com/console/token) 创建的 API Key。
在 `models.providers` 中配置供应商信息，将 `apiKey` 和 `headers.Authorization` 替换为你在 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 创建的 API Key。 > 💡 **支持的分组**
> OpenClaw 使用 **逆向分组** 的 API Key。请在[创建专属 Key](/guide/create-key) 时选择逆向分组。
💡 支持的分组 ### 第三步：重启网关
OpenClaw 使用 **逆向分组** 的 API Key。 ```bash
openclaw gateway restart
```
![只允许逆向分组](`+a+`) ### 第四步：验证配置
请在 [创建专属 Key](</guide/create-key>) 时选择逆向分组。
### 第三步：重启网关
bash
openclaw gateway restart
1
### 第四步：验证配置
运行以下命令进入 TUI 界面测试模型是否正常： 运行以下命令进入 TUI 界面测试模型是否正常：
bash ```bash
openclaw tui
```
openclaw tui
1
测试成功后输入 `/quit` 退出 TUI。 测试成功后输入 `/quit` 退出 TUI。
## 🌐 浏览器访问 Dashboard ## 🌐 浏览器访问 Dashboard
### 获取 Dashboard URL ### 获取 Dashboard URL
在控制台运行命令获取 Dashboard URL，在浏览器中访问即可进入管理面板。 在控制台运行命令获取 Dashboard URL，在浏览器中访问即可进入管理面板。
⚠️ 服务器用户注意 > ⚠️ **服务器用户注意**
> 如果你在远程服务器上运行 OpenClaw，需要完成以下额外步骤。
如果你在远程服务器运行 OpenClaw，需要： **1. 配置反向代理**
**1\. 配置反向代理** 使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并配置 SSL 证书。
使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并设置 SSL 证书。 **2. 修改配置文件**
**2\. 修改配置文件**
编辑 `~/.openclaw/openclaw.json`，在 `gateway` 字段下添加： 编辑 `~/.openclaw/openclaw.json`，在 `gateway` 字段下添加：
json ```json
"controlUi": {
"allowInsecureAuth": true
"controlUi": { }
"allowInsecureAuth": true ```
}
1 **3. 重启网关**
2
3
**3\. 重启网关** ```bash
openclaw gateway restart
bash ```
openclaw gateway restart
1
访问带有 Token 的 Dashboard URL 即可进入后台界面。 访问带有 Token 的 Dashboard URL 即可进入后台界面。
## 🤖 配置 Telegram Bot（可选） ## 🤖 配置 Telegram Bot（可选）
如果安装时选择了 Telegram 适配器，可以通过以下步骤配置 Bot 访问权限： 如果安装时选择了 Telegram 适配器，可以通过以下步骤配置 Bot 访问权限。
### 第一步：与 Bot 对话 ### 第一步：与 Bot 对话
在 Telegram 中找到你通过 **@BotFather** 创建的机器人，发起对话。 在 Telegram 中找到你通过 **@BotFather** 创建的机器人，发起对话。
### 第二步：获取 Pairing Code ### 第二步：获取 Pairing Code
首次对话后会收到一个 **Pairing Code** 。 首次对话后会收到一个 **Pairing Code**。
### 第三步：授权配对 ### 第三步：授权配对
在控制台运行以下命令完成授权： 在控制台运行以下命令完成授权：
bash ```bash
openclaw pairing approve telegram 你的Pairing_Code
```
openclaw pairing approve telegram 你的Pairing_Code
1
配对成功后，即可通过 Telegram Bot 与 OpenClaw 进行远程对话。 配对成功后，即可通过 Telegram Bot 与 OpenClaw 进行远程对话。
## 📄 完整配置实例 ## 📄 完整配置实例
以下是一份接入 IkunCode 渠道的 `openclaw.json` 完整配置参考（路径：`~/.openclaw/openclaw.json`）： 以下是一份接入 oneinai 渠道的 `openclaw.json` 完整参考（路径：`~/.openclaw/openclaw.json`）：
💡 说明 > 💡 **说明**
> 配置中的 `sk-xxxx` 和 `xxxxx` 为占位符，请替换为你自己的 API Key 和 Bot Token。
配置中的 `sk-xxxx` 和 `xxxxx` 为占位符，请替换为你自己的 API Key 和 Bot Token。 ```json
{
json "messages": {
"ackReactionScope": "group-mentions"
},
{ "agents": {
"messages": { "defaults": {
"ackReactionScope": "group-mentions" "model": {
"primary": "oneinai-claude/claude-opus-4-5-20251101"
}, },
"agents": { "maxConcurrent": 4,
"defaults": { "subagents": {
"model": { "maxConcurrent": 8
"primary": "ikuncode-claude/claude-opus-4-5-20251101"
},
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 8
},
"compaction": {
"mode": "safeguard"
},
"workspace": "C:\\\\Users\\\\Administrator\\\\.openclaw\\\\workspace"
}
}, },
"models": { "compaction": {
"providers": { "mode": "safeguard"
"ikuncode-claude": {
"baseUrl": "https://api.oneinai.com/v1",
"apiKey": "sk-xxxx",
"api": "openai-completions",
"headers": {
"User-Agent": "claude-cli/2.0.76 (external, cli)",
"Authorization": "Bearer sk-xxxx"
},
"models": [
{
"id": "claude-opus-4-5-20251101",
"name": "claude-opus-4-5-20251101",
"contextWindow": 200000,
"maxTokens": 32000,
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
}
}
]
},
"ikuncode-codex": {
"baseUrl": "https://api.oneinai.com/v1",
"apiKey": "sk-xxxx",
"api": "openai-completions",
"headers": {
"User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal",
"Authorization": "Bearer sk-xxxx"
},
"models": [
{
"id": "gpt-5.2-codex",
"name": "gpt-5.2-codex",
"contextWindow": 200000,
"maxTokens": 32000,
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
}
}
]
}
}
}, },
"gateway": { "workspace": "C:\\\\Users\\\\Administrator\\\\.openclaw\\\\workspace"
"mode": "local", }
"auth": { },
"mode": "token", "models": {
"token": "xxxx" "providers": {
"oneinai-claude": {
"baseUrl": "https://api.oneinai.com/v1",
"apiKey": "sk-xxxx",
"api": "openai-completions",
"headers": {
"User-Agent": "claude-cli/2.0.76 (external, cli)",
"Authorization": "Bearer sk-xxxx"
}, },
"port": 18789, "models": [
"bind": "loopback", {
"tailscale": { "id": "claude-opus-4-5-20251101",
"mode": "off", "name": "claude-opus-4-5-20251101",
"resetOnExit": false "contextWindow": 200000,
} "maxTokens": 32000,
}, "cost": {
"auth": { "input": 0,
"profiles": {} "output": 0,
}, "cacheRead": 0,
"plugins": { "cacheWrite": 0
"entries": { }
"telegram": {
"enabled": true
} }
} ]
}, },
"channels": { "oneinai-codex": {
"telegram": { "baseUrl": "https://api.oneinai.com/v1",
"enabled": true, "apiKey": "sk-xxxx",
"botToken": "xxxxx" "api": "openai-completions",
} "headers": {
}, "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal",
"logging": { "Authorization": "Bearer sk-xxxx"
"level": "trace", },
"consoleLevel": "debug", "models": [
"consoleStyle": "pretty" {
}, "id": "gpt-5.2-codex",
"commands": { "name": "gpt-5.2-codex",
"restart": true "contextWindow": 200000,
}, "maxTokens": 32000,
"skills": { "cost": {
"install": { "input": 0,
"nodeManager": "npm" "output": 0,
} "cacheRead": 0,
"cacheWrite": 0
}
}
]
} }
} }
},
1 "gateway": {
2 "mode": "local",
3 "auth": {
4 "mode": "token",
5 "token": "xxxx"
6 },
7 "port": 18789,
8 "bind": "loopback",
9 "tailscale": {
10 "mode": "off",
11 "resetOnExit": false
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
### 关键字段说明
字段| 说明
---|---
`agents.defaults.model.primary`| 默认使用的模型，格式为 `供应商名/模型ID`
`agents.defaults.maxConcurrent`| 主代理最大并发数
`agents.defaults.subagents.maxConcurrent`| 子代理最大并发数
`agents.defaults.compaction.mode`| 上下文压缩模式，`safeguard` 为安全模式
`agents.defaults.workspace`| 工作区目录路径，按你的系统修改
`models.providers`| 模型供应商配置，可配置多个供应商
`models.providers.*.baseUrl`| API 基础地址，IkunCode 统一为 `https://api.oneinai.com/v1`
`models.providers.*.apiKey`| 对应分组的 API Key
`models.providers.*.api`| 接口协议，固定为 `openai-completions`
`models.providers.*.headers`| 请求头，需包含 `User-Agent` 和 `Authorization`
`gateway.port`| 网关监听端口，默认 `18789`
`gateway.bind`| 绑定模式，`loopback` 仅本机访问
`channels.telegram.botToken`| Telegram Bot Token，通过 @BotFather 获取
`logging.level`| 日志级别，排查问题时可设为 `trace`
⚠️ 注意事项
* **Headers 中的 Authorization** 必须与 `apiKey` 保持一致，格式为 `Bearer sk-xxxx`
* **User-Agent** 建议保持示例中的格式，确保请求正常识别
* **workspace 路径** ：Windows 用户使用 `\\\\` 双反斜杠，Linux/macOS 用户使用 `/` 正斜杠（如 `/root/.openclaw/workspace`）
* **cost 全部设为 0** ：通过 IkunCode 中转使用时无需在本地计费
## 常见问题
### 安装脚本执行失败？
* 确认网络连接正常，能访问 `openclaw.ai`
* 确认系统已安装 `curl` 和 `bash`
* 如果在国内服务器，可能需要配置代理
### 遇到 403 `Your request was blocked` 怎么办？
如果请求返回 `403 Your request was blocked`，说明缺少正确的请求头。**必须** 在供应商配置中添加 `headers` 字段：
json
"headers": {
"User-Agent": "claude-cli/2.0.76 (external, cli)",
"Authorization": "Bearer sk-xxxx"
} }
},
"auth": {
"profiles": {}
},
"plugins": {
"entries": {
"telegram": {
"enabled": true
}
}
},
"channels": {
"telegram": {
"enabled": true,
"botToken": "xxxxx"
}
},
"logging": {
"level": "trace",
"consoleLevel": "debug",
"consoleStyle": "pretty"
},
"commands": {
"restart": true
},
"skills": {
"install": {
"nodeManager": "npm"
}
}
}
```
1 ### 关键字段说明
2
3
4
🚨 重要 | 字段 | 说明 |
| --- | --- |
| `agents.defaults.model.primary` | 默认使用的模型，格式为 `供应商名/模型ID` |
| `agents.defaults.maxConcurrent` | 主代理最大并发数 |
| `agents.defaults.subagents.maxConcurrent` | 子代理最大并发数 |
| `agents.defaults.compaction.mode` | 上下文压缩模式，`safeguard` 为安全模式 |
| `agents.defaults.workspace` | 工作区目录路径，按你的系统修改 |
| `models.providers` | 模型供应商配置，可配置多个供应商 |
| `models.providers.*.baseUrl` | API 基础地址，oneinai 统一为 `https://api.oneinai.com/v1` |
| `models.providers.*.apiKey` | 对应分组的 API Key |
| `models.providers.*.api` | 接口协议，固定为 `openai-completions` |
| `models.providers.*.headers` | 请求头，需包含 `User-Agent` 和 `Authorization` |
| `gateway.port` | 网关监听端口，默认 `18789` |
| `gateway.bind` | 绑定模式，`loopback` 仅本机访问 |
| `channels.telegram.botToken` | Telegram Bot Token，通过 @BotFather 获取 |
| `logging.level` | 日志级别，排查问题时可设为 `trace` |
* `headers` 中的 `Authorization` 值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥` > ⚠️ **注意事项**
* `User-Agent` 必须保持示例格式，否则请求会被拦截 > - **Headers 中的 Authorization** 必须与 `apiKey` 保持一致，格式为 `Bearer sk-xxxx`
* 配置完成后执行 `openclaw gateway restart` 重启网关 > - **User-Agent** 必须保持示例中的格式，确保请求正常识别
> - **workspace 路径**：Windows 用户使用 `\\\\` 双反斜杠，Linux/macOS 用户使用 `/` 正斜杠（如 `/root/.openclaw/workspace`）
> - **cost 全部设为 0**：通过 oneinai 中转使用时无需在本地计费
### Gateway 重启后模型仍不可用？ ## ❓ 常见问题
* 检查 API Key 是否正确填入 ### 安装脚本执行失败？
* 确认 Key 对应的分组支持你选择的模型
* 查看 OpenClaw 日志排查具体错误
### 更多问题 - 确认网络连接正常，能访问 `openclaw.ai`
- 确认系统已安装 `curl` 和 `bash`
- 如果在国内服务器，可能需要配置代理
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。 ### 遇到 403 `Your request was blocked` 怎么办？
如果请求返回 `403 Your request was blocked`，说明缺少正确的请求头。**必须**在供应商配置中添加 `headers` 字段：
```json
"headers": {
"User-Agent": "claude-cli/2.0.76 (external, cli)",
"Authorization": "Bearer sk-xxxx"
}
```
> 🚨 **重要**
> - `headers` 中的 `Authorization` 值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥`
> - `User-Agent` 必须保持示例格式，否则请求会被拦截
> - 配置完成后执行 `openclaw gateway restart` 重启网关
### Gateway 重启后模型仍不可用？
- 检查 API Key 是否正确填入
- 确认 Key 对应的分组支持你选择的模型
- 查看 OpenClaw 日志排查具体错误
### 更多问题
请查看 [FAQ](/support/faq)

12
apidoc/apps/opencode.md
View File

@ -36,7 +36,7 @@ bash
安装完成后，在终端输入 `opencode` 命令，若出现 TUI 界面则安装成功。 安装完成后，在终端输入 `opencode` 命令，若出现 TUI 界面则安装成功。
![安装成功界面](https://cdn.xf233.io/project/Packy-docs/Advanced/OpenCode/02.png) ![安装成功界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode01.png)
### 第二步：安装 CC-Switch ### 第二步：安装 CC-Switch
@ -48,7 +48,7 @@ bash
打开 CC-Switch，上方配置项选择 `OpenCode`，然后点击 **添加供应商** 按钮。 打开 CC-Switch，上方配置项选择 `OpenCode`，然后点击 **添加供应商** 按钮。
![添加供应商界面](https://docs.ikuncode.cc/images/opnecode.png) ![添加供应商界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode02.png)
**2\. 填写供应商信息** **2\. 填写供应商信息**
@ -66,7 +66,7 @@ bash
根据你需要的模型类型，选择正确分组的 API Key： 根据你需要的模型类型，选择正确分组的 API Key：
![只允许逆向分组]('+t+') ![只允许逆向分组](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode-group.png)
* **Claude 系列** ：只允许逆向分组 * **Claude 系列** ：只允许逆向分组
* **GPT 系列** ：Codex 分组 * **GPT 系列** ：Codex 分组
@ -80,11 +80,11 @@ bash
2. 输入 `/models` 命令，检查配置的渠道是否出现在模型列表中 2. 输入 `/models` 命令，检查配置的渠道是否出现在模型列表中
3. 如果能看到你添加的模型，说明配置成功 3. 如果能看到你添加的模型，说明配置成功
![模型列表验证](https://cdn.xf233.io/project/Packy-docs/Advanced/OpenCode/06.png) ![模型列表验证](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode03.png)
开始愉快地编码吧！🎉 开始愉快地编码吧！🎉
![使用中的对话界面](https://cdn.xf233.io/project/Packy-docs/Advanced/OpenCode/07.png) ![使用中的对话界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode0.png)
## 常见问题 ## 常见问题
@ -100,4 +100,4 @@ bash
### 更多问题 ### 更多问题
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。 请查看 [FAQ](</support/faq>)

2
apidoc/deploy/claude-code.md
View File

@ -336,4 +336,4 @@ source ~/.zshrc
### 更多问题 ### 更多问题
请查看 [FAQ](/support/faq) 或联系 [售后支持](/support/after-sales)。 请查看 [FAQ](/support/faq)

514
apidoc/deploy/codex.md
View File

@ -1,393 +1,283 @@
# CodeX 部署指南 # CodeX 部署指南
**企业级 AI 编码助手 - 完整部署手册** **企业级 AI 编码助手 - 完整部署手册**
资源| 地址 | 资源 | 地址 |
---|--- | --- | --- |
官方文档| [developers.openai.com/codex](<https://developers.openai.com/codex/>) | 官方文档 | [developers.openai.com/codex](https://developers.openai.com/codex/) |
| oneinai 控制台 | <https://api.oneinai.com/console/token> |
📋 前置要求
请先完成 [Node.js 环境安装](</node/windows>) 和 [CC-Switch 工具安装](</tools/cc-switch>)。 > 📋 **前置要求**
> 请先完成 [Node.js 环境安装](/node/windows) 和 [CC-Switch 工具安装](/tools/cc-switch)。
## 🎯 快速导航 ## 🎯 快速导航
CodeX 是基于 GPT-5 架构的下一代智能编程助手，为开发者提供卓越的代码生成与优化能力。 CodeX 是基于 GPT-5 架构的智能编程助手，为开发者提供卓越的代码生成与优化能力。
**部署路径** ：系统环境配置 ➜ CLI 工具安装 ➜ API 集成 ➜ 开发环境就绪 **部署路径**：系统环境配置 ➜ CLI 工具安装 ➜ API 集成 ➜ 开发环境就绪
## 🚀 使用 CC-Switch 快速配置（推荐） ## 🚀 使用 CC-Switch 快速配置（推荐）
⚠️ 前置条件 > ⚠️ **前置条件**
> 使用 CC-Switch 配置 CodeX 之前，请确保已通过 npm 全局安装 CodeX 工具：
>
> ```bash
> npm install -g @openai/codex@latest
> ```
>
> 验证安装：`codex --version`
使用 CC-Switch 配置 CodeX 之前，请确保已通过 npm 全局安装 CodeX 工具： 推荐使用 [CC-Switch 快速配置工具](/tools/cc-switch) 进行图形化配置，简单快捷无需命令行操作。
bash ### 配置步骤
npm install -g @openai/codex@latest
1 **1. 启动 CC-Switch 并切换到 Codex 标签**
验证安装：`codex --version` 1. 打开 CC-Switch 应用程序
2. 点击顶部的「Codex」标签页
3. 点击右上角橙色「+」按钮添加新配置
g
![CC-Switch Codex 标签页](https://minio.oneinai.com/oneinai/images/docs/codex/codex01.pn)
推荐使用 [CC-Switch 快速配置工具](</tools/cc-switch>) 进行图形化配置，简单快捷无需命令行操作。 **2. 填写 CodeX 提供商配置**
### 配置步骤 | 配置项 | 说明 |
| --- | --- |
| **提供商名称** | 自定义名称，如「oneinai」 |
| **Base URL** | `https://api.oneinai.com/v1` |
| **API Key** | 在 [oneinai 控制台](https://api.oneinai.com/console/token) 创建的 CodeX 专用令牌（codex 令牌组） |
| **Model** | `gpt-5.4`（撰写文档时最新模型为 5.4） |
| **其他配置** | 根据需求调整推理强度、网络访问等参数 |
**1\. 启动 CC-Switch 并切换到 Codex 标签** 填写完成后点击「保存」按钮。
1. 打开 CC-Switch 应用程序 ![CC-Switch 添加 CodeX 配置](https://minio.oneinai.com/oneinai/images/docs/codex/codex02.png)
2. 点击顶部的「Codex」标签页 ![CC-Switch CodeX 配置详情](https://minio.oneinai.com/oneinai/images/docs/codex/codex03.png)
3. 点击右上角橙色「+」按钮添加新配置
![CC-Switch Codex 标签页](https://docs.ikuncode.cc/images/tu9.png) > 💡 **提示**
> - CC-Switch 会自动创建 `~/.codex/config.toml` 和 `auth.json` 文件
> - 可以添加多个提供商配置，随时切换
> - 切换配置后，关闭并重启 CodeX 即可生效
**2\. 填写 CodeX 提供商配置** **3. 启用配置并使用**
1. **提供商名称** ：自定义名称（如「IkunCoding」） 1. 在配置列表中找到刚创建的「oneinai」配置
2. **Base URL** ：输入 `https://api.oneinai.com/v1` 2. 点击配置右侧的「当前使用」按钮
3. **API Key** ：粘贴您从 IkunCode 平台获取的 CodeX 专用令牌（codex令牌组） 3. 配置会被标记为「当前使用」状态（绿色标签）
4. **Model** ：选择 `gpt-5.4`（书写文档时最新模型为 5.4） 4. 重启 CodeX，新配置即可生效
5. **其他配置** ：根据需求调整推理强度、网络访问等参数
6. 点击「保存」按钮
![CC-Switch 添加 CodeX 配置](https://docs.ikuncode.cc/images/tu10.png)![CC-Switch CodeX 配置详情](https://docs.ikuncode.cc/images/tu11.png) **4. 系统托盘快速切换**
💡 提示
* CC-Switch 会自动创建 `~/.codex/config.toml` 和 `auth.json` 文件
* 可以添加多个提供商配置，随时切换
* 切换配置后，关闭并重启 CodeX 即可生效
**3\. 启用配置并使用**
1. 在配置列表中找到刚创建的「IkunCoding」配置
2. 点击配置右侧的「当前使用」按钮
3. 配置会被标记为「当前使用」状态（绿色标签）
4. 重启 CodeX，新配置即可生效
**4\. 系统托盘快速切换**
CC-Switch 支持通过系统托盘快速切换 CodeX 配置： CC-Switch 支持通过系统托盘快速切换 CodeX 配置：
* 右键点击系统托盘中的 CC-Switch 图标 - 右键点击系统托盘中的 CC-Switch 图标
* 在菜单中选择 Codex 分类 - 在菜单中选择 Codex 分类
* 直接选择要切换到的配置 - 直接选择要切换到的配置
* 配置立即生效，无需打开主界面 - 配置立即生效，无需打开主界面
⚠️ 注意事项 > ⚠️ **注意事项**
> - 务必在 oneinai 平台创建「codex」令牌组的专用密钥
> - CodeX 令牌与 Claude Code 令牌不通用
> - 切换配置后需要重启 CodeX 才能生效
> - 可在 CC-Switch 中测试 API 端点速度
* 务必从 IkunCode 平台创建「codex」令牌组的专用密钥 ## ⌨️ 手动命令行配置
* CodeX 令牌与 Claude Code 令牌不通用
* 切换配置后需要重启 CodeX 才能生效
* 可在 CC-Switch 中测试 API 端点速度
## ⌨️ 手动命令行配置 如果你不使用 CC-Switch，可以按照以下步骤手动配置 CodeX。
如果您不使用 CC-Switch，可以按照以下步骤手动配置 CodeX。 ### 🖥️ Windows 平台
### 🖥️ Windows 平台 #### 第一步：部署 CodeX 命令行工具
#### 第一步：部署 CodeX 命令行工具
以管理员权限启动命令提示符或 PowerShell，执行： 以管理员权限启动命令提示符或 PowerShell，执行：
powershell ```powershell
npm install -g @openai/codex@latest
codex --version
npm install -g @openai/codex@latest ```
codex --version
1 #### 第二步：集成 oneinai API 服务
2
#### 第二步：集成 IkunCoding API 服务 **获取专属 API 凭证**：
**获取专属 API 凭证** ： 1. 访问 [oneinai 控制台](https://api.oneinai.com/console/token)
2. 完成账户注册或登录
3. 进入「API 密钥管理」模块
4. 创建新密钥时务必选择「codex」令牌组
5. 安全保存生成的 API Key
1. 访问 IkunCoding 开发者控制台 > 🔐 **安全提醒**
2. 完成账户注册或执行登录操作 > CodeX 要求使用独立的令牌组配置，与 Claude Code 令牌体系完全隔离。
3. 导航至「API 密钥管理」模块
4. 创建新密钥时，务必选择「codex」令牌组
5. 安全保存生成的 API Key
🔐 安全提醒 **构建配置目录结构**：
CodeX 要求使用独立的令牌组配置，与 Claude Code 令牌体系完全隔离。 ```powershell
mkdir $env:USERPROFILE\.codex
cd $env:USERPROFILE\.codex
```
**构建配置目录结构** ： **编写配置文件 `config.toml`**：
powershell ```toml
model_provider = "oneinai"
model = "gpt-5.4"
mkdir %USERPROFILE%\\.codex model_reasoning_effort = "xhigh"
cd %USERPROFILE%\\.codex disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
1 [model_providers.oneinai]
2 name = "oneinai"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
```
**编写配置文件：config.toml** **编写认证文件 `auth.json`**：
toml ```json
{
"OPENAI_API_KEY": "此处粘贴你的 CodeX 专用令牌"
model_provider = "IkunCoding" }
model = "gpt-5.4" ```
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
[model_providers.IkunCoding]
name = "ikun"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
1 #### 第三步：初始化工作空间
2
3
4
5
6
7
8
9
10
11
12
13
**编写认证文件：auth.json** ```powershell
mkdir my-codex-project
cd my-codex-project
codex
```
json ### 🍏 macOS 平台
{
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
}
1 #### 部署 CodeX 工具
2
3
#### 第三步：初始化工作空间 ```bash
npm install -g @openai/codex@latest
codex --version
```
powershell #### 集成 API 服务
mkdir my-codex-project
cd my-codex-project
codex
1 **构建配置目录**：
2
3
### 🍏 macOS 平台 ```bash
mkdir -p ~/.codex
cd ~/.codex
```
#### 部署 CodeX 工具 **编写 `config.toml` 配置**：
bash ```bash
cat > config.toml << 'EOF'
model_provider = "oneinai"
npm install -g @openai/codex@latest model = "gpt-5.4"
codex --version model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
1 [model_providers.oneinai]
2 name = "oneinai"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF
```
#### 集成 API 服务 **编写 `auth.json` 认证配置**：
**构建配置目录** ： ```bash
cat > auth.json << 'EOF'
{
"OPENAI_API_KEY": "此处粘贴你的 CodeX 专用令牌"
}
EOF
```
bash #### 初始化工作空间
mkdir -p ~/.codex
cd ~/.codex
1 ```bash
2 mkdir my-codex-project
cd my-codex-project
codex
```
**编写 config.toml 配置** ： ### 🐧 Linux 平台
bash #### 部署 CodeX 工具
cat > config.toml << 'EOF'
model_provider = "IkunCoding"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
[model_providers.IkunCoding]
name = "ikun"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF
1 ```bash
2 sudo npm install -g @openai/codex@latest
3 codex --version
4 ```
5
6
7
8
9
10
11
12
13
14
15
**编写 auth.json 认证配置** ： #### 集成 API 服务
bash **构建配置目录**：
cat > auth.json << 'EOF'
{
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
}
EOF
1 ```bash
2 mkdir -p ~/.codex
3 cd ~/.codex
4 ```
5
#### 初始化工作空间 **编写 `config.toml` 配置**：
bash ```bash
cat > config.toml << 'EOF'
model_provider = "oneinai"
mkdir my-codex-project model = "gpt-5.4"
cd my-codex-project model_reasoning_effort = "xhigh"
codex disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
1 [model_providers.oneinai]
2 name = "oneinai"
3 base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF
```
### 🐧 Linux 平台 **编写 `auth.json` 认证配置**：
#### 部署 CodeX 工具 ```bash
cat > auth.json << 'EOF'
{
"OPENAI_API_KEY": "此处粘贴你的 CodeX 专用令牌"
}
EOF
```
bash #### 初始化工作空间
sudo npm install -g @openai/codex@latest
codex --version
1 ```bash
2 mkdir my-codex-project
cd my-codex-project
codex
```
#### 集成 API 服务 ## ❓ 常见问题
**构建配置目录** ： ### CodeX 和 Claude Code 的令牌不通用？
bash
mkdir -p ~/.codex
cd ~/.codex
1
2
**编写 config.toml 配置** ：
bash
cat > config.toml << 'EOF'
model_provider = "IkunCoding"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
[model_providers.IkunCoding]
name = "ikun"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
**编写 auth.json 认证配置** ：
bash
cat > auth.json << 'EOF'
{
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
}
EOF
1
2
3
4
5
#### 初始化工作空间
bash
mkdir my-codex-project
cd my-codex-project
codex
1
2
3
## 常见问题
### CodeX 和 Claude Code 的令牌不通用？
是的，两者使用不同的令牌组： 是的，两者使用不同的令牌组：
* Claude Code: 使用 Claude Code 令牌组 - Claude Code：使用 Claude Code 令牌组
* CodeX: 使用 "codex" 令牌组 - CodeX：使用 `codex` 令牌组
请在 IkunCode 平台创建对应的专用令牌。 请在 oneinai 平台创建对应的专用令牌。
### 配置文件放在哪里？ ### 配置文件放在哪里？
* Windows: `%USERPROFILE%\\.codex\\` - Windows：`%USERPROFILE%\.codex\`
* macOS/Linux: `~/.codex/` - macOS / Linux：`~/.codex/`
### 更多问题 ### 更多问题
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。 请查看 [FAQ](/support/faq)

448
apidoc/deploy/gemini-cli.md
View File

@ -1,347 +1,259 @@
# Gemini CLI 安装步骤 # Gemini CLI 安装步骤
**Google AI 编程助手安装指南** **Google AI 编程助手安装指南**
资源| 地址 | 资源 | 地址 |
---|--- | --- | --- |
官方文档| [geminicli.com/docs](<https://geminicli.com/docs/>) | 官方文档 | [geminicli.com/docs](https://geminicli.com/docs/) |
| oneinai 控制台 | <https://api.oneinai.com/console/token> |
📋 前置要求
请先完成 [Node.js 环境安装](</node/windows>)，确保 Node.js 18+ 已正确安装。 > 📋 **前置要求**
> 请先完成 [Node.js 环境安装](/node/windows)，确保 Node.js 18+ 已正确安装。
🚀 Gemini CLI 快速开始 ## 🚀 快速开始
Google AI 编程助手，Gemini 2.5 Pro 驱动 Google AI 编程助手，由 Gemini 2.5 Pro 驱动。
**1️⃣** 安装 CLI **2️⃣** 配置密钥 **3️⃣** 开始编码 **1️⃣ 安装 CLI　2️⃣ 配置密钥　3️⃣ 开始编码**
## 🚀 使用 CC-Switch 快速配置（推荐） ## 🚀 使用 CC-Switch 快速配置（推荐）
⚠️ 前置条件 > ⚠️ **前置条件**
> 使用 CC-Switch 配置 Gemini CLI 之前，请确保已通过 npm 全局安装 Gemini CLI：
>
> ```bash
> npm install -g @google/gemini-cli
> ```
>
> 验证安装：`gemini --version`
使用 CC-Switch 配置 Gemini CLI 之前，请确保已通过 npm 全局安装 Gemini CLI 工具： 推荐使用 [CC-Switch 快速配置工具](/tools/cc-switch) 进行图形化配置，简单快捷，无需手动创建配置文件。
bash ### 配置步骤
npm install -g @google/gemini-cli
1 **1. 启动 CC-Switch 并切换到 Gemini 标签**
验证安装：`gemini --version` 1. 打开 CC-Switch 应用程序
2. 点击顶部的「Gemini」标签页
3. 点击右上角橙色「+」按钮添加新配置
推荐使用 [CC-Switch 快速配置工具](</tools/cc-switch>) 进行图形化配置，简单快捷无需手动创建配置文件。 ![CC-Switch Gemini 标签页](https://minio.oneinai.com/oneinai/images/docs/gemini-cli/gemini-cli01.png)
### 配置步骤 **2. 填写 Gemini CLI 提供商配置**
**1\. 启动 CC-Switch 并切换到 Gemini 标签** | 配置项 | 说明 |
| --- | --- |
| **提供商名称** | 自定义名称，如「oneinai」 |
| **Base URL** | `https://api.oneinai.com` |
| **API Key** | 在 [oneinai 控制台](https://api.oneinai.com/console/token) 创建的 Gemini 专用令牌 |
| **Model** | `gemini-3-pro-preview` 或其他可用模型 |
| **安全设置** | 根据需求调整（可选） |
1. 打开 CC-Switch 应用程序 填写完成后点击「保存」按钮。
2. 点击顶部的「Gemini」标签页
3. 点击右上角橙色「+」按钮添加新配置
![CC-Switch Gemini 标签页](https://docs.ikuncode.cc/images/tu12.png) ![CC-Switch 添加 Gemini CLI 配置](https://minio.oneinai.com/oneinai/images/docs/gemini-cli/gemini-cli02.png)
![CC-Switch Gemini CLI 配置详情](https://minio.oneinai.com/oneinai/images/docs/gemini-cli/gemini-cli03.png)
**2\. 填写 Gemini CLI 提供商配置** > 💡 **提示**
> - CC-Switch 会自动创建 `~/.gemini/.env` 和 `settings.json` 文件
> - 可以添加多个提供商配置，随时切换
> - 切换配置后，关闭并重启 Gemini CLI 即可生效
1. **提供商名称** ：自定义名称（如「ikuncode」） **3. 启用配置并使用**
2. **Base URL** ：输入 `https://api.oneinai.com`
3. **API Key** ：粘贴您从 IkunCode 平台获取的 Gemini 专用令牌
4. **Model** ：选择 `gemini-3-pro-preview` 或其他可用模型
5. **安全设置** ：根据需求调整（可选）
6. 点击「保存」按钮
![CC-Switch 添加 Gemini CLI 配置](https://docs.ikuncode.cc/images/tu13.png)![CC-Switch Gemini CLI 配置详情](https://docs.ikuncode.cc/images/tu14.png) 1. 在配置列表中找到刚创建的「oneinai」配置
2. 点击配置右侧的「当前使用」按钮
3. 配置会被标记为「当前使用」状态（绿色标签）
4. 重启 Gemini CLI，新配置即可生效
💡 提示 **4. 系统托盘快速切换**
* CC-Switch 会自动创建 `~/.gemini/.env` 和 `settings.json` 文件
* 可以添加多个提供商配置，随时切换
* 切换配置后，关闭并重启 Gemini CLI 即可生效
**3\. 启用配置并使用**
1. 在配置列表中找到刚创建的「ikuncode」配置
2. 点击配置右侧的「当前使用」按钮
3. 配置会被标记为「当前使用」状态（绿色标签）
4. 重启 Gemini CLI，新配置即可生效
**4\. 系统托盘快速切换**
CC-Switch 支持通过系统托盘快速切换 Gemini CLI 配置： CC-Switch 支持通过系统托盘快速切换 Gemini CLI 配置：
* 右键点击系统托盘中的 CC-Switch 图标 - 右键点击系统托盘中的 CC-Switch 图标
* 在菜单中选择 Gemini 分类 - 在菜单中选择 Gemini 分类
* 直接选择要切换到的配置 - 直接选择要切换到的配置
* 配置立即生效，无需打开主界面 - 配置立即生效，无需打开主界面
⚠️ 注意事项 > ⚠️ **注意事项**
> - 务必在 oneinai 平台创建 Gemini CLI 专用令牌
> - Gemini 令牌与 Claude Code / CodeX 令牌不通用
> - 切换配置后需要重启 Gemini CLI 才能生效
> - 可在 CC-Switch 中测试 API 端点速度
* 确保从 IkunCode 平台创建 Gemini CLI 专用令牌 ## ⌨️ 手动命令行配置
* Gemini 令牌与 Claude Code/CodeX 令牌不通用
* 切换配置后需要重启 Gemini CLI 才能生效
* 可在 CC-Switch 中测试 API 端点速度
## ⌨️ 手动命令行配置 如果你不使用 CC-Switch，可以按照以下步骤手动安装和配置 Gemini CLI。
如果您不使用 CC-Switch，可以按照以下步骤手动安装和配置 Gemini CLI。 ### 🖥️ Windows 平台
### 🖥️ Windows 安装流程教程 #### 1️⃣ 全局安装 Gemini CLI
#### 1️⃣ 全局安装 Gemini CLI ```powershell
npm install -g @google/gemini-cli
```
powershell #### 2️⃣ 配置 Gemini CLI
npm install -g @google/gemini-cli
1 > ⚠️ **重要提示**
> 请替换下方的 `GEMINI_API_KEY` 为你从 [oneinai 控制台](https://api.oneinai.com/console/token) 获取的 Gemini CLI 专用 API 密钥。
#### 2️⃣ 配置 Gemini CLI **2.1 创建 gemini 配置目录**
⚠️ 重要提示 在用户目录下创建：`%USERPROFILE%\.gemini\`
请替换下方的 `GEMINI_API_KEY` 为你从 <https://ikuncode.cc> 获取的 Gemini CLI 专用 API 密钥！ **2.2 创建 `.env` 文件**
**3.1 创建 gemini 文件夹** 在 `.gemini` 目录中新建 `.env` 文件，写入：
在用户目录下：`%USERPROFILE%\\.gemini\\` ```env
GOOGLE_GEMINI_BASE_URL=https://api.oneinai.com
GEMINI_API_KEY=你的专属密钥（在 oneinai 控制台创建）
GEMINI_MODEL=gemini-3-pro-preview
```
**3.2 创建 .env 文件** **2.3 创建 `settings.json` 文件**
在 `gemini` 文件夹新建 `.env` 文件： 在 `.gemini` 目录中新建 `settings.json` 文件，写入：
env ```json
{
"ide": {
GOOGLE_GEMINI_BASE_URL=https://api.oneinai.com "enabled": true
GEMINI_API_KEY=你的专属密钥请到https://ikuncode.cc获取 },
GEMINI_MODEL=gemini-3-pro-preview "security": {
"auth": {
1 "selectedType": "gemini-api-key"
2
3
**3.3 创建 settings.json 文件**
在 `gemini` 文件夹新建 `settings.json` 文件：
json
{
"ide": {
"enabled": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
}
} }
}
}
```
1 #### 3️⃣ 启动 Gemini CLI
2
3
4
5
6
7
8
9
10
#### 3️⃣ 启动 Gemini CLI ```powershell
gemini
```
powershell > 🎉 **开始使用 Gemini CLI**
> - 输入上下文描述快速生成代码
> - Agent Mode 自动编程模式
gemini > - Google Search 实时联网搜索
1 ### 🍏 macOS 平台
🎉 开始使用 Gemini CLI #### 1️⃣ 全局安装 Gemini CLI
• 输入上下文描述 "M kikasuna" • Agent Mode 自动编程模式 • Google Search 实时联网搜索 ```bash
npm install -g @google/gemini-cli
```
### 🍏 macOS 安装流程教程 #### 2️⃣ 配置 Gemini CLI
#### 1️⃣ 全局安装 Gemini CLI **2.1 创建配置目录**：
bash ```bash
mkdir -p ~/.gemini
cd ~/.gemini
npm install -g @google/gemini-cli ```
1 **2.2 创建 `.env` 文件**：
#### 2️⃣ 配置 Gemini CLI ```bash
cat > .env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://api.oneinai.com
GEMINI_API_KEY=你的专属密钥（在 oneinai 控制台创建）
GEMINI_MODEL=gemini-3-pro-preview
EOF
```
**3.1 创建配置目录** ： **2.3 创建 `settings.json` 文件**：
bash ```bash
cat > settings.json << 'EOF'
{
mkdir -p ~/.gemini "ide": {
cd ~/.gemini "enabled": true
},
1 "security": {
2 "auth": {
"selectedType": "gemini-api-key"
**3.2 创建 .env 文件** ：
bash
cat > .env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://api.oneinai.com
GEMINI_API_KEY=你的专属密钥请到https://ikuncode.cc获取
GEMINI_MODEL=gemini-3-pro-preview
EOF
1
2
3
4
5
**3.3 创建 settings.json 文件** ：
bash
cat > settings.json << 'EOF'
{
"ide": {
"enabled": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
}
} }
EOF }
}
EOF
```
1 #### 3️⃣ 启动 Gemini CLI
2
3
4
5
6
7
8
9
10
11
12
#### 3️⃣ 启动 Gemini CLI ```bash
gemini
```
bash ### 🐧 Linux 平台
gemini
1 #### 1️⃣ 全局安装 Gemini CLI
### 🐧 Linux 安装流程教程 ```bash
sudo npm install -g @google/gemini-cli
```
#### 1️⃣ 全局安装 Gemini CLI #### 2️⃣ 配置 Gemini CLI
bash **2.1 创建配置目录**：
sudo npm install -g @google/gemini-cli
1 ```bash
mkdir -p ~/.gemini
cd ~/.gemini
```
#### 2️⃣ 配置 Gemini CLI **2.2 创建 `.env` 文件**：
**3.1 创建配置目录** ： ```bash
cat > .env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://api.oneinai.com
GEMINI_API_KEY=你的专属密钥（在 oneinai 控制台创建）
GEMINI_MODEL=gemini-3-pro-preview
EOF
```
bash **2.3 创建 `settings.json` 文件**：
mkdir -p ~/.gemini
cd ~/.gemini
1 ```bash
2 cat > settings.json << 'EOF'
{
**3.2 创建 .env 文件** ： "ide": {
"enabled": true
bash },
"security": {
"auth": {
cat > .env << 'EOF' "selectedType": "gemini-api-key"
GOOGLE_GEMINI_BASE_URL=https://api.oneinai.com
GEMINI_API_KEY=你的专属密钥请到https://ikuncode.cc获取
GEMINI_MODEL=gemini-3-pro-preview
EOF
1
2
3
4
5
**3.3 创建 settings.json 文件** ：
bash
cat > settings.json << 'EOF'
{
"ide": {
"enabled": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
}
} }
EOF }
}
EOF
```
1 #### 3️⃣ 启动 Gemini CLI
2
3
4
5
6
7
8
9
10
11
12
#### 3️⃣ 启动 Gemini CLI ```bash
gemini
```
bash > 🎉 **部署完成！**
> 现在你可以使用 Gemini CLI 进行 AI 辅助编程了。
gemini
1 ## ❓ 常见问题
🎉 部署完成！ ### API Key 在哪里获取？
现在您可以使用 Gemini CLI 进行 AI 辅助编程了。 登录 [oneinai 控制台](https://api.oneinai.com/console/token)，创建 Gemini CLI 专用令牌即可。
## 常见问题 ### 配置文件位置
### API Key 在哪里获取？ - Windows：`%USERPROFILE%\.gemini\`
- macOS / Linux：`~/.gemini/`
登录 [IkunCode 平台](<https://api.oneinai.com>)，创建 Gemini CLI 专用令牌。 ### 更多问题
### 配置文件位置 请查看 [FAQ](/support/faq)
* Windows: `%USERPROFILE%\\.gemini\\`
* macOS/Linux: `~/.gemini/`
### 更多问题
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。

612
apidoc/deploy/nano-banana.md
View File

@ -1,437 +1,293 @@
# ![NanoBanana](https://docs.ikuncode.cc/images/nano.png) NanoBanana 图像生成部署指南 # ![NanoBanana](https://minio.oneinai.com/oneinai/images/docs/nano-banana/nano-banana01.png) NanoBanana 图像生成部署指南
**通过 OneinAI 调用 Gemini 原生图像生成 API** **通过 oneinai 调用 Gemini 原生图像生成 API**
资源| 地址 | 资源 | 地址 |
---|--- | --- | --- |
OneinAI 平台| [api.ikuncode.cc](<https://api.oneinai.com>) | oneinai 平台 | <https://api.oneinai.com> |
| oneinai 控制台 | <https://api.oneinai.com/console/token> |
📋 简介
NanoBanana 是 OneinAI 提供的 Gemini 图像生成模型系列。通过 OneinAI 的 API Key 即可直接调用，无需科学上网，无需谷歌账号。 ## 📋 简介
## 🎯 模型介绍 NanoBanana 是 oneinai 提供的 Gemini 图像生成模型系列。通过 oneinai 的 API Key 即可直接调用，无需科学上网，无需谷歌账号。
OneinAI 提供两个 NanoBanana 模型： ## 🎯 模型介绍
模型| 模型 ID| 特点| 适用场景 oneinai 提供两个 NanoBanana 模型：
---|---|---|---
**NanoBananaPro**| `gemini-3-pro-image-preview`| 效果最佳，支持高清输出| 高质量海报、商业素材、精细创作
**NanoBanana2**| `gemini-3.1-flash-image-preview`| 速度快、价格低| 快速预览、批量生成、日常使用
💡 如何选择
* 追求**画质** ：选 NanoBananaPro（Pro 版） | 模型 | 模型 ID | 特点 | 适用场景 |
* 追求**速度和性价比** ：选 NanoBanana2（Flash 版） | --- | --- | --- | --- |
| **NanoBananaPro** | `gemini-3-pro-image-preview` | 效果最佳，支持高清输出 | 高质量海报、商业素材、精细创作 |
| **NanoBanana2** | `gemini-3.1-flash-image-preview` | 速度快、价格低 | 快速预览、批量生成、日常使用 |
## 📐 支持的宽高比 > 💡 **如何选择**
> - 追求**画质**：选 NanoBananaPro（Pro 版）
> - 追求**速度和性价比**：选 NanoBanana2（Flash 版）
两个模型均支持以下 **10 种宽高比** ： ## 📐 支持的宽高比
宽高比| 说明| 宽高比| 说明 两个模型均支持以下 **10 种宽高比**：
---|---|---|---
**1:1**| 正方形图片| **3:2**| 相机常用比例（横）
**16:9**| 横屏标准比例| **2:3**| 相机常用比例（竖）
**9:16**| 竖屏标准比例| **21:9**| 超宽屏比例
**4:3**| 传统横屏比例| **5:4**| 显示器比例（横）
**3:4**| 传统竖屏比例| **4:5**| 显示器比例（竖）
## 📏 支持的分辨率
每种宽高比支持三种分辨率等级： | 宽高比 | 说明 | 宽高比 | 说明 |
| --- | --- | --- | --- |
| **1:1** | 正方形图片 | **3:2** | 相机常用比例（横） |
| **16:9** | 横屏标准比例 | **2:3** | 相机常用比例（竖） |
| **9:16** | 竖屏标准比例 | **21:9** | 超宽屏比例 |
| **4:3** | 传统横屏比例 | **5:4** | 显示器比例（横） |
| **3:4** | 传统竖屏比例 | **4:5** | 显示器比例（竖） |
### 1K 分辨率（快速预览） ## 📏 支持的分辨率
宽高比| 分辨率| 宽高比| 分辨率 每种宽高比支持三种分辨率等级。
---|---|---|---
1:1| 1024×1024| 3:2| 1232×816
16:9| 1376×768| 2:3| 816×1232
9:16| 768×1376| 21:9| 1584×672
4:3| 1200×896| 5:4| 1136×896
3:4| 896×1200| 4:5| 896×1136
### 2K 分辨率（推荐使用）
宽高比| 分辨率| 宽高比| 分辨率 ### 1K 分辨率（快速预览）
---|---|---|---
1:1| 2048×2048| 3:2| 2464×1632
16:9| 2752×1536| 2:3| 1632×2464
9:16| 1536×2752| 21:9| 3168×1344
4:3| 2400×1792| 5:4| 2272×1792
3:4| 1792×2400| 4:5| 1792×2272
### 4K 分辨率（超高清）
宽高比| 分辨率| 宽高比| 分辨率 | 宽高比 | 分辨率 | 宽高比 | 分辨率 |
---|---|---|--- | --- | --- | --- | --- |
1:1| 4096×4096| 3:2| 4928×3264 | 1:1 | 1024×1024 | 3:2 | 1232×816 |
16:9| 5504×3072| 2:3| 3264×4928 | 16:9 | 1376×768 | 2:3 | 816×1232 |
9:16| 3072×5504| 21:9| 6336×2688 | 9:16 | 768×1376 | 21:9 | 1584×672 |
4:3| 4800×3584| 5:4| 4544×3584 | 4:3 | 1200×896 | 5:4 | 1136×896 |
3:4| 3584×4800| 4:5| 3584×4544 | 3:4 | 896×1200 | 4:5 | 896×1136 |
## 🔧 API 请求格式 ### 2K 分辨率（推荐使用）
| 宽高比 | 分辨率 | 宽高比 | 分辨率 |
| --- | --- | --- | --- |
| 1:1 | 2048×2048 | 3:2 | 2464×1632 |
| 16:9 | 2752×1536 | 2:3 | 1632×2464 |
| 9:16 | 1536×2752 | 21:9 | 3168×1344 |
| 4:3 | 2400×1792 | 5:4 | 2272×1792 |
| 3:4 | 1792×2400 | 4:5 | 1792×2272 |
### 4K 分辨率（超高清）
| 宽高比 | 分辨率 | 宽高比 | 分辨率 |
| --- | --- | --- | --- |
| 1:1 | 4096×4096 | 3:2 | 4928×3264 |
| 16:9 | 5504×3072 | 2:3 | 3264×4928 |
| 9:16 | 3072×5504 | 21:9 | 6336×2688 |
| 4:3 | 4800×3584 | 5:4 | 4544×3584 |
| 3:4 | 3584×4800 | 4:5 | 3584×4544 |
## 🔧 API 请求格式
NanoBanana 使用**谷歌原生格式** API，与 OpenAI 格式不同。 NanoBanana 使用**谷歌原生格式** API，与 OpenAI 格式不同。
### 基本请求结构 ### 基本请求结构
json ```json
{
"contents": [{
{ "parts": [
"contents": [{ { "text": "你的图片描述" }
"parts": [ ]
{ "text": "您的图片描述" } }],
] "generationConfig": {
}], "responseModalities": ["IMAGE"],
"generationConfig": { "imageConfig": {
"responseModalities": ["IMAGE"], "aspectRatio": "16:9",
"imageConfig": { "image_size": "2K"
"aspectRatio": "16:9", }
"image_size": "2K" }
} }
```
### 参数说明
| 参数 | 说明 | 可选值 |
| --- | --- | --- |
| `responseModalities` | 响应类型，必须设为图片 | `["IMAGE"]` |
| `aspectRatio` | 宽高比 | `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`、`5:4`、`4:5` |
| `image_size` | 分辨率等级 | `1K`、`2K`、`4K` |
### API 端点
```
POST https://api.oneinai.com/v1beta/models/{模型ID}:generateContent
```
- NanoBananaPro：`gemini-3-pro-image-preview`
- NanoBanana2：`gemini-3.1-flash-image-preview`
## 📝 示例代码
### cURL 示例
```bash
curl -X POST "https://api.oneinai.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "Authorization: Bearer sk-你的oneinai密钥" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts": [
{"text": "一只可爱的小猫咪坐在花园里，油画风格，高清，细节丰富"}
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"image_size": "2K"
} }
} }
}'
```
1 ### Python 示例
2
3
4
5
6
7
8
9
10
11
12
13
14
### 参数说明 ```python
import requests
import base64
参数| 说明| 可选值 API_KEY = "sk-你的oneinai密钥"
---|---|--- API_URL = "https://api.oneinai.com/v1beta/models/gemini-3-pro-image-preview:generateContent"
`responseModalities`| 响应类型，必须设为图片| `["IMAGE"]`
`aspectRatio`| 宽高比| `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`、`5:4`、`4:5`
`image_size`| 分辨率等级| `1K`、`2K`、`4K`
### API 端点
POST https://api.oneinai.com/v1beta/models/{模型ID}:generateContent
1 payload = {
"contents": [{
* NanoBananaPro：`gemini-3-pro-image-preview` "parts": [
* NanoBanana2：`gemini-3.1-flash-image-preview`
## 📝 示例代码
### cURL 示例
bash
curl -X POST "https://api.oneinai.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \\
-H "Authorization: Bearer sk-你的OneinAI密钥" \\
-H "Content-Type: application/json" \\
-d '{
"contents": [{
"parts": [
{"text": "一只可爱的小猫咪坐在花园里，油画风格，高清，细节丰富"} {"text": "一只可爱的小猫咪坐在花园里，油画风格，高清，细节丰富"}
] ]
}], }],
"generationConfig": { "generationConfig": {
"responseModalities": ["IMAGE"], "responseModalities": ["IMAGE"],
"imageConfig": { "imageConfig": {
"aspectRatio": "16:9", "aspectRatio": "16:9",
"image_size": "2K" "image_size": "2K"
}
}
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
### Python 示例
python
import requests
import base64
API_KEY = "sk-你的OneinAI密钥"
API_URL = "https://api.oneinai.com/v1beta/models/gemini-3-pro-image-preview:generateContent"
payload = {
"contents": [{
"parts": [
{"text": "一只可爱的小猫咪坐在花园里，油画风格，高清，细节丰富"}
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"image_size": "2K"
}
} }
} }
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(API_URL, headers=headers, json=payload, timeout=600)
if response.status_code == 200:
data = response.json()
image_base64 = data["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
# 保存图片
with open("output.png", "wb") as f:
f.write(base64.b64decode(image_base64))
print("图片已保存为 output.png")
else:
print(f"请求失败: {response.status_code}")
print(response.text)
1 headers = {
2 "Authorization": f"Bearer {API_KEY}",
3 "Content-Type": "application/json"
4 }
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
### Node.js 示例 response = requests.post(API_URL, headers=headers, json=payload, timeout=600)
javascript if response.status_code == 200:
data = response.json()
image_base64 = data["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
const fs = require('fs');
const API_KEY = 'sk-你的OneinAI密钥';
const API_URL = 'https://api.oneinai.com/v1beta/models/gemini-3-pro-image-preview:generateContent';
async function generateImage() {
const response = await fetch(API_URL, {
method: 'POST',
headers: {
'Authorization': \`Bearer \${API_KEY}\`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
contents: [{
parts: [
{ text: '一只可爱的小猫咪坐在花园里，油画风格，高清，细节丰富' }
]
}],
generationConfig: {
responseModalities: ['IMAGE'],
imageConfig: {
aspectRatio: '16:9',
image_size: '2K'
}
}
})
});
const data = await response.json();
const imageBase64 = data.candidates[0].content.parts[0].inlineData.data;
fs.writeFileSync('output.png', Buffer.from(imageBase64, 'base64'));
console.log('图片已保存为 output.png');
}
generateImage().catch(console.error);
1 with open("output.png", "wb") as f:
2 f.write(base64.b64decode(image_base64))
3 print("图片已保存为 output.png")
4 else:
5 print(f"请求失败: {response.status_code}")
6 print(response.text)
7 ```
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
## 🖼️ 图生图编辑 ### Node.js 示例
NanoBananaPro 还支持**图生图** 功能，上传一张图片并描述编辑指令，即可对图片进行修改。 ```javascript
const fs = require('fs');
json const API_KEY = 'sk-你的oneinai密钥';
const API_URL = 'https://api.oneinai.com/v1beta/models/gemini-3-pro-image-preview:generateContent';
{ async function generateImage() {
"contents": [{ const response = await fetch(API_URL, {
"parts": [ method: 'POST',
{ headers: {
"inlineData": { 'Authorization': `Bearer ${API_KEY}`,
"mimeType": "image/png", 'Content-Type': 'application/json'
"data": "图片的Base64编码字符串" },
} body: JSON.stringify({
}, contents: [{
{ "text": "将背景改为星空，保持人物不变" } parts: [
{ text: '一只可爱的小猫咪坐在花园里，油画风格，高清，细节丰富' }
] ]
}], }],
"generationConfig": { generationConfig: {
"responseModalities": ["IMAGE"], responseModalities: ['IMAGE'],
"imageConfig": { imageConfig: {
"aspectRatio": "16:9", aspectRatio: '16:9',
"image_size": "2K" image_size: '2K'
} }
} }
})
});
const data = await response.json();
const imageBase64 = data.candidates[0].content.parts[0].inlineData.data;
fs.writeFileSync('output.png', Buffer.from(imageBase64, 'base64'));
console.log('图片已保存为 output.png');
}
generateImage().catch(console.error);
```
## 🖼️ 图生图编辑
NanoBananaPro 还支持**图生图**功能，上传一张图片并描述编辑指令，即可对图片进行修改。
```json
{
"contents": [{
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "图片的Base64编码字符串"
}
},
{ "text": "将背景改为星空，保持人物不变" }
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"image_size": "2K"
} }
}
}
```
1 > 💡 **图生图使用技巧**
2 > - 编辑指令要**具体明确**，说清楚保留什么、修改什么
3 > - 支持换背景、改风格、加元素、去水印等操作
4 > - 图片需要转为 Base64 编码后放入 `inlineData.data` 字段
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
💡 图生图使用技巧 ## 🤖 在 Claude Code 中使用
* 编辑指令要**具体明确** ，说清楚保留什么、修改什么 如果你已安装 oneimage Skill，可以在 Claude Code 对话中直接使用自然语言生成图片，无需手动调用 API。
* 支持换背景、改风格、加元素、去水印等操作
* 图片需要转为 Base64 编码后放入 `inlineData.data` 字段
## 🤖 在 Claude Code 中使用 ```
> 用 oneinai 画一张赛博朋克风格的城市夜景，16:9 比例，2K 分辨率
如果您已安装 [ikunimage Skill](</skills/ikunimage>)，可以在 Claude Code 对话中直接使用自然语言生成图片，无需手动调用 API。 > oneinai 生成一张水墨风格的山水画，竖屏 9:16
> 用 ikun 画一张赛博朋克风格的城市夜景，16:9 比例，2K 分辨率
> ikun 生成一张水墨风格的山水画，竖屏 9:16
> 用 ikun 编辑这张图片 /path/to/image.png，把背景换成海边日落
1 > 用 oneinai 编辑这张图片 /path/to/image.png，把背景换成海边日落
2 ```
3
4
5
详细安装和使用说明请参考：[ikunimage AI 生图](</skills/ikunimage>) 详细安装和使用说明请参考 oneimage AI 生图技能文档。
## ⏱️ 性能建议 ## ⏱️ 性能建议
### 推荐超时时间 ### 推荐超时时间
不同分辨率的处理时间差异较大，建议设置合理的超时： 不同分辨率的处理时间差异较大，建议设置合理的超时：
分辨率| 推荐超时| 适用场景 | 分辨率 | 推荐超时 | 适用场景 |
---|---|--- | --- | --- | --- |
**1K**| 360 秒（6 分钟）| 快速预览、测试效果 | **1K** | 360 秒（6 分钟） | 快速预览、测试效果 |
**2K**| 600 秒（10 分钟）| 日常使用（推荐） | **2K** | 600 秒（10 分钟） | 日常使用（推荐） |
**4K**| 1200 秒（20 分钟）| 超高清输出、商业用途 | **4K** | 1200 秒（20 分钟） | 超高清输出、商业用途 |
### 带宽注意 ### 带宽注意
图片数据使用 Base64 编码传输，数据量较大： 图片数据使用 Base64 编码传输，数据量较大：
* 建议使用**稳定高速的网络连接** - 建议使用**稳定高速的网络连接**
* 4K 图片的 Base64 数据可能超过 **10MB** - 4K 图片的 Base64 数据可能超过 **10MB**
* 避免在网络高峰时段生成 4K 图片 - 避免在网络高峰时段生成 4K 图片
## ⚠️ 注意事项 ## ⚠️ 注意事项
1. **API Key** ：需从 [OneinAI 平台](<https://api.oneinai.com>) 创建支持图像模型的令牌 1. **API Key**：需从 [oneinai 平台](https://api.oneinai.com) 创建支持图像模型的令牌
2. **API 格式** ：NanoBanana 使用**谷歌原生格式** ，不是 OpenAI 兼容格式，请注意区分 2. **API 格式**：NanoBanana 使用**谷歌原生格式**，不是 OpenAI 兼容格式，请注意区分
3. **分辨率与耗时** ：分辨率越高，生成时间越长，请根据实际需求选择 3. **分辨率与耗时**：分辨率越高，生成时间越长，请根据实际需求选择
4. **文字渲染** ：支持在图片中渲染中文文字（如招牌、海报文案），在 prompt 中直接写明即可 4. **文字渲染**：支持在图片中渲染中文文字（如招牌、海报文案），在 prompt 中直接写明即可
5. **价格差异** ：不同模型和分辨率价格不同，详见 OneinAI 平台定价页面 5. **价格差异**：不同模型和分辨率价格不同，详见 oneinai 平台定价页面

60
apidoc/guide/create-key.md
View File

@ -1,45 +1,39 @@
# 创建专属 Key # 创建专属 Key
注册登录后，点击创建专属 Key。 注册登录后，点击创建专属 Key。
## 创建步骤 ## 创建步骤
1. 登录 OneinAI 平台 1. 登录 oneinai 平台
2. 访问"[令牌管理](<https://api.oneinai.com/console/token>)" 2. 访问 [令牌管理](https://api.oneinai.com/console/token)
3. 点击"添加令牌"按钮 3. 点击「添加令牌」按钮
4. 创建需要使用的令牌，不要选择用户分组，请根据[监测站](<https://status.ikuncode.cc/>)的模型状态和令牌说明、倍率综合选择适合您的分组。 4. 创建需要使用的令牌，**不要选择用户分组**。请根据[监测站](https://status.oneinai.com/)的模型状态、令牌说明与倍率综合选择适合你的分组
5. 保存并复制 Key 5. 保存并复制 Key
💡 小提示 > 💡 **小提示**
> **模型限制列表**留空即可，无需配置（除非你了解它的作用）。
**模型限制列表** 留空即可，不需要配置。除非您看懂了它的作用。 ## 安全建议
## 安全建议 > 🔐 **安全提醒**
> - **不要**将 Key 分享给他人
> - **不要**将 Key 提交到代码仓库
> - **不要**在公开场合展示 Key
> - 询问配置是否正确时，请给 Key 打码
> - 使用环境变量或配置文件存储 Key
> - 定期更换 Key 提高安全性
🔐 安全提醒 ## 保存 Key
* **不要** 将 Key 分享给他人 创建成功后，请立即保存好你的 Key：
* **不要** 将 Key 提交到代码仓库
* **不要** 在公开场合展示 Key
* 询问配置是否正确时，给Key打码
* 使用环境变量或配置文件存储 Key
* 定期更换 Key 提高安全性
## 保存 Key ```bash
# 示例 Key（请替换为你的实际 Key）
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
创建成功后，请立即保存好您的 Key： ## 下一步
bash - [修改令牌设置](/guide/modify-token) - 调整令牌参数
- [配置环境变量](/deploy/claude-code#配置环境变量) - 在工具中使用 Key
- [充值](/guide/recharge) - 确保账户有足够余额
# 示例 Key（请替换为您的实际 Key）
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
1
2
## 下一步
* [修改令牌设置](</guide/modify-token>) \- 调整令牌参数
* [配置环境变量](</deploy/claude-code#配置环境变量>) \- 在工具中使用 Key
* [充值](</guide/recharge>) \- 确保账户有足够余额

142
apidoc/guide/modify-token.md
View File

@ -1,71 +1,71 @@
# 修改令牌设置 # 修改令牌设置
创建 Key 后，您可以根据需要修改令牌的各项设置。 创建 Key 后，您可以根据需要修改令牌的各项设置。
![令牌设置页面](https://docs.ikuncode.cc/images/tu3_new.png) ![令牌设置页面](https://minio.oneinai.com/oneinai/images/docs/modify-token/modify-token01.png)
## 可修改的设置 ## 可修改的设置
### 令牌名称 ### 令牌名称
修改令牌的显示名称，便于区分和管理。 修改令牌的显示名称，便于区分和管理。
### 配额限制 ### 配额限制
调整令牌的使用额度： 调整令牌的使用额度：
* 无限额度 * 无限额度
* 设置每日/每月限额 * 设置每日/每月限额
* 设置总额度 * 设置总额度
### 速率限制 ### 速率限制
控制请求频率： 控制请求频率：
* 每分钟请求数 * 每分钟请求数
* 每小时请求数 * 每小时请求数
* 并发请求数 * 并发请求数
### 启用/禁用 ### 启用/禁用
临时禁用令牌而不删除，方便后续再次使用。 临时禁用令牌而不删除，方便后续再次使用。
## 修改步骤 ## 修改步骤
1. 登录控制台 1. 登录控制台
2. 找到要修改的令牌 2. 找到要修改的令牌
3. 点击"编辑"按钮 3. 点击"编辑"按钮
4. 修改相关设置 4. 修改相关设置
5. 保存更改 5. 保存更改
## 重要提示 ## 重要提示
⚠️ 注意 ⚠️ 注意
* 修改设置后立即生效 * 修改设置后立即生效
* 某些设置可能需要重启工具才能应用 * 某些设置可能需要重启工具才能应用
* 修改令牌组需要重新创建 Key * 修改令牌组需要重新创建 Key
## 保留好 Key 备用 ## 保留好 Key 备用
修改设置后，请确保保存好您的 Key，后续配置环境变量需要使用。 修改设置后，请确保保存好您的 Key，后续配置环境变量需要使用。
bash bash
# Windows PowerShell # Windows PowerShell
$env:ANTHROPIC_AUTH_TOKEN="您的Key" $env:ANTHROPIC_AUTH_TOKEN="您的Key"
# macOS/Linux # macOS/Linux
export ANTHROPIC_AUTH_TOKEN="您的Key" export ANTHROPIC_AUTH_TOKEN="您的Key"
1 1
2 2
3 3
4 4
5 5
## 下一步 ## 下一步
* [充值](</guide/recharge>) \- 为账户充值 * [充值](</guide/recharge>) \- 为账户充值
* [开始部署](</deploy/claude-code>) \- 配置 AI 编程工具 * [开始部署](</deploy/claude-code>) \- 配置 AI 编程工具

3
apidoc/guide/recharge.md
View File

@ -88,9 +88,6 @@
* 可能享受优惠价格 * 可能享受优惠价格
* 支持开具发票 * 支持开具发票
## 联系方式
如有充值相关问题，请查看[售前售后](</support/after-sales>)页面获取联系方式。
## 下一步 ## 下一步

2
apidoc/guide/registration.md
View File

@ -10,7 +10,7 @@
* 使用邮箱注册 * 使用邮箱注册
* 使用第三方账号快捷注册 * 使用第三方账号快捷注册
![注册页面](https://docs.ikuncode.cc/images/tu1.png) ![注册页面](https://minio.oneinai.com/oneinai/images/docs/registration/registration01.png)
## 注册方式 ## 注册方式

70
apidoc/intro/links.md
View File

@ -1,35 +1,35 @@
# 友情链接 # 友情链接
🤝 推荐说明 🤝 推荐说明
本站管理员推荐，与站长无利益相关。**不做任何背书，请自行判断。** 本站管理员推荐，与站长无利益相关。**不做任何背书，请自行判断。**
## Claude Code 镜像站 ## Claude Code 镜像站
[![EasyChat](https://docs.ikuncode.cc/images/Anthropic.png)EasyChatClaude Code 免费账号网页版镜像站，无需注册即可体验 Claude 对话→](<https://easychat.top/>) [![EasyChat](https://minio.oneinai.com/oneinai/images/docs/links/links01.png)EasyChatClaude Code 免费账号网页版镜像站，无需注册即可体验 Claude 对话→](<https://easychat.top/>)
### 简介 ### 简介
EasyChat 是面向 Claude 网页 Chat 使用场景推出的镜像服务，主要服务于内容创作、学习、日常办公等用户群体。自 2024 年 9 月创建 [easychat.top](<https://easychat.top/>) 站点以来持续运行至今，一直保证稳定可用。 EasyChat 是面向 Claude 网页 Chat 使用场景推出的镜像服务，主要服务于内容创作、学习、日常办公等用户群体。自 2024 年 9 月创建 [easychat.top](<https://easychat.top/>) 站点以来持续运行至今，一直保证稳定可用。
系统全部自主研发，并持续更新改善，力求给用户提供最接近官网的使用体验。 系统全部自主研发，并持续更新改善，力求给用户提供最接近官网的使用体验。
### 使用方式 ### 使用方式
**1\. 选择账号** **1\. 选择账号**
打开 [EasyChat](<https://easychat.top/>) 后，页面会展示多个可用的免费共享账号卡片，点击任意一个状态为「可用」的账号即可开始对话。 打开 [EasyChat](<https://easychat.top/>) 后，页面会展示多个可用的免费共享账号卡片，点击任意一个状态为「可用」的账号即可开始对话。
![账号选择界面](https://docs.ikuncode.cc/images/jxz.png) ![账号选择界面](https://minio.oneinai.com/oneinai/images/docs/links/links02.png)
**2\. 开始聊天** **2\. 开始聊天**
进入后即为标准的 Claude 聊天界面，支持中文对话、多轮上下文、代码生成等全部功能。 进入后即为标准的 Claude 聊天界面，支持中文对话、多轮上下文、代码生成等全部功能。
![聊天界面](https://docs.ikuncode.cc/images/ltjm.png) ![聊天界面](https://minio.oneinai.com/oneinai/images/docs/links/links03.png)
注意 注意
* 共享账号为公共资源，请合理使用，勿滥用 * 共享账号为公共资源，请合理使用，勿滥用
* 超长对话会消耗更多使用次数，请合理规划用量 * 超长对话会消耗更多使用次数，请合理规划用量
* 如遇账号不可用，请稍后再试或选择其他账号 * 如遇账号不可用，请稍后再试或选择其他账号

1
apidoc/intro/overview.md
View File

@ -72,4 +72,3 @@ OneinAI 作为中间层：
* [注册账号](</guide/registration>)开始使用 * [注册账号](</guide/registration>)开始使用
* 查看[常见问题](</support/faq>)了解更多 * 查看[常见问题](</support/faq>)了解更多
* 联系[售后支持](</support/after-sales>)获取帮助

2
apidoc/intro/welcome.md
View File

@ -1,6 +1,6 @@
# 欢迎使用 OneinAI！ # 欢迎使用 OneinAI！
OneinAI 是一家专注于给编码人员生产提效的中转站（目前主要是 Claude Code、Codex等服务），我们始终坚持"真诚 热爱"的服务理念，希望能和用户交朋友。有任何服务不周到、用得不爽的地方，请直接联系（见[售前售后](</support/after-sales>)）我们的服务人员。 OneinAI 是一家专注于给编码人员生产提效的中转站（目前主要是 Claude Code、Codex等服务），我们始终坚持"真诚 热爱"的服务理念，希望能和用户交朋友。有任何服务不周到、用得不爽的地方，请直接联系我们的服务人员。
💡 提示 💡 提示

294
apidoc/node/linux.md
View File

@ -1,147 +1,147 @@
# Linux 平台安装 Node.js # Linux 平台安装 Node.js
**三大 AI 编程工具的必备运行环境** **三大 AI 编程工具的必备运行环境**
💡 重要说明 💡 重要说明
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v` Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
## Ubuntu/Debian 发行版 ## Ubuntu/Debian 发行版
### 使用 NodeSource 仓库（推荐） ### 使用 NodeSource 仓库（推荐）
bash bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs sudo apt-get install -y nodejs
# 验证安装 # 验证安装
node --version node --version
npm --version npm --version
1 1
2 2
3 3
4 4
5 5
6 6
## CentOS/RHEL 发行版 ## CentOS/RHEL 发行版
bash bash
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash - curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs sudo yum install -y nodejs
# 验证安装 # 验证安装
node --version node --version
npm --version npm --version
1 1
2 2
3 3
4 4
5 5
6 6
## Fedora 发行版 ## Fedora 发行版
bash bash
sudo dnf install -y nodejs npm sudo dnf install -y nodejs npm
# 验证安装 # 验证安装
node --version node --version
npm --version npm --version
1 1
2 2
3 3
4 4
5 5
## Arch Linux ## Arch Linux
bash bash
sudo pacman -S nodejs npm sudo pacman -S nodejs npm
# 验证安装 # 验证安装
node --version node --version
npm --version npm --version
1 1
2 2
3 3
4 4
5 5
## 使用 nvm（推荐进阶用户） ## 使用 nvm（推荐进阶用户）
nvm 允许您管理多个 Node.js 版本： nvm 允许您管理多个 Node.js 版本：
bash bash
# 安装 nvm # 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 重新加载 shell 配置 # 重新加载 shell 配置
source ~/.bashrc source ~/.bashrc
# 安装 Node.js LTS # 安装 Node.js LTS
nvm install --lts nvm install --lts
# 设置默认版本 # 设置默认版本
nvm use --lts nvm use --lts
nvm alias default node nvm alias default node
1 1
2 2
3 3
4 4
5 5
6 6
7 7
8 8
9 9
10 10
11 11
12 12
## 常见问题 ## 常见问题
### 权限问题 ### 权限问题
如果遇到权限问题，可以配置 npm 使用用户目录： 如果遇到权限问题，可以配置 npm 使用用户目录：
bash bash
mkdir ~/.npm-global mkdir ~/.npm-global
npm config set prefix '~/.npm-global' npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc source ~/.bashrc
1 1
2 2
3 3
4 4
### 版本过旧 ### 版本过旧
如果系统自带的 Node.js 版本过旧，建议使用 NodeSource 仓库或 nvm 安装最新 LTS 版本。 如果系统自带的 Node.js 版本过旧，建议使用 NodeSource 仓库或 nvm 安装最新 LTS 版本。
## 下一步 ## 下一步
✅ 环境准备完成！ ✅ 环境准备完成！
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。 现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
* [安装 Claude Code](</deploy/claude-code>) * [安装 Claude Code](</deploy/claude-code>)
* [安装 CodeX](</deploy/codex>) * [安装 CodeX](</deploy/codex>)
* [安装 Gemini CLI](</deploy/gemini-cli>) * [安装 Gemini CLI](</deploy/gemini-cli>)

174
apidoc/node/macos.md
View File

@ -1,87 +1,87 @@
# macOS 平台安装 Node.js # macOS 平台安装 Node.js
**三大 AI 编程工具的必备运行环境** **三大 AI 编程工具的必备运行环境**
💡 重要说明 💡 重要说明
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v` Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
## 方法一：Homebrew 包管理器（推荐） ## 方法一：Homebrew 包管理器（推荐）
bash bash
# 安装 Homebrew（如果未安装） # 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Node.js # 安装 Node.js
brew install node brew install node
# 验证安装 # 验证安装
node --version node --version
npm --version npm --version
1 1
2 2
3 3
4 4
5 5
6 6
7 7
8 8
9 9
## 方法二：官方安装包 ## 方法二：官方安装包
1. 访问 Node.js 官网：<https://nodejs.org> 1. 访问 Node.js 官网：<https://nodejs.org>
2. 下载 LTS 版本的 .pkg 安装包 2. 下载 LTS 版本的 .pkg 安装包
3. 运行安装程序并按照提示完成安装 3. 运行安装程序并按照提示完成安装
## 验证安装 ## 验证安装
打开终端，执行： 打开终端，执行：
bash bash
node --version node --version
npm --version npm --version
1 1
2 2
如果显示版本号（如 v18.x.x 或更高），说明安装成功。 如果显示版本号（如 v18.x.x 或更高），说明安装成功。
## 常见问题 ## 常见问题
### Homebrew 安装慢 ### Homebrew 安装慢
可以使用国内镜像： 可以使用国内镜像：
bash bash
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git" export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
1 1
### 权限问题 ### 权限问题
如果遇到权限问题，不要使用 `sudo`，而是修复 Homebrew 权限： 如果遇到权限问题，不要使用 `sudo`，而是修复 Homebrew 权限：
bash bash
sudo chown -R $(whoami) /usr/local/bin /usr/local/lib sudo chown -R $(whoami) /usr/local/bin /usr/local/lib
1 1
## 下一步 ## 下一步
✅ 环境准备完成！ ✅ 环境准备完成！
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。 现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
* [安装 Claude Code](</deploy/claude-code>) * [安装 Claude Code](</deploy/claude-code>)
* [安装 CodeX](</deploy/codex>) * [安装 CodeX](</deploy/codex>)
* [安装 Gemini CLI](</deploy/gemini-cli>) * [安装 Gemini CLI](</deploy/gemini-cli>)

176
apidoc/node/windows.md
View File

@ -1,88 +1,88 @@
# Windows 平台安装 Node.js # Windows 平台安装 Node.js
**三大 AI 编程工具的必备运行环境** **三大 AI 编程工具的必备运行环境**
💡 重要说明 💡 重要说明
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v` Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
## 方法一：官方安装包（推荐） ## 方法一：官方安装包（推荐）
1. 访问 Node.js 官网：<https://nodejs.org/zh-cn/download> 1. 访问 Node.js 官网：<https://nodejs.org/zh-cn/download>
2. 下载 LTS（长期支持）版本的 Windows Installer (.msi) 2. 下载 LTS（长期支持）版本的 Windows Installer (.msi)
3. 运行安装包，采用默认配置完成安装 3. 运行安装包，采用默认配置完成安装
4. 安装程序会自动配置系统 PATH 环境变量 4. 安装程序会自动配置系统 PATH 环境变量
![NodeJS下载页面](https://docs.ikuncode.cc/images/tu4.png) ![NodeJS下载页面](https://minio.oneinai.com/oneinai/images/docs/windows/windows01.png)
## 方法二：包管理器安装 ## 方法二：包管理器安装
### 使用 Winget ### 使用 Winget
Windows 11 或 Windows 10 最新版： Windows 11 或 Windows 10 最新版：
powershell powershell
winget install OpenJS.NodeJS.LTS winget install OpenJS.NodeJS.LTS
1 1
### 使用 Chocolatey ### 使用 Chocolatey
需先安装 Chocolatey： 需先安装 Chocolatey：
powershell powershell
choco install nodejs-lts choco install nodejs-lts
1 1
### 使用 Scoop ### 使用 Scoop
powershell powershell
scoop install nodejs-lts scoop install nodejs-lts
1 1
## 验证安装 ## 验证安装
打开命令提示符或 PowerShell，执行： 打开命令提示符或 PowerShell，执行：
powershell powershell
node --version node --version
npm --version npm --version
1 1
2 2
如果显示版本号（如 v18.x.x 或更高），说明安装成功。 如果显示版本号（如 v18.x.x 或更高），说明安装成功。
## 常见问题 ## 常见问题
### 提示"不是内部或外部命令" ### 提示"不是内部或外部命令"
* 重新打开终端窗口 * 重新打开终端窗口
* 检查 PATH 环境变量是否包含 Node.js 路径 * 检查 PATH 环境变量是否包含 Node.js 路径
* 重启电脑后再试 * 重启电脑后再试
### 安装失败 ### 安装失败
* 以管理员身份运行安装程序 * 以管理员身份运行安装程序
* 关闭杀毒软件后重试 * 关闭杀毒软件后重试
* 检查系统盘空间是否充足 * 检查系统盘空间是否充足
## 下一步 ## 下一步
✅ 环境准备完成！ ✅ 环境准备完成！
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。 现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
* [返回环境安装总览](</node/windows>) * [返回环境安装总览](</node/windows>)
* [安装 Claude Code](</deploy/claude-code>) * [安装 Claude Code](</deploy/claude-code>)
* [使用 CC-Switch 工具](</tools/cc-switch>) * [使用 CC-Switch 工具](</tools/cc-switch>)

202
apidoc/skills/ikuncode-aimcp.md
View File

@ -1,202 +0,0 @@
# ikuncode-aimcp - 统一 AI MCP 服务器
**一个二进制，三套 AI 引擎 — Gemini · Codex · Grok**
📋 简介
ikuncode-aimcp 是一个用 Rust 编写的统一 MCP 服务器，将 Gemini CLI、Codex CLI 和 Grok Search 整合到单个进程中。配置一次，即可在 Cursor / Windsurf / Claude Desktop 等任意 MCP 客户端中使用全部工具。
## 🔗 相关链接
资源| 地址
---|---
GitHub 仓库| [xuxu777xu/ikuncode-aimcp](<https://github.com/xuxu777xu/ikuncode-aimcp>)
ikun API| [api.ikuncode.cc](<https://api.oneinai.com>)
## ✨ 功能特点
* ✅ **一个二进制，全部工具** ：只需配置一个 MCP 服务器，取代三个独立安装
* ✅ **运行时检测** ：启动时自动检测可用工具，不可用的工具返回清晰错误信息
* ✅ **AdaptiveStdio 传输** ：自动检测 JSONL 和 LSP 帧格式，最大化客户端兼容性
* ✅ **纯 Rust GrokSearch** ：零 Python 依赖，通过 Grok API 实现 Web 搜索和内容抓取
* ✅ **Gemini 图像生成** ：内置 `gemini_image` 工具，支持宽高比和分辨率控制
## 🧰 工具列表
工具| 来源| 描述
---|---|---
`gemini`| Gemini CLI| AI 驱动的任务执行，支持会话连续性
`gemini_image`| Gemini CLI| AI 图像生成，使用专用生图模型
`codex`| Codex CLI| AI 辅助编码，支持沙箱策略
`web_search`| Grok API| Web 搜索，返回结构化 JSON 结果
`web_fetch`| Grok API| 抓取网页内容并转为 Markdown
`get_config_info`| Grok API| 显示配置信息并测试 API 连接
### 相关项目
项目| 类型| 适用场景
---|---|---
**ikuncode-aimcp** （本项目）| MCP Server| 所有 MCP 客户端通用，含 gemini_image 图像生成
[ikunimage](</skills/ikunimage>)| Claude Code Skill| Claude Code 专用 — 文生图 / 图生图 / 并发批量生成
## 🛠️ 安装
### 方式一：下载预编译二进制（推荐）
从 [GitHub Releases](<https://github.com/xuxu777xu/ikuncode-aimcp/releases>) 下载对应平台的二进制文件：
平台| 文件名
---|---
Windows x64| `ikuncode-aimcp-x86_64-pc-windows-msvc.exe`
macOS Apple Silicon| `ikuncode-aimcp-aarch64-apple-darwin`
macOS Intel| `ikuncode-aimcp-x86_64-apple-darwin`
Linux x64| `ikuncode-aimcp-x86_64-unknown-linux-gnu`
下载后放到 `PATH` 目录中即可使用。macOS / Linux 需要添加执行权限：
bash
chmod +x ikuncode-aimcp-*
mv ikuncode-aimcp-* /usr/local/bin/ikuncode-aimcp
1
2
### 方式二：npm 安装
bash
npm install -g ikuncode-aimcp
1
### 方式三：cargo 安装
bash
cargo install --git https://github.com/xuxu777xu/ikuncode-aimcp.git
1
### 方式四：从源码编译
bash
git clone https://github.com/xuxu777xu/ikuncode-aimcp.git
cd ikuncode-aimcp
cargo build --release
# 二进制文件在 target/release/ 目录下
1
2
3
4
## ⚙️ 配置 MCP 客户端
在你的 MCP 客户端（如 Claude Desktop、Cursor、Windsurf 等）中添加以下配置：
json
{
"mcpServers": {
"ikuncode-aimcp": {
"command": "ikuncode-aimcp",
"env": {
"GEMINI_API_KEY": "你的-gemini-api-key",
"GROK_API_KEY": "你的-grok-api-key"
}
}
}
}
1
2
3
4
5
6
7
8
9
10
11
⚠️ 环境变量说明
* `GEMINI_API_KEY`：用于 Gemini 相关工具（`gemini`、`gemini_image`）
* `GROK_API_KEY`：用于 Grok 搜索工具（`web_search`、`web_fetch`）
* Codex 工具使用独立配置，请参考 [Codex 部署文档](</deploy/codex>)
## 📖 工具使用说明
### gemini — AI 任务执行
参数| 必填| 类型| 默认值| 描述
---|---|---|---|---
`PROMPT`| 是| string| —| 发送给 Gemini 的任务指令
`sandbox`| 否| bool| false| 在沙箱模式下运行
`SESSION_ID`| 否| string| —| 恢复已有会话，用于多轮对话
`model`| 否| string| —| 模型覆盖
`timeout_secs`| 否| int| 600| 超时时间（1–3600 秒）
### gemini_image — 图像生成
参数| 必填| 类型| 默认值| 描述
---|---|---|---|---
`PROMPT`| 是| string| —| 图像生成指令
`model`| 否| string| —| 模型覆盖
`output_dir`| 否| string| —| 图片保存目录
`aspect_ratio`| 否| string| —| 宽高比（1:1 / 16:9 / 9:16 等）
`image_size`| 否| string| —| 分辨率（1K / 2K / 4K）
`timeout_secs`| 否| int| 600| 超时时间（1–3600 秒）
### codex — AI 辅助编码
参数| 必填| 类型| 默认值| 描述
---|---|---|---|---
`PROMPT`| 是| string| —| 发送给 Codex 的任务指令
`cd`| 是| string| —| 工作目录路径
`sandbox`| 否| string| `read-only`| 沙箱策略
### web_search — Web 搜索
参数| 必填| 类型| 默认值| 描述
---|---|---|---|---
`query`| 是| string| —| 自然语言搜索查询
`platform`| 否| string| —| 聚焦特定平台
`min_results`| 否| int| 3| 最少返回结果数
`max_results`| 否| int| 10| 最多返回结果数
### web_fetch — 网页内容抓取
参数| 必填| 类型| 默认值| 描述
---|---|---|---|---
`url`| 是| string| —| 有效的 HTTP/HTTPS 网址
### get_config_info — Grok 配置诊断
无参数。返回当前 Grok 配置信息并测试 API 连接。
## 常见问题
### 安装后命令找不到？
确认二进制文件已放到 `PATH` 目录中，且有执行权限。可运行 `which ikuncode-aimcp` 检查。
### Gemini 工具不可用？
检查 `GEMINI_API_KEY` 环境变量是否正确设置，以及本地是否安装了 Gemini CLI。
### Grok 搜索返回错误？
运行 `get_config_info` 工具检查 API 配置和连接状态。
### 更多问题
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。

312
apidoc/skills/ikunimage.md
View File

@ -1,312 +0,0 @@
# ikunimage - AI 图片生成器
**Claude Code Skill — 通过 ikun API 调用 Gemini 图像模型，支持文生图与图生图**
📋 简介
ikunimage 是一款 Claude Code Skill 插件，通过 [ikun API](<https://api.oneinai.com>) 调用 **NanoBananaPro（Gemini 3 Pro Image Preview）** 模型，在 Claude Code 对话中直接生成高质量图片。支持文生图、图生图编辑、批量并发等多种模式。
## 🔗 相关链接
资源| 地址
---|---
GitHub 仓库| [deijing/ikunimage](<https://github.com/deijing/ikunimage>)
ikun API| [api.ikuncode.cc](<https://api.oneinai.com>)
## ✨ 功能特点
* ✅ **文生图** ：用自然语言描述场景，AI 生成对应图片
* ✅ **图生图** ：上传本地图片 + 编辑描述，AI 修改生成新图片
* ✅ **10 种宽高比** ：1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 5:4 / 4:5
* ✅ **3 档分辨率** ：1K（快速预览）/ 2K（推荐）/ 4K（超高清）
* ✅ **文字渲染** ：支持在图片中渲染中文文字（招牌、海报、标语等）
* ✅ **并发批量** ：多张图片并发生成，大幅缩短总耗时
* ✅ **配置文件管理** ：API Key 存储在本地配置文件，安全便捷
## 📋 前置要求
* [Claude Code](<https://docs.anthropic.com/en/docs/claude-code>) CLI 已安装
* Python 3.10+
* ikun API Key（从 [api.ikuncode.cc](<https://api.oneinai.com>) 获取）
## 🛠️ 安装
### 第一步：下载 Skill
bash
# 如果目录不存在，先创建
mkdir -p ~/.claude/skills
# 克隆 ikunimage 到 skills 目录
cd ~/.claude/skills
git clone https://github.com/deijing/ikunimage.git
1
2
3
4
5
6
安装完成后目录结构如下：
~/.claude/skills/ikunimage/
├── SKILL.md # Skill 定义文件
├── scripts/
│ ├── generate_ikun.py # 文生图脚本
│ └── generate_ikun_edit.py # 图生图脚本
└── references/
└── api-reference.md # API 参考文档
1
2
3
4
5
6
7
### 第二步：安装依赖
bash
pip install httpx
1
### 第三步：配置 API Key
三种方式任选其一：
**方式 A：交互式配置（推荐）**
bash
python ~/.claude/skills/ikunimage/scripts/generate_ikun.py --setup
1
按提示输入你的 API Key 即可，配置会保存到 `~/.ikunimage/config.json`。
**方式 B：手动创建配置文件**
bash
mkdir -p ~/.ikunimage
echo '{"api_key": "sk-你的key"}' > ~/.ikunimage/config.json
1
2
**方式 C：环境变量**
bash
export IKUN_API_KEY="sk-你的key"
1
💡 API Key 加载优先级
`--api-key` 命令行参数 > `IKUN_API_KEY` 环境变量 > `~/.ikunimage/config.json` 配置文件
## 📖 使用方法
### 在 Claude Code 中使用
安装配置完成后，在 Claude Code 对话中输入：
/ikunimage
1
然后描述你想要的图片即可。例如：
* "画一张江南水乡的风景"
* "生成一张 4K 超宽屏的故宫雪景"
* "批量生成 5 张不同风格的古风人像"
图生图编辑：
* "编辑 /path/to/photo.jpg，把背景改成竹林"
### 独立脚本使用
也可以脱离 Claude Code，直接在命令行中调用。
**文生图** ：
bash
python ~/.claude/skills/ikunimage/scripts/generate_ikun.py \\
-p "一位中国女性，身穿汉服，站在竹林中，晨雾缭绕" \\
-ar 3:4 \\
-s 2K \\
-o ./output.png
1
2
3
4
5
**图生图** ：
bash
python ~/.claude/skills/ikunimage/scripts/generate_ikun_edit.py \\
-i ./photo.jpg \\
-p "将背景改为雪景，保持人物不变" \\
-ar 3:4 \\
-o ./edited.png
1
2
3
4
5
**批量生成** ：
bash
# 准备任务文件 tasks.json
cat > tasks.json << 'EOF'
[
{"prompt": "描述1", "aspect_ratio": "3:4", "size": "2K", "output": "./out1.png"},
{"prompt": "描述2", "aspect_ratio": "16:9", "size": "1K", "output": "./out2.png"}
]
EOF
# 执行批量生成
python ~/.claude/skills/ikunimage/scripts/generate_ikun.py \\
--batch tasks.json \\
--workers 2
1
2
3
4
5
6
7
8
9
10
11
12
## 📐 参数速查
### 文生图 (generate_ikun.py)
参数| 简写| 说明| 默认值
---|---|---|---
`--setup`| | 交互式配置 API Key|
`--api-key`| | 指定 API Key| 从配置加载
`--prompt`| `-p`| 图片描述（必填）|
`--aspect-ratio`| `-ar`| 宽高比| `1:1`
`--size`| `-s`| 分辨率（1K/2K/4K）| `2K`
`--output`| `-o`| 输出路径| `output.png`
`--batch`| `-b`| 批量任务 JSON 文件|
`--workers`| `-w`| 并发数| 自动（默认 2）
`--retry`| `-r`| 重试次数（0-10）| `3`
### 图生图 (generate_ikun_edit.py)
参数| 简写| 说明| 默认值
---|---|---|---
`--setup`| | 交互式配置 API Key|
`--api-key`| | 指定 API Key| 从配置加载
`--input`| `-i`| 输入图片路径（必填）|
`--prompt`| `-p`| 编辑描述（必填）|
`--aspect-ratio`| `-ar`| 输出宽高比| `1:1`
`--output`| `-o`| 输出路径| `output.png`
`--batch`| `-b`| 批量任务 JSON 文件|
`--workers`| `-w`| 并发数| 自动（默认 2）
`--retry`| `-r`| 重试次数（0-10）| `3`
⚠️ 互斥参数
`--prompt` 和 `--batch` 互斥，单图模式和批量模式必须二选一。
## 📊 分辨率参考
### 1K（快速预览）
宽高比| 分辨率
---|---
1:1| 1024×1024
16:9| 1376×768
9:16| 768×1376
4:3| 1200×896
3:4| 896×1200
### 2K（推荐）
宽高比| 分辨率
---|---
1:1| 2048×2048
16:9| 2752×1536
9:16| 1536×2752
4:3| 2400×1792
3:4| 1792×2400
### 4K（超高清）
宽高比| 分辨率
---|---
1:1| 4096×4096
16:9| 5504×3072
9:16| 3072×5504
4:3| 4800×3584
3:4| 3584×4800
## 🖼️ 图生图支持格式
格式| 支持| 备注
---|---|---
JPG / JPEG| ✅| 推荐
PNG| ✅| 推荐
WebP| ✅|
GIF| ✅| 仅使用第一帧
💡 建议
图片大小推荐 < 4MB，过大可能导致上传变慢或超时。
## 常见问题
### 提示 "未找到 API Key"？
运行交互式配置命令：
bash
python ~/.claude/skills/ikunimage/scripts/generate_ikun.py --setup
1
### 请求超时？
4K 图片生成较慢，脚本已设置充足的超时时间。如果仍然超时，可降低分辨率到 2K 或 1K。
### 收到 429 错误？
触发了 API 频率限制。脚本会自动指数退避重试（默认 3 次）。可加 `--retry 5` 增加重试次数。
### 更多问题
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。

89
apidoc/support/after-sales.md
View File

@ -1,89 +0,0 @@
# 售前售后
有任何不懂的，可以进群咨询，可提供人工一对一服务。
## 联系方式
### Telegram 群组
**推荐方式** ：加入我们的 Telegram 群组，快速获得帮助。
* **群组链接** ：<https://t.me/ikuncode>
群内可以：
* 咨询使用问题
* 反馈bug和建议
* 获取最新消息
* 与其他用户交流
### QQ 群
* **QQ 群号** ：请扫描下方二维码加入
### 扫码加群
![联系方式二维码](https://docs.ikuncode.cc/images/tu5.png)
## 服务时间
* **工作日** ：9:00 - 00:00
* **节假日** ：11:00 - 00:00
💡 提示
紧急问题建议在工作时间联系，响应更快。
## 服务内容
### 售前咨询
* 产品功能介绍
* 价格方案说明
* 技术可行性咨询
* 企业方案定制
### 售后支持
* 使用问题解答
* 技术故障排查
* 配置指导
* 一对一人工服务
### 企业服务
如需企业服务，请联系客服
## 常见问题快速通道
在联系客服前，建议先查看：
* [常见问题 FAQ](</support/faq>)
* [部署指南](</deploy/claude-code>)
* [配置工具](</tools/cc-switch>)
## 反馈建议
我们欢迎您的反馈和建议：
* 功能需求
* 使用体验
* 问题反馈
* 改进建议
所有反馈都会认真对待，帮助我们持续改进服务。
## 服务承诺
💪 我们的承诺
* **真诚服务** ：坦诚沟通，不夸大宣传
* **热爱产品** ：持续优化，追求卓越
* **快速响应** ：及时处理问题和反馈
* **用户至上** ：以用户体验为中心
* * *
OneinAI - 真诚 热爱
我们希望能和用户交朋友

179
apidoc/support/faq.md
View File

@ -1,159 +1,148 @@
# 常见问题（FAQ） # 常见问题（FAQ）
## 账号与 Key ## 账号与 Key
### 1\. 可以开发票对吧？ ### 1. 可以开发票吗？
对。支持普票、专票。累计充值满500元可提交开发票需求。 可以，支持普票和专票。累计充值满 500 元可提交开票需求。
### 2\. Key 无效/鉴权失败怎么办？ ### 2. Key 无效 / 鉴权失败怎么办？
* 检查是否复制了多余空格 - 检查是否复制了多余空格
* 检查 Key 是否过期/被禁用 - 检查 Key 是否过期或被禁用
* 检查请求是否使用了正确的 Header/参数 - 检查请求是否使用了正确的 Header / 参数
* 确认使用了对应工具的专用令牌组 - 确认使用了对应工具的专用令牌组
### 3\. 如何查看余额和消费记录？ ### 3. 如何查看余额和消费记录？
登录控制台即可查看： 登录 [oneinai 控制台](https://api.oneinai.com/console/token) 即可查看：
* 当前余额 - 当前余额
* 充值记录 - 充值记录
* 消费明细 - 消费明细
* 账单详情 - 账单详情
## 网站访问 ## 网站访问
### 网站进入为什么白屏？ ### 网站打开为什么白屏？
很有可能是你的广告过滤插件导致，请手动将我们的域名添加到白名单。 很可能是浏览器的广告过滤插件导致，请手动将我们的域名添加到白名单。
常见的广告过滤插件： 常见的广告过滤插件：
* AdBlock - AdBlock
* uBlock Origin - uBlock Origin
* AdGuard - AdGuard
解决方法： 解决方法：
1. 打开插件设置 1. 打开插件设置
2. 添加 `api.ikuncode.cc` 到白名单 2. 将 `api.oneinai.com` 添加到白名单
3. 刷新页面 3. 刷新页面
4. 尝试浏览器强制刷新（Windows：`Ctrl + Shift + R`，macOS：`Cmd + Shift + R`） 4. 必要时使用浏览器强制刷新（Windows：`Ctrl + Shift + R`，macOS：`Cmd + Shift + R`）
## 环境与安装 ## 环境与安装
### npm 安装很慢/失败？ ### npm 安装很慢 / 失败？
可以使用国内镜像： 可以切换为国内镜像：
bash ```bash
# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com
# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com
# 验证配置
npm config get registry
1 # 验证配置
2 npm config get registry
3 ```
4
5
### Node.js 版本过低怎么办？ ### Node.js 版本过低怎么办？
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 版本。 Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 版本。
升级方法： 升级方法：
* Windows: 重新下载安装最新版本 - **Windows**：重新下载安装最新版本
* macOS: `brew upgrade node` - **macOS**：`brew upgrade node`
* Linux: 使用 nvm 或 NodeSource 仓库 - **Linux**：使用 nvm 或 NodeSource 仓库
### 环境变量设置后不生效？ ### 环境变量设置后不生效？
* Windows: 重启终端窗口或重启电脑 - **Windows**：重启终端窗口或重启电脑
* macOS/Linux: 执行 `source ~/.bashrc` 或 `source ~/.zshrc` - **macOS / Linux**：执行 `source ~/.bashrc` 或 `source ~/.zshrc`
## 工具使用 ## 工具使用
### CC-Switch 无法启动？ ### CC-Switch 无法启动？
1. 检查是否有权限问题 1. 检查是否有权限问题
2. 尝试以管理员身份运行 2. 尝试以管理员身份运行
3. 查看是否有杀毒软件拦截 3. 查看是否有杀毒软件拦截
4. 重新下载安装最新版本 4. 重新下载安装最新版本
### Claude Code 提示连接失败？ ### Claude Code 提示连接失败？
检查项： 请按顺序排查：
* 网络连接是否正常 - 网络连接是否正常
* API 密钥是否正确 - API 密钥是否正确
* 环境变量是否设置正确 - 环境变量是否设置正确
* 余额是否充足 - 余额是否充足
### CodeX 和 Claude Code 的令牌不通用？ ### CodeX 和 Claude Code 的令牌不通用？
是的，不同工具需要不同的令牌组： 是的，不同工具需要不同的令牌组：
* Claude Code: 使用 Claude Code 令牌组 - **Claude Code**：使用 Claude Code 令牌组
* CodeX: 使用 "codex测试" 令牌组 - **CodeX**：使用 `codex` 令牌组
* Gemini CLI: 使用 Gemini 令牌组 - **Gemini CLI**：使用 Gemini 令牌组
请在 IkunCode 平台创建对应的专用令牌。 请在 oneinai 平台创建对应的专用令牌。
## 计费相关 ## 计费相关
### 如何计费？ ### 如何计费？
* 按实际使用量计费 - 按实际使用量计费
* 不同模型价格不同 - 不同模型价格不同
* 详细计费规则请查看控制台 - 详细计费规则请查看控制台
### 余额不足会怎样？ ### 余额不足会怎样？
* 服务会暂停 - 服务会暂停
* 请及时充值以继续使用 - 请及时充值以继续使用
* 充值后立即恢复服务 - 充值后立即恢复服务
### 支持退款吗？ ### 支持退款吗？
* 未使用的余额可以申请退款 - 未使用的余额可以申请退款
* 已使用的部分不支持退款 - 已使用的部分不支持退款
* 具体政策请咨询客服 - 具体政策请咨询客服
## 技术问题 ## 技术问题
### 代码会被保存吗？ ### 代码会被保存吗？
不会。我们不会存储您的代码内容，仅转发请求和响应。 不会。我们不会存储你的代码内容，仅转发请求与响应。
### 是否支持企业使用？ ### 是否支持企业使用？
支持。企业用户可以： 支持。企业用户可以：
* 联系客服获取企业方案 - 联系客服获取企业方案
* 支持大额充值和发票 - 支持大额充值和开票
* 可能享受优惠价格 - 可能享受优惠价格
### 如何获得技术支持？
请查看[售前售后](</support/after-sales>)页面获取联系方式。 ## 更多问题
## 更多问题 ### 遇到技术难题？
### 遇到技术难题？
如果遇到启动失败、报错、超时等技术问题，请查看： 如果遇到启动失败、报错、超时等技术问题，请查看：
👉 **[疑难杂症排查指南](</support/troubleshooting>)** \- 详细的错误排查和解决方案 👉 **[疑难杂症排查指南](/support/troubleshooting)** - 详细的错误排查与解决方案
### 仍未解决？ ### 仍未解决？
如果上述问题没有解决您的疑问，请： 如果上述内容没有解决你的疑问，请联系我们：
* 加入 Telegram 群组：<https://t.me/ikuncode> - 加入 Telegram 群组：<https://t.me/oneinai>
* 查看[售前售后](</support/after-sales>)联系客服

274
apidoc/support/troubleshooting.md
View File

@ -1,249 +1,205 @@
# 疑难杂症排查指南 # 疑难杂症排查指南
本文档汇总了 Claude Code、CodeX、Gemini CLI 等 AI 编程工具的常见问题和解决方案。 本文档汇总了 Claude Code、CodeX、Gemini CLI 等 AI 编程工具在使用 oneinai 服务时的常见问题与解决方案。
## 🔍 服务状态查看 ## 服务状态查看
在排查问题前，建议先查看服务状态： 排查问题前，建议先确认 oneinai 服务是否正常：
**服务分组状态页** ：<https://status.ikuncode.cc/> **服务分组状态页**：<https://status.oneinai.cc/>
* * * ---
## 一、Claude Code 启动时跳登录 ## 一、Claude Code 启动时反复跳登录
### 问题描述 ### 问题描述
启动 Claude Code 时，反复弹出登录界面。 启动 Claude Code 时，反复弹出登录界面，无法进入正常使用状态。
### 解决方案 ### 解决方案
#### 方案一：使用 CC-Switch 跳过功能 #### 方案一：使用 CC-Switch 跳过功能
打开 CC-Switch，进入「设置」-「通用」，在「窗口行为」中开启「跳过初次安装确认」开关，即可绕过反复弹出的登录界面。 打开 CC-Switch，进入「设置」-「通用」，在「窗口行为」中开启「跳过初次安装确认」开关，即可绕过反复弹出的登录界面。
详细步骤参见：[CC-Switch 初始化设置](</tools/cc-switch#第一步：初始化设置>) 详细步骤参见：[CC-Switch 初始化设置](</tools/cc-switch#第一步：初始化设置>)
#### 方案二：手动修改配置文件 #### 方案二：手动修改配置文件
参考教程：<https://www.cnblogs.com/gordonMlxg/articles/19103691> 参考教程：<https://www.cnblogs.com/gordonMlxg/articles/19103691>
* * * ---
## 四、API Connect Error 排查 ## 二、API Connect Error 排查
### 排查方向 ### 排查方向
1. **本地网络异常** 1. **本地网络异常**
- 检查网络连接是否正常
- 尝试访问其他网站验证网络可达性
* 检查网络连接是否正常 2. **代理 / 梯子不稳定**
* 尝试访问其他网站验证网络 - 检查代理配置是否正确
2. **代理/梯子不稳定** - 尝试切换代理节点
* 检查代理配置 ### 建议
* 尝试切换代理节点
### 建议 **优先尝试直连网络**：关闭代理后测试是否恢复正常。若直连可用，说明问题出在代理链路上。
👉 **尝试直接使用直连网络** ---
关闭代理后测试是否恢复正常。 ## 三、上下文过大导致异常
* * * ### 问题表现
## 八、CC 上下文过大导致异常 对话中出现异常错误，通常表现为响应失败或返回乱码，多与上下文过大有关。
### 问题表现 ### 解决方案
对话中出现异常错误，通常与上下文过大有关。 1. **新建会话**：开启新的对话，清空上下文。
2. **查看 Token 分布**：执行 `/context` 命令查看当前上下文的 Token 使用情况。
3. **关闭自动压缩**：关闭 Auto Compress 功能，手动控制上下文大小。
### 解决方案 ---
1. **新建会话** ## 四、Request Timed Out（请求超时）
* 开启新的对话，清空上下文 ### 可能原因
2. **查看 Token 分布**
/context
1 1. 本地网络连接问题
2. 代理或梯子状态不稳定
3. 服务端负载过高
查看当前上下文的 Token 使用情况 ### 解决方案
3. **关闭自动压缩** - 检查本地网络连接
- 检查代理或梯子状态
- 必要时切换至直连网络
- 查看 [oneinai 服务状态页](<https://status.oneinai.cc/status/api>) 确认服务可用性
* 关闭 Auto Compress（自动压缩）功能 ---
* 手动控制上下文大小
* * * ## 五、API Error 503
## 九、Request Timed Out（请求超时） ### 错误说明
### 可能原因 当前 oneinai 分组服务暂时不可用。
1. 本地网络连接问题 ### 解决方案
2. 代理或梯子状态不稳定
3. 服务端负载过高
### 解决方案 1. 切换至其他可用的服务分组
2. 通过状态页确认分组的实时状态
* 检查本地网络连接 **服务状态查看**：<https://status.oneinai.cc/status/api>
* 检查代理或梯子状态
* 必要时尝试直连网络
* 查看[服务状态页](<https://status.ikuncode.cc/status/api>)确认服务可用性
* * * ---
## 十、API Error 503 ## 六、Gemini CLI 报错 400
### 错误说明 ### 问题说明
当前分组服务不可用。
### 解决方案
1. 切换至其他可用服务分组
2. 通过状态页确认分组状态
**服务状态查看** ：<https://status.ikuncode.cc/status/api>
* * *
## 十一、Gemini CLI 报错 400
### 问题说明
当前会话异常，通常是会话状态错误导致。 当前会话异常，通常是会话状态错误导致。
### 解决方案 ### 解决方案
直接重开会话即可解决。 直接重开会话即可解决。
* * * ---
## 十二、Claude Code 2.0.73 版本内容割裂 ## 七、Claude Code 2.0.73 版本内容割裂
### 问题说明 ### 问题说明
在 2.0.73 版本中出现对话/内容割裂问题。 在 2.0.73 版本中出现对话 / 内容割裂的问题。
### 解决方案：回退版本 ### 解决方案：回退版本
bash ```bash
npm install -g @anthropic-ai/claude-code@2.0.72
```
npm install -g @anthropic-ai/claude-code@2.0.72
1 回退到稳定的 2.0.72 版本即可恢复。
回退到稳定的 2.0.72 版本。 ---
* * * ## 八、关闭 Claude Code 自动更新
## 十三、如何关闭 Claude Code 自动更新 ### 问题描述
### 问题描述
不希望 Claude Code 自动更新到新版本。 不希望 Claude Code 自动更新到新版本。
### 解决方案 ### 解决方案
在 `settings.json` 中添加以下环境变量： 在 `settings.json` 中添加以下环境变量：
json ```json
{
"env": {
{ "DISABLE_AUTOUPDATER": "1"
"env": { }
"DISABLE_AUTOUPDATER": "1" }
} ```
}
1
2
3
4
5
或在系统环境变量中设置： 或在系统环境变量中设置：
bash ```bash
# macOS / Linux
export DISABLE_AUTOUPDATER=1
# macOS/Linux ```
export DISABLE_AUTOUPDATER=1
# Windows PowerShell
$Env:DISABLE_AUTOUPDATER = "1"
1 ```powershell
2 # Windows PowerShell
3 $Env:DISABLE_AUTOUPDATER = "1"
4 ```
5
* * * ---
## 🔧 排查技巧总结 ## 排查技巧总结
### 快速诊断流程 ### 快速诊断流程
1. ✅ 查看[服务状态页](<https://status.ikuncode.cc/status/api>) 1. 查看 [oneinai 服务状态页](<https://status.oneinai.cc/status/api>)
2. ✅ 检查环境变量配置 2. 检查环境变量配置
3. ✅ 验证令牌是否有效 3. 验证令牌是否有效
4. ✅ 检查网络和代理状态 4. 检查网络和代理状态
5. ✅ 查看 Token 余额 5. 查看 Token 余额
6. ✅ 尝试重新开启会话 6. 尝试重新开启会话
### 常用调试命令 ### 常用调试命令
#### Claude Code #### Claude Code
bash ```bash
/status # 查看当前会话状态
/context # 查看上下文 Token 使用
/status # 查看当前会话状态 /clear # 清空当前会话
/context # 查看上下文 Token 使用 ```
/clear # 清空当前会话
1 ### 环境变量检查
2
3
### 环境变量检查 #### Windows
#### Windows ```powershell
# 查看所有 ANTHROPIC 相关变量
Get-ChildItem Env: | Where-Object { $_.Name -like "*ANTHROPIC*" }
```
powershell #### macOS / Linux
# 查看所有 ANTHROPIC 相关变量
Get-ChildItem Env: | Where-Object {$_.Name -like "*ANTHROPIC*"}
1 ```bash
2 # 查看所有 ANTHROPIC 相关变量
env | grep ANTHROPIC
```
#### macOS/Linux ---
bash ## 获取帮助
# 查看所有 ANTHROPIC 相关变量
env | grep ANTHROPIC
1
2
* * *
## 📮 获取帮助
如果以上方法都无法解决您的问题，请： 如果以上方法都无法解决您的问题，请：
* 📧 查看[售前售后](</support/after-sales>)联系客服 - 加入 Telegram 群组：<https://t.me/oneinai>
* 💬 加入 Telegram 群组：<https://t.me/ikuncode> - 查看 [常见问题 FAQ](</support/faq>)
* 📖 查看[常见问题 FAQ](</support/faq>)
* * * ---
_本文档持续更新中，如有新的疑难杂症欢迎反馈..._ _本文档持续更新中，如有新的疑难杂症欢迎反馈。_

219
apidoc/tools/cc-switch.md
View File

@ -1,162 +1,171 @@
# CC-Switch 快速配置工具 # CC-Switch 快速配置工具
**All-in-One AI CLI 管理器 - 桌面应用程序** **All-in-One AI CLI 管理器 — 跨平台桌面应用**
## 🔗 相关链接 ## 🔗 相关链接
资源| 地址 | 资源 | 地址 |
---|--- | --- | --- |
GitHub 发布页| [cc-switch/releases](<https://github.com/farion1231/cc-switch/releases>) | GitHub 发布页 | [cc-switch/releases](https://github.com/farion1231/cc-switch/releases) |
CC-Switch 文档站| [ccswitch.lovable.app](<https://ccswitch.lovable.app/>) | CC-Switch 文档站 | [ccswitch.io](https://www.ccswitch.io/zh/docs) |
| oneinai 控制台 | <https://api.oneinai.com/console/token> |
## 🎯 工具介绍
CC-Switch 是一款跨平台桌面应用程序，统一管理 Claude Code、Codex 和 Gemini CLI 三大 AI 编程工具。通过直观的图形界面，实现配置切换、MCP 服务器管理、系统提示和 Claude Skills 管理。 ## 🎯 工具介绍
💡 核心功能 CC-Switch 是一款跨平台桌面应用，统一管理 **Claude Code**、**Codex** 和 **Gemini CLI** 三大 AI 编程工具。通过直观的图形界面，让你在多个供应商配置之间一键切换，并集中管理 MCP 服务器、系统提示和 Claude Skills。
• 一键切换不同 AI 工具的提供商配置 • API 端点速度测试与质量指示器 • 多预设系统提示管理 • MCP 服务器统一架构管理 • Claude Skills 发现与安装系统 • 配置备份/恢复（自动保留最近10个） • 深度链接协议支持（`ccswitch://`） • 环境变量冲突检测 > 💡 **核心功能**
> - 一键切换不同 AI 工具的供应商配置
> - API 端点速度测试与质量指示器
> - 多预设系统提示管理
> - MCP 服务器统一架构管理
> - Claude Skills 发现与安装系统
> - 配置自动备份与恢复（保留最近 10 个）
> - 深度链接协议支持（`ccswitch://`）
> - 环境变量冲突检测
![CC-Switch 软件界面](https://docs.ikuncode.cc/images/tu6.png) ![CC-Switch 软件界面](https://minio.oneinai.com/oneinai/images/docs/cc-switch/cc-switch01.png)
## 📦 安装方法 ## 📦 安装方法
### 🖥️ Windows 平台 ### 🖥️ Windows 平台
#### 方法一：MSI 安装器（推荐） **方法一：MSI 安装器（推荐）**
1. 访问项目发布页：<https://github.com/farion1231/cc-switch/releases> 1. 访问 [Releases 页面](https://github.com/farion1231/cc-switch/releases)
2. 下载最新版本的 `.msi` 安装器 2. 下载最新版本的 `.msi` 安装器
3. 运行安装器，按照向导完成安装 3. 运行安装器，按向导完成安装
4. 安装完成后从开始菜单启动 CC-Switch 4. 从开始菜单启动 CC-Switch
#### 方法二：便携版（无需安装） **方法二：便携版（免安装）**
1. 下载 `.zip` 便携版压缩包 1. 下载 `.zip` 便携版压缩包
2. 解压到任意目录 2. 解压到任意目录
3. 运行 `cc-switch.exe` 即可使用 3. 双击 `cc-switch.exe` 即可使用
### 🍏 macOS 平台 ### 🍏 macOS 平台
#### 推荐方式：Homebrew 安装 **推荐方式：Homebrew 安装**
bash ```bash
# 添加 tap 源
brew tap farion1231/ccswitch
# 添加 tap 源
brew tap farion1231/ccswitch
# 安装 cc-switch
brew install --cask cc-switch
1 # 安装 cc-switch
2 brew install --cask cc-switch
3 ```
4
5
#### 手动安装 **手动安装**
1. 访问 [Releases 页面](<https://github.com/farion1231/cc-switch/releases>) 1. 访问 [Releases 页面](https://github.com/farion1231/cc-switch/releases)
2. 下载 `.dmg` 安装包 2. 下载 `.dmg` 安装包
3. 打开 DMG 文件，将 CC-Switch 拖入应用程序文件夹 3. 打开 DMG，将 CC-Switch 拖入「应用程序」文件夹
4. 从启动台或应用程序文件夹启动 4. 从启动台或「应用程序」启动
### 🐧 Linux 平台 ### 🐧 Linux 平台
#### Debian/Ubuntu 系列（推荐） **Debian / Ubuntu 系列（推荐）**
bash ```bash
sudo dpkg -i cc-switch_*.deb
sudo apt-get install -f # 修复依赖
sudo dpkg -i cc-switch_*.deb ```
sudo apt-get install -f # 修复依赖
1 **AppImage 通用版本**
2
#### AppImage 通用版本 ```bash
chmod +x cc-switch_*.AppImage
./cc-switch_*.AppImage
```
bash **Arch Linux（AUR）**
chmod +x cc-switch_*.AppImage
./cc-switch_*.AppImage
1 ```bash
2 paru -S cc-switch-bin
# 或使用 yay
yay -S cc-switch-bin
```
#### Arch Linux（AUR） ## 🚀 快速开始
bash ### 第一步：初始化设置
paru -S cc-switch-bin
# 或使用 yay
yay -S cc-switch-bin
1 打开 CC-Switch，进入「设置 → 通用」，将「窗口行为」中的所有开关全部启用，确保自启动、Claude Code 插件集成、托盘最小化等功能正常生效。
2
3
## 🚀 快速开始 ![CC-Switch 初始化设置界面](https://minio.oneinai.com/oneinai/images/docs/cc-switch/cc-switch02.png)
### 第一步：初始化设置 > 💡 **推荐配置**
> 建议启用以下选项以获得最佳体验：
> - 开机自启
> - 静默启动
> - 应用到 Claude Code 插件
> - 跳过初次安装确认
> - 关闭时最小化到托盘
打开 CC-Switch，进入「设置」页面，在「通用」标签下将「窗口行为」中的所有开关全部打开，确保自启动、Claude Code 插件集成、托盘最小化等功能正常生效。 ### 第二步：添加供应商配置
![CC-Switch 初始化设置界面](https://docs.ikuncode.cc/images/cc-switch-init-settings.png) **1. 添加 Claude / Gemini 供应商**
💡 推荐配置 点击右上角的「+」按钮，进入添加面板。
建议将「窗口行为」中的所有开关全部启用，以获得最佳使用体验：开机自启、静默启动、应用到 Claude Code 插件、跳过初次安装确认、关闭时最小化到托盘。 ![添加 Claude / Gemini 供应商](https://minio.oneinai.com/oneinai/images/docs/cc-switch/cc-switch03.png)
### 第二步：添加提供商配置 > 💡 **Gemini 用户提示**
> 使用 Gemini CLI 时，请在 oneinai 平台创建 **Gemini 分组**的令牌，而非 Claude 分组。
1. 点击右上角的加号按钮来添加提供商(Claude/Gemini) **2. 添加 Codex 供应商**
![添加新供应商配置界面](https://docs.ikuncode.cc/images/cc-switch-add-provider.png) 切换到 Codex 标签后，同样点击右上角「+」按钮添加。
💡 Gemini 用户 ![添加 Codex 供应商](https://minio.oneinai.com/oneinai/images/docs/cc-switch/cc-switch04.png)
如果使用的是 Gemini CLI，请在平台创建**对应的** 令牌，而非 Claude 分组。 **3. 保存配置**
2. 点击右上角的加号按钮来添加提供商(Codex) 填写完成后点击「保存」即可。
![添加新供应商配置界面](https://docs.ikuncode.cc/images/cc-switch-add-provider2.png) > ⚠️ **重要提示**
> 不同 AI 工具（Claude Code / Codex / Gemini CLI）需要使用**不同的令牌组**。请在[监测站](https://status.oneinai.com/)中确认模型状态后，再选择合适的分组创建令牌。
3. 点击「保存」完成配置 ### 第三步：切换供应商
⚠️ 重要提示 | 操作方式 | 步骤 |
| --- | --- |
| **应用内切换** | 在供应商列表中选择目标配置 → 点击「启用」 |
| **托盘快捷切换** | 右键点击托盘图标 → 选择对应工具的供应商 |
不同的AI工具（Claude Code、Codex、Gemini CLI）需要不同的令牌组配置。 请在[监测站](<https://status.ikuncode.cc/>)中选择合适的分组创建令牌。 > ℹ️ **生效说明**
> Claude Code 支持热重载，切换后立即生效；Codex 和 Gemini CLI 需要重启工具才能应用新配置。
### 第三步：切换提供商 ### 第四步：开始使用
1. 在提供商列表中选择要使用的配置 切换完成后，启动对应的 AI 工具即可享受新配置。
2. 点击「启用」按钮
3. **或** 使用系统托盘图标进行即时切换
**系统托盘快速切换：** ## 📖 进阶使用
* 右键点击系统托盘中的 CC-Switch 图标 ### 系统托盘菜单
* 从菜单中直接选择要切换的提供商
* 配置立即生效（Claude Code支持热重载，其它的可能需要重新启动）
### 第四步：应用配置 - 右键点击托盘图标可看到分类列表（Claude / Codex / Gemini）
- 直接点击对应分类下的供应商即可切换
- 无需打开主界面，提升日常切换效率
切换配置后，关闭并重新启动对应的 AI 工具即可自动应用新配置。 ### API 速度测试
## 📖 完整文档 在供应商详情页可以一键测试 API 端点的连接速度，并以颜色直观展示质量等级，帮你快速选出最优节点。
更多详细配置和高级功能，请参阅 [CC-Switch 官方完整文档](<https://www.ccswitch.io/zh/docs?section=getting-started>)。 ### 配置备份与恢复
## 🔗 项目资源 CC-Switch 会自动保留最近 10 个配置版本，意外修改后可一键回滚到任意历史版本。
* **GitHub 仓库** ：<https://github.com/farion1231/cc-switch> ## 📚 完整文档
* **问题反馈** ：[GitHub Issues](<https://github.com/farion1231/cc-switch/issues>)
* **最新版本** ：[Releases 页面](<https://github.com/farion1231/cc-switch/releases>)
🎉 开始使用！ 更多高级功能与详细说明，请参阅 [CC-Switch 官方文档](https://www.ccswitch.io/zh/docs)。
现在您可以使用 CC-Switch 轻松管理多个 AI 编程工具的配置了。 享受高效的开发体验！ ## 🔗 项目资源
- **GitHub 仓库**：<https://github.com/farion1231/cc-switch>
- **问题反馈**：[GitHub Issues](https://github.com/farion1231/cc-switch/issues)
- **最新版本**：[Releases 页面](https://github.com/farion1231/cc-switch/releases)
---
🎉 **开始使用！** 现在你可以用 CC-Switch 轻松管理多个 AI 编程工具的配置，享受高效的开发体验。

124
apidoc/tools/claude-code-hub.md
View File

@ -1,62 +1,62 @@
# Claude Code Hub (CCH) # Claude Code Hub (CCH)
**团队级多供应商 AI Coding 代理调度平台** **团队级多供应商 AI Coding 代理调度平台**
## 🔗 相关链接 ## 🔗 相关链接
资源| 地址 资源| 地址
---|--- ---|---
官网| [claude-code-hub.app](<https://claude-code-hub.app/>) 官网| [claude-code-hub.app](<https://claude-code-hub.app/>)
官方文档| [claude-code-hub.app/docs](<https://claude-code-hub.app/docs>) 官方文档| [claude-code-hub.app/docs](<https://claude-code-hub.app/docs>)
GitHub| [ding113/claude-code-hub](<https://github.com/ding113/claude-code-hub>) GitHub| [ding113/claude-code-hub](<https://github.com/ding113/claude-code-hub>)
## 🎯 工具介绍 ## 🎯 工具介绍
Claude Code Hub (CCH) 是一个服务器部署的多租户 AI Coding 工具调度平台，帮助团队统一管理 Claude、Codex、Gemini 等多家 AI 服务商，实现智能负载均衡与自动故障转移。 Claude Code Hub (CCH) 是一个服务器部署的多租户 AI Coding 工具调度平台，帮助团队统一管理 Claude、Codex、Gemini 等多家 AI 服务商，实现智能负载均衡与自动故障转移。
💡 适用场景 💡 适用场景
* **敏捷开发团队** ：多人共用 AI 工具，需要统一管理和用量追踪 * **敏捷开发团队** ：多人共用 AI 工具，需要统一管理和用量追踪
* **AI 驱动开发团队** ：重度依赖 AI Coding，需要高可用和自动故障转移 * **AI 驱动开发团队** ：重度依赖 AI Coding，需要高可用和自动故障转移
* **创业公司** ：预算有限，需要精细的成本控制和多维限流 * **创业公司** ：预算有限，需要精细的成本控制和多维限流
* **中小软件公司** ：需要合规审计、访问控制和完整日志 * **中小软件公司** ：需要合规审计、访问控制和完整日志
## ✨ 核心功能 ## ✨ 核心功能
* **智能负载均衡** ：权重 + 优先级 + 分组调度，内置熔断保护与最多 3 次自动故障转移 * **智能负载均衡** ：权重 + 优先级 + 分组调度，内置熔断保护与最多 3 次自动故障转移
* **多供应商管理** ：同时接入 Claude、Codex、Gemini、OpenAI Compatible 等多种供应商 * **多供应商管理** ：同时接入 Claude、Codex、Gemini、OpenAI Compatible 等多种供应商
* **限流与并发控制** ：支持 RPM（每分钟请求数）、金额限制（5小时/周/月）、并发 Session 控制 * **限流与并发控制** ：支持 RPM（每分钟请求数）、金额限制（5小时/周/月）、并发 Session 控制
* **实时监控与统计** ：仪表盘展示调用量、成本、活跃 Session 和供应商健康状态 * **实时监控与统计** ：仪表盘展示调用量、成本、活跃 Session 和供应商健康状态
* **Session 管理** ：5 分钟上下文缓存，同一会话自动路由到相同供应商，提高缓存命中率 * **Session 管理** ：5 分钟上下文缓存，同一会话自动路由到相同供应商，提高缓存命中率
* **OpenAI 兼容层** ：支持 `/v1/chat/completions` 端点，无缝对接现有工具链 * **OpenAI 兼容层** ：支持 `/v1/chat/completions` 端点，无缝对接现有工具链
## 🛠️ 快速部署 ## 🛠️ 快速部署
### 一键脚本部署 ### 一键脚本部署
bash bash
# 使用官方部署脚本，5 分钟完成安装 # 使用官方部署脚本，5 分钟完成安装
curl -fsSL https://claude-code-hub.app/install.sh | bash curl -fsSL https://claude-code-hub.app/install.sh | bash
1 1
2 2
详细部署文档请参考：[脚本部署指南](<https://claude-code-hub.app/docs/deployment/script>) 详细部署文档请参考：[脚本部署指南](<https://claude-code-hub.app/docs/deployment/script>)
### 客户端接入 ### 客户端接入
部署完成后，将 Claude Code、Codex 等工具的 API 地址指向 CCH 代理即可使用。 部署完成后，将 Claude Code、Codex 等工具的 API 地址指向 CCH 代理即可使用。
详细接入文档请参考：[客户端接入指南](<https://claude-code-hub.app/docs/deployment/client-setup>) 详细接入文档请参考：[客户端接入指南](<https://claude-code-hub.app/docs/deployment/client-setup>)
## 常见问题 ## 常见问题
### CCH和CCS有什么区别？ ### CCH和CCS有什么区别？
CCH更适合团队内部使用，而CCS更适合个人用户。 CCH更适合团队内部使用，而CCS更适合个人用户。
### CCH 和直接使用 API 有什么区别？ ### CCH 和直接使用 API 有什么区别？
CCH 提供了供应商故障自动切换、负载均衡、用量统计、Session 粘性等团队级功能，单人使用直接配 API 即可，多人协作推荐使用 CCH。 CCH 提供了供应商故障自动切换、负载均衡、用量统计、Session 粘性等团队级功能，单人使用直接配 API 即可，多人协作推荐使用 CCH。