fix: 移除死链接，修复构建错误
- 删除已废弃的 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:
parent
16c6279484
commit
3afad1525c
16
.claude/settings.local.json
Normal file
16
.claude/settings.local.json
Normal 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)"
|
||||
]
|
||||
}
|
||||
}
|
||||
@ -91,18 +91,10 @@ export default defineConfig({
|
||||
{ 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: '支持',
|
||||
items: [
|
||||
{ text: 'FAQ', link: '/support/faq' },
|
||||
{ text: '售后', link: '/support/after-sales' },
|
||||
{ text: '故障排查', link: '/support/troubleshooting' },
|
||||
]
|
||||
},
|
||||
|
||||
@ -1,160 +1,161 @@
|
||||
# Alma 客户端配置指南
|
||||
|
||||
**功能强大的 AI 编程客户端工具**
|
||||
|
||||
📋 简介
|
||||
|
||||
Alma 是一款功能强大且界面精美的 AI 客户端工具，集成了代码编写、终端操作、Git 管理、浏览器等多种功能，为开发者提供完整的 AI 辅助编程体验。
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
资源| 地址
|
||||
---|---
|
||||
Alma 官网| <https://alma.now/>
|
||||
|
||||
## ✨ 功能特点
|
||||
|
||||
Alma 提供以下强大功能：
|
||||
|
||||
* ✅ **代码编写** ：智能代码生成和补全
|
||||
* ✅ **终端操作** ：集成终端，直接执行命令
|
||||
* ✅ **Git 管理** ：可视化 Git 操作
|
||||
* ✅ **浏览器集成** ：内置浏览器支持
|
||||
* ✅ **多模型支持** ：支持 Claude、Gemini 等多种模型
|
||||
* ✅ **自定义供应商** ：可接入自定义 API 提供商
|
||||
|
||||
|
||||
|
||||
## 🛠️ 安装与配置
|
||||
|
||||
### 第一步：安装 Alma
|
||||
|
||||
访问 [Alma 官网](<https://alma.now/>) 下载并安装适合你操作系统的版本。
|
||||
|
||||
### 第二步：设置中文界面
|
||||
|
||||
为了更好的使用体验，建议将界面设置为中文：
|
||||
|
||||
1. 打开 Alma 应用
|
||||
2. 进入 **Settins → General → Language**
|
||||
3. 选择「中文」
|
||||
4. 点击「保存」
|
||||
|
||||
|
||||
|
||||
|
||||
### 第三步：添加 OneinAI 自定义供应商
|
||||
|
||||
**1\. 进入供应商设置**
|
||||
|
||||
点击 **选择供应商 → Add Custom Provider** （添加自定义提供商）
|
||||
|
||||
|
||||
|
||||
**2\. 配置 OneinAI 供应商**
|
||||
|
||||
|
||||
|
||||
填写以下信息：
|
||||
|
||||
* **Provider Name** ：OneinAI（或自定义名称）
|
||||
* **Base URL** ：`https://api.oneinai.com/v1`
|
||||
* **API Key** ：粘贴你从 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 创建的 API Key
|
||||
|
||||
💡提示
|
||||
如果需要使用Claude模型，请选择Anthropic然后添加供应商
|
||||
|
||||
**3\. 获取可用模型**
|
||||
|
||||
添加完成后，在 OneinAI 供应商界面点击 **Fetch** （获取）按钮，系统会自动获取所有可用模型。
|
||||
|
||||
|
||||
|
||||
选择你需要的模型即可开始使用。
|
||||
|
||||
|
||||
|
||||
|
||||
### 使用技巧
|
||||
|
||||
**1\. 代码编写**
|
||||
|
||||
* 描述你的需求，Alma 会生成对应代码
|
||||
* 支持多文件操作和项目级别的修改
|
||||
* 可以实时预览和修改生成的代码
|
||||
|
||||
**2\. 终端操作**
|
||||
|
||||
* 集成终端直接执行命令
|
||||
* 支持查看命令执行结果
|
||||
* 可以与 AI 互动调试问题
|
||||
|
||||
**3\. Git 管理**
|
||||
|
||||
* 可视化查看 Git 状态
|
||||
* AI 辅助编写提交信息
|
||||
* 支持分支管理和合并操作
|
||||
|
||||
**4\. 文件浏览**
|
||||
|
||||
* 浏览项目文件结构
|
||||
* 快速定位和编辑文件
|
||||
* 支持文件搜索和过滤
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 1\. 选择合适的模型
|
||||
|
||||
* **Claude Sonnet** ：适合日常编码任务，速度快
|
||||
* **Claude Opus** ：适合复杂的架构设计和难题
|
||||
* **Gemini** ：适合需要多模态能力的任务（如图片理解）
|
||||
|
||||
### 2\. 合理使用上下文
|
||||
|
||||
* 对于小型项目，可以「全选」所有文件
|
||||
* 对于大型项目，选择相关的模块和文件
|
||||
* 定期清理不相关的上下文，避免 token 浪费
|
||||
|
||||
### 3\. 充分利用 Alma 的集成功能
|
||||
|
||||
* 使用终端功能验证 AI 生成的代码
|
||||
* 利用 Git 集成管理代码版本
|
||||
* 通过浏览器功能查看文档和参考资料
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 如何切换不同的 API 提供商？
|
||||
|
||||
在聊天界面顶部的模型选择器中，可以随时切换不同的提供商和模型。
|
||||
|
||||
### 为什么有些模型无法使用？
|
||||
|
||||
* 检查对应的 API Key 是否有权限访问该模型
|
||||
* 确认账户余额是否充足
|
||||
* 查看 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 的令牌组设置
|
||||
|
||||
### Alma 和 Claude Code 有什么区别？
|
||||
|
||||
特性| Alma| Claude Code
|
||||
---|---|---
|
||||
界面| 图形化界面| 命令行界面
|
||||
适用场景| 全功能开发环境| 终端快速操作
|
||||
集成功能| 终端、Git、浏览器等| 纯命令行工具
|
||||
学习曲线| 较低| 较高
|
||||
|
||||
可以根据具体需求选择使用。
|
||||
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。
|
||||
|
||||
## ✅ 完成
|
||||
|
||||
🎉 **配置完成！现在你可以愉快地使用 Alma 进行 AI 辅助编程了！**
|
||||
|
||||
记住以下要点：
|
||||
|
||||
* ✅ 选择「全选」上下文范围
|
||||
* ✅ 根据任务选择合适的模型
|
||||
* ✅ 充分利用 Alma 的集成功能
|
||||
* ✅ 定期检查 API 余额
|
||||
|
||||
# Alma 客户端配置指南
|
||||
|
||||
**功能强大的 AI 编程客户端工具**
|
||||
|
||||
📋 简介
|
||||
|
||||
Alma 是一款功能强大且界面精美的 AI 客户端工具，集成了代码编写、终端操作、Git 管理、浏览器等多种功能，为开发者提供完整的 AI 辅助编程体验。
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
资源| 地址
|
||||
---|---
|
||||
Alma 官网| <https://alma.now/>
|
||||
|
||||
## ✨ 功能特点
|
||||
|
||||
Alma 提供以下强大功能：
|
||||
|
||||
* ✅ **代码编写** ：智能代码生成和补全
|
||||
* ✅ **终端操作** ：集成终端，直接执行命令
|
||||
* ✅ **Git 管理** ：可视化 Git 操作
|
||||
* ✅ **浏览器集成** ：内置浏览器支持
|
||||
* ✅ **多模型支持** ：支持 Claude、Gemini 等多种模型
|
||||
* ✅ **自定义供应商** ：可接入自定义 API 提供商
|
||||
|
||||
|
||||
|
||||
## 🛠️ 安装与配置
|
||||
|
||||
### 第一步：安装 Alma
|
||||
|
||||
访问 [Alma 官网](<https://alma.now/>) 下载并安装适合你操作系统的版本。
|
||||
|
||||
### 第二步：设置中文界面
|
||||
|
||||
为了更好的使用体验，建议将界面设置为中文：
|
||||
|
||||
1. 打开 Alma 应用
|
||||
2. 进入 **Settins → General → Language**
|
||||
3. 选择「中文」
|
||||
4. 点击「保存」
|
||||
|
||||
|
||||
|
||||
|
||||
### 第三步：添加 OneinAI 自定义供应商
|
||||
|
||||
**1\. 进入供应商设置**
|
||||
|
||||
点击 **选择供应商 → Add Custom Provider** （添加自定义提供商）
|
||||
|
||||
|
||||
|
||||
**2\. 配置 OneinAI 供应商**
|
||||
|
||||
|
||||
|
||||
填写以下信息：
|
||||
|
||||
* **Provider Name** ：OneinAI（或自定义名称）
|
||||
* **Base URL** ：`https://api.oneinai.com/v1`
|
||||
* **API Key** ：粘贴你从 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 创建的 API Key
|
||||
|
||||
💡提示
|
||||
如果需要使用Claude模型，请选择Anthropic然后添加供应商
|
||||
|
||||
**3\. 获取可用模型**
|
||||
|
||||
添加完成后，在 OneinAI 供应商界面点击 **Fetch** （获取）按钮，系统会自动获取所有可用模型。
|
||||
|
||||
|
||||
|
||||
选择你需要的模型即可开始使用。
|
||||
|
||||
|
||||
|
||||
|
||||
### 使用技巧
|
||||
|
||||
**1\. 代码编写**
|
||||
|
||||
* 描述你的需求，Alma 会生成对应代码
|
||||
* 支持多文件操作和项目级别的修改
|
||||
* 可以实时预览和修改生成的代码
|
||||
|
||||
**2\. 终端操作**
|
||||
|
||||
* 集成终端直接执行命令
|
||||
* 支持查看命令执行结果
|
||||
* 可以与 AI 互动调试问题
|
||||
|
||||
**3\. Git 管理**
|
||||
|
||||
* 可视化查看 Git 状态
|
||||
* AI 辅助编写提交信息
|
||||
* 支持分支管理和合并操作
|
||||
|
||||
**4\. 文件浏览**
|
||||
|
||||
* 浏览项目文件结构
|
||||
* 快速定位和编辑文件
|
||||
* 支持文件搜索和过滤
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 1\. 选择合适的模型
|
||||
|
||||
* **Claude Sonnet** ：适合日常编码任务，速度快
|
||||
* **Claude Opus** ：适合复杂的架构设计和难题
|
||||
* **Gemini** ：适合需要多模态能力的任务（如图片理解）
|
||||
|
||||
### 2\. 合理使用上下文
|
||||
|
||||
* 对于小型项目，可以「全选」所有文件
|
||||
* 对于大型项目，选择相关的模块和文件
|
||||
* 定期清理不相关的上下文，避免 token 浪费
|
||||
|
||||
### 3\. 充分利用 Alma 的集成功能
|
||||
|
||||
* 使用终端功能验证 AI 生成的代码
|
||||
* 利用 Git 集成管理代码版本
|
||||
* 通过浏览器功能查看文档和参考资料
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 如何切换不同的 API 提供商？
|
||||
|
||||
在聊天界面顶部的模型选择器中，可以随时切换不同的提供商和模型。
|
||||
|
||||
### 为什么有些模型无法使用？
|
||||
|
||||
* 检查对应的 API Key 是否有权限访问该模型
|
||||
* 确认账户余额是否充足
|
||||
* 查看 [OneinAI 控制台](<https://api.oneinai.com/console/token>) 的令牌组设置
|
||||
|
||||
### Alma 和 Claude Code 有什么区别？
|
||||
|
||||
特性| Alma| Claude Code
|
||||
---|---|---
|
||||
界面| 图形化界面| 命令行界面
|
||||
适用场景| 全功能开发环境| 终端快速操作
|
||||
集成功能| 终端、Git、浏览器等| 纯命令行工具
|
||||
学习曲线| 较低| 较高
|
||||
|
||||
可以根据具体需求选择使用。
|
||||
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](</support/faq>)
|
||||
|
||||
## ✅ 完成
|
||||
|
||||
🎉 **配置完成！现在你可以愉快地使用 Alma 进行 AI 辅助编程了！**
|
||||
|
||||
记住以下要点：
|
||||
|
||||
* ✅ 选择「全选」上下文范围
|
||||
* ✅ 根据任务选择合适的模型
|
||||
* ✅ 充分利用 Alma 的集成功能
|
||||
* ✅ 定期检查 API 余额
|
||||
|
||||
@ -1,268 +1,281 @@
|
||||
# CherryStudio 配置指南
|
||||
# CherryStudio 配置指南
|
||||
|
||||
**全能的 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` 安装程序
|
||||
* **macOS** ：下载 `.dmg` 镜像文件
|
||||
* **Linux** ：下载 `.AppImage` 或 `.deb` 包
|
||||
3. 下载完成后，按照系统提示完成安装
|
||||
1. 访问 [CherryStudio 下载页面](https://www.cherry-ai.com/download)
|
||||
2. 根据你的操作系统选择对应的安装包：
|
||||
- **Windows**：下载 `.exe` 安装程序
|
||||
- **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>)
|
||||
2. 登录你的账户
|
||||
3. 根据需要创建对应的令牌组：
|
||||
* **Claude 模型** ：选择 Claude分组
|
||||
* **Gemini 模型** ：选择 Gemini分组
|
||||
|
||||
|
||||
|
||||
> ⚠️ 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 应用
|
||||
2. 点击左下角的「设置」或「偏好设置」
|
||||
3. 选择「模型配置」或「API 配置」选项
|
||||
### 第二步：选择 Claude 模型类型
|
||||
|
||||
### 第二步：选择 Claude 模型类型
|
||||
|
||||
|
||||
|
||||
在模型列表中选择你需要的 Claude 模型。
|
||||
|
||||
在模型列表中选择你需要的 Claude 模型
|
||||
|
||||
### 第三步：配置 Claude API
|
||||
### 第三步：配置 Claude API
|
||||
|
||||
在 Claude 配置界面中填写以下信息：
|
||||
|
||||
|
||||
|
||||
|
||||
**配置参数** ：
|
||||
**配置参数：**
|
||||
|
||||
* **提供商类型** ：选择 `Anthropic`
|
||||
* **API 地址** ：`https://api.oneinai.com`
|
||||
* **API Key** ：粘贴你从 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 获取的 Claude API Key
|
||||
* **模型名称** ：输入上一步选择的模型名称（如 `claude-sonnet-4-6`）
|
||||
| 字段 | 填写内容 |
|
||||
|------|---------|
|
||||
| 提供商类型 | `Anthropic` |
|
||||
| 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 模型类型
|
||||
|
||||
|
||||
|
||||
在模型列表中选择你需要的 Gemini 模型：
|
||||
|
||||
* **Gemini 3 Flash Preview** ：`gemini-3-flash-preview` \- 最新版本，速度快，性能优秀（推荐）
|
||||
* **Gemini 3 Pro Preview** ：`gemini-3-pro-preview` \- 高性能，适合复杂任务
|
||||
* **Gemini 2.0 Flash** ：快速响应，适合简单对话
|
||||
- **Gemini 3 Flash Preview**：`gemini-3-flash-preview` — 最新版本，速度快，性能优秀（推荐）
|
||||
- **Gemini 3 Pro Preview**：`gemini-3-pro-preview` — 高性能，适合复杂任务
|
||||
- **Gemini 2.0 Flash**：快速响应，适合简单对话
|
||||
|
||||
⚠️ 注意
|
||||
|
||||
* Gemini 和 Claude 需要使用不同的 API Key（不同的令牌组）
|
||||
* 确保你在 IkunCode 平台创建了对应的令牌组
|
||||
|
||||
### 第二步：配置 Gemini API
|
||||
### 第二步：配置 Gemini API
|
||||
|
||||
在 Gemini 配置界面中填写以下信息：
|
||||
|
||||
|
||||
|
||||
|
||||
**配置参数** ：
|
||||
**配置参数：**
|
||||
|
||||
* **提供商类型** ：选择 `Gemini`
|
||||
* **API 地址** ：`https://api.oneinai.com/v1beta/models`
|
||||
* **API Key** ：粘贴你从 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 获取的 Gemini API Key
|
||||
* **模型名称** ：输入上一步选择的模型名称（如 `gemini-3-flash-preview`）
|
||||
| 字段 | 填写内容 |
|
||||
|------|---------|
|
||||
| 提供商类型 | `Gemini` |
|
||||
| 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. 点击顶部的模型选择器
|
||||
2. 选择其他已配置的模型
|
||||
3. 继续对话（上下文可能会保留或重置，取决于应用设置）
|
||||
1. 点击顶部的模型选择器
|
||||
2. 选择其他已配置的模型
|
||||
3. 继续对话（上下文可能会保留或重置，取决于应用设置）
|
||||
|
||||
### 调整参数
|
||||
### 调整参数
|
||||
|
||||
CherryStudio 通常支持调整以下参数：
|
||||
|
||||
* **Temperature** （温度）：控制回复的随机性（0-1）
|
||||
* **Max Tokens** （最大令牌数）：控制回复长度
|
||||
* **Top P** ：控制采样范围
|
||||
- **Temperature**（温度）：控制回复的随机性（0-1）
|
||||
- **Max Tokens**（最大令牌数）：控制回复长度
|
||||
- **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`）
|
||||
* **多模态任务** ：Gemini 3 Pro Preview（支持图片）
|
||||
| 任务类型 | 推荐模型 | 模型标识 |
|
||||
|---------|---------|---------|
|
||||
| 代码编写 | 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` |
|
||||
| 多模态（图片） | Gemini 3 Pro Preview | `gemini-3-pro-preview` |
|
||||
|
||||
### 2\. 管理 API 使用
|
||||
### 2. 管理 API 使用
|
||||
|
||||
* 定期检查 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 的余额
|
||||
* 为不同用途创建不同的 API Key
|
||||
* 避免在公共场合泄露 API Key
|
||||
- 定期检查 [oneinAI 控制台](https://api.oneinai.com/console/token) 的余额
|
||||
- 为不同用途创建不同的 API Key，便于管理和审计
|
||||
- 避免在公共场合或代码仓库中泄露 API Key
|
||||
|
||||
### 3\. 优化对话体验
|
||||
### 3. 优化对话体验
|
||||
|
||||
* 使用清晰的提示词
|
||||
* 合理设置上下文长度
|
||||
* 善用对话历史管理功能
|
||||
- 使用清晰、具体的提示词
|
||||
- 合理设置上下文长度，避免过长影响响应速度
|
||||
- 善用对话历史管理功能，及时归档或清理
|
||||
|
||||
## 🔍 与其他客户端的对比
|
||||
---
|
||||
|
||||
特性| CherryStudio| Alma| Hapi
|
||||
---|---|---|---
|
||||
界面类型| 桌面应用| 桌面应用| Web/PWA
|
||||
多模型支持| ✅| ✅| ✅
|
||||
代码编辑| 部分支持| ✅| ✅
|
||||
终端集成| ❌| ✅| ✅
|
||||
远程访问| ❌| ❌| ✅
|
||||
学习曲线| 低| 中| 中
|
||||
|
||||
**选择建议** ：
|
||||
## 🔍 与其他客户端的对比
|
||||
|
||||
* **纯对话需求** ：CherryStudio（界面简洁，易上手）
|
||||
* **编程开发** ：Alma 或 Hapi（功能更强大）
|
||||
* **远程控制** ：Hapi（独有功能）
|
||||
| 特性 | CherryStudio | Alma | 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 配置错误
|
||||
* 网络连接问题
|
||||
* API Key 权限不足
|
||||
1. 重新复制 API Key，确保完整且无多余空格
|
||||
2. 在 [oneinAI 控制台](https://api.oneinai.com/console/token) 确认创建了正确的令牌组
|
||||
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. 分别配置不同的模型提供商
|
||||
2. 在新建对话时选择对应的模型
|
||||
3. 可以创建多个对话窗口，每个使用不同模型
|
||||
1. 检查网络连接质量
|
||||
2. 尝试使用更快的模型（如 Gemini Flash 或 Claude Haiku）
|
||||
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 对话了！**
|
||||
|
||||
记住以下要点：
|
||||
**核心要点回顾：**
|
||||
|
||||
* ✅ 不同模型使用不同的 API Key（不同令牌组）
|
||||
* ✅ Claude API 地址：`https://api.oneinai.com/v1/messages`
|
||||
* ✅ Gemini API 地址：`https://api.oneinai.com/v1beta/models`
|
||||
* ✅ 根据任务选择合适的模型
|
||||
* ✅ 定期检查 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 的余额
|
||||
* ✅ 妥善保管你的 API Key
|
||||
- ✅ Claude 与 Gemini 必须使用**不同的 API Key**（不同令牌组）
|
||||
- ✅ Claude API 地址：`https://api.oneinai.com`
|
||||
- ✅ Gemini API 地址：`https://api.oneinai.com/v1beta/models`
|
||||
- ✅ 根据任务特性选择合适的模型
|
||||
- ✅ 定期检查 [oneinAI 控制台](https://api.oneinai.com/console/token) 的余额
|
||||
- ✅ 妥善保管你的 API Key，避免泄露
|
||||
|
||||
* * *
|
||||
---
|
||||
|
||||
**相关教程** ：
|
||||
**相关教程：**
|
||||
|
||||
* [Alma 客户端配置](</apps/alma>)
|
||||
* [Hapi 远程控制](</apps/hapi>)
|
||||
* [IkunCode 控制台](<https://api.oneinai.com/console/token>)
|
||||
- [Alma 客户端配置](/apps/alma)
|
||||
- [Hapi 远程控制](/apps/hapi)
|
||||
- [oneinAI 控制台](https://api.oneinai.com/console/token)
|
||||
|
||||
@ -1,325 +1,325 @@
|
||||
# Hapi 进阶配置：Cloudflare 优选 IP 高速穿透
|
||||
|
||||
**没有公网 IP？使用 Cloudflare 优选 IP，打造高速内网穿透通道**
|
||||
|
||||
> **适用场景** ：已配置 Cloudflare Tunnel，但访问速度慢、延迟高 **解决方案** ：利用 Cloudflare for SaaS + 优选 IP 服务，绕过拥堵节点 **前置要求** ：已完成 [Hapi 基础配置](</apps/hapi>)，拥有两个域名
|
||||
|
||||
## 📺 视频教程
|
||||
|
||||
推荐观看
|
||||
|
||||
[没有公网IP？cloudflare优选IP，高速内网穿透 - 哔哩哔哩](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
|
||||
|
||||
视频详细演示了完整的配置过程，强烈建议先观看视频再进行操作。
|
||||
|
||||
## 🎯 你正在解决什么问题？
|
||||
|
||||
### 默认 Tunnel 的痛点
|
||||
|
||||
当你直接使用 Cloudflare Tunnel 绑定域名时：
|
||||
|
||||
* ❌ Cloudflare 分配的 Anycast IP 在国内可能被绕路（绕到美国、欧洲）
|
||||
* ❌ 运营商 QoS 限速，访问速度慢
|
||||
* ❌ 延迟高达几百毫秒，严重影响使用体验
|
||||
|
||||
|
||||
|
||||
### 优选 IP 方案的优势
|
||||
|
||||
通过本教程的配置：
|
||||
|
||||
* ✅ 强制流量走对国内网络友好的节点（香港、新加坡等）
|
||||
* ✅ 大幅提升访问速度，延迟降低到几十毫秒
|
||||
* ✅ 完全免费，利用 Cloudflare 企业级功能
|
||||
* ✅ 稳定性高，自动切换最优路由
|
||||
|
||||
|
||||
|
||||
🚀 速度提升对比
|
||||
|
||||
从上面两张图可以看到，优选 IP 后访问速度得到了**显著提升** ，延迟从几百毫秒降低到几十毫秒，页面加载也更加流畅！
|
||||
|
||||
## 🔍 原理解析
|
||||
|
||||
### 流量走向链路
|
||||
|
||||
当用户访问你的域名时，流量是这样流转的：
|
||||
|
||||
|
||||
用户浏览器
|
||||
↓
|
||||
DNS 解析：hapi.justdo.xin
|
||||
↓
|
||||
CNAME → cdn.ttdk.fun
|
||||
↓
|
||||
CNAME → isp.qzz.io（优选 IP 调度器）
|
||||
↓
|
||||
返回最优 Cloudflare IP（根据用户运营商）
|
||||
↓
|
||||
Cloudflare 边缘节点（通过 Host Header 识别）
|
||||
↓
|
||||
SaaS 路由：hapi.justdo.xin → hapi.ttdk.fun
|
||||
↓
|
||||
Cloudflare Tunnel（加密隧道）
|
||||
↓
|
||||
你的本地服务器 localhost:3006
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
13
|
||||
14
|
||||
15
|
||||
16
|
||||
17
|
||||
|
||||
💡 提示
|
||||
|
||||
[isp.qzz.io](<https://isp.qzz.io/>) 在这里充当"智能交警"的角色，根据你的网络环境自动选择最优路线。
|
||||
|
||||
### 核心技术要点
|
||||
|
||||
1. **优选 IP 调度器** ：[isp.qzz.io](<https://isp.qzz.io/>) 会根据用户的网络环境（电信/联通/移动），返回当前速度最快、延迟最低的 Cloudflare 官方 CDN 节点 IP
|
||||
|
||||
2. **Cloudflare for SaaS** ：通过 Custom Hostnames 功能，把"访问域名"和"隧道域名"解耦，实现"走优选 IP 进隧道"
|
||||
|
||||
3. **DNS 链式解析** ：通过 CNAME 链，把用户请求引导到优选 IP，同时保持 Cloudflare 对域名的正确识别
|
||||
|
||||
💡 关于优选 IP 调度器
|
||||
|
||||
[isp.qzz.io](<https://isp.qzz.io/>) 是一个社区维护的 Cloudflare 优选 IP 调度服务，它会自动测速并返回对你当前网络环境最优的 Cloudflare CDN 节点。访问该网站可以查看更多信息和使用说明。
|
||||
|
||||
## 🛠️ 配置步骤
|
||||
|
||||
### 前置准备
|
||||
|
||||
你需要准备：
|
||||
|
||||
1. **主力域名** ：用于展示给用户访问（例如：`hapi.justdo.xin`）
|
||||
2. **辅助域名** ：用于承载 Cloudflare Tunnel（例如：`ttdk.fun`）
|
||||
3. 两个域名都需要托管在 Cloudflare
|
||||
|
||||
⚠️ 重要说明
|
||||
|
||||
* 主力域名和辅助域名**不能是同一个域名**
|
||||
* 辅助域名需要是你自己拥有的，不能用别人的
|
||||
* 两个域名都必须在 Cloudflare 上管理
|
||||
|
||||
### 第一步：配置 Cloudflare Tunnel（辅助域名）
|
||||
|
||||
在辅助域名（例如 `ttdk.fun`）上设置 Tunnel：
|
||||
|
||||
1. 登录 Cloudflare，选择辅助域名
|
||||
2. 进入 **Zero Trust → Access → Tunnels**
|
||||
3. 创建隧道并安装 cloudflared
|
||||
4. 配置公共主机名：
|
||||
* **子域名** ：`hapi`
|
||||
* **域名** ：`ttdk.fun`
|
||||
* **服务** ：`http://localhost:3006`
|
||||
|
||||
完成后你应该能通过 `hapi.ttdk.fun` 访问你的 Hapi 服务。
|
||||
|
||||
### 第二步：启用 Cloudflare for SaaS（辅助域名）
|
||||
|
||||
在辅助域名（`ttdk.fun`）上启用 SaaS 功能：
|
||||
|
||||
1. 进入 Cloudflare 控制台
|
||||
2. 选择 `ttdk.fun` 域名
|
||||
3. 进入 **SSL/TLS → Custom Hostnames**
|
||||
4. 点击 **Add Custom Hostname**
|
||||
5. 填写：
|
||||
* **Custom Hostname** ：`hapi.justdo.xin`（主力域名）
|
||||
* **Wildcard** ：不勾选
|
||||
6. 点击 **Add Custom Hostname**
|
||||
|
||||
💡 提示
|
||||
|
||||
添加后会生成 2 条 TXT 验证记录，先不着急配置，继续下一步。
|
||||
|
||||
### 第三步：配置 DNS 解析（主力域名）
|
||||
|
||||
在主力域名（`justdo.xin`）的 DNS 设置中添加以下记录：
|
||||
|
||||
#### 3.1 添加 SSL 验证记录
|
||||
|
||||
从第二步中复制 Cloudflare 生成的 2 条 TXT 记录，添加到主力域名的 DNS：
|
||||
|
||||
类型| 名称| 内容| 代理状态
|
||||
---|---|---|---
|
||||
TXT| `_acme-challenge.hapi`| `xxxxxxxxxx`（从 SaaS 页面复制）| 仅限 DNS
|
||||
TXT| `_acme-challenge.hapi`| `yyyyyyyyyy`（从 SaaS 页面复制）| 仅限 DNS
|
||||
|
||||
#### 3.2 添加 CNAME 记录
|
||||
|
||||
类型| 名称| 目标| 代理状态
|
||||
---|---|---|---
|
||||
CNAME| `cdn`| `isp.qzz.io`| 仅限 DNS ⚠️
|
||||
CNAME| `hapi`| `cdn.justdo.xin`| 仅限 DNS ⚠️
|
||||
|
||||
🚨 关键配置
|
||||
|
||||
**必须关闭小黄云（代理状态设为 "仅限 DNS"）！**
|
||||
|
||||
如果开启代理，会导致 DNS 解析链中断，无法触发优选 IP。
|
||||
|
||||
### 第四步：配置回退源（辅助域名）
|
||||
|
||||
在辅助域名（`ttdk.fun`）的 DNS 设置中：
|
||||
|
||||
类型| 名称| 目标| 代理状态
|
||||
---|---|---|---
|
||||
CNAME| `hapi`| `[你的隧道ID].cfargotunnel.com`| 已代理 ✅
|
||||
|
||||
💡 提示
|
||||
|
||||
这条记录通常在创建 Tunnel 时自动生成。确保小黄云是**开启** 状态（已代理）。
|
||||
|
||||
### 第五步：等待 SSL 证书生效
|
||||
|
||||
1. 回到辅助域名的 **SSL/TLS → Custom Hostnames** 页面
|
||||
2. 查看 `hapi.justdo.xin` 的状态
|
||||
3. 等待几分钟，状态变为 **Active（有效）** 即表示配置成功
|
||||
|
||||
⏳ 耐心等待
|
||||
|
||||
SSL 证书签发通常需要 5-15 分钟，请耐心等待。如果超过 30 分钟仍未生效，检查 TXT 记录是否正确添加。
|
||||
|
||||
## ✅ 验证配置
|
||||
|
||||
### 测试访问
|
||||
|
||||
在浏览器中访问：`https://hapi.justdo.xin`
|
||||
|
||||
如果能正常打开 Hapi 界面，说明配置成功！
|
||||
|
||||
### 测试速度提升
|
||||
|
||||
使用 ping 或测速工具对比：
|
||||
|
||||
**优化前** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
ping hapi.ttdk.fun
|
||||
# 延迟通常 200-500ms
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
**优化后** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
ping hapi.justdo.xin
|
||||
# 延迟通常 20-100ms
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
## 🎓 角色分配总结
|
||||
|
||||
角色| 域名示例| 作用
|
||||
---|---|---
|
||||
**主力域名**| `hapi.justdo.xin`| 你最终展示给用户访问的地址
|
||||
**辅助域名**| `hapi.ttdk.fun`| 承载 Tunnel 的"回退源"，用户不直接感知
|
||||
**优选 IP 调度器**| [isp.qzz.io](<https://isp.qzz.io/>)| 像"交警"，告诉流量该走哪条不堵的路
|
||||
**中转域名**| `cdn.justdo.xin`| 作为跳板，把主力域名引向优选 IP 池
|
||||
|
||||
## 🔧 故障排查
|
||||
|
||||
### SSL 证书一直显示 Pending？
|
||||
|
||||
**可能原因** ：
|
||||
|
||||
* TXT 记录添加错误或未生效
|
||||
* DNS 传播未完成
|
||||
|
||||
**解决方法** ：
|
||||
|
||||
1. 使用 [DNS 检查工具](<https://dnschecker.org/>) 验证 TXT 记录
|
||||
2. 等待 DNS 全球传播（最多 24 小时）
|
||||
3. 重新添加 Custom Hostname
|
||||
|
||||
### 访问显示 526 错误？
|
||||
|
||||
**可能原因** ：
|
||||
|
||||
* 辅助域名的 `hapi` 记录未开启代理（小黄云）
|
||||
* Tunnel 未正确配置
|
||||
|
||||
**解决方法** ：
|
||||
|
||||
1. 确保 `hapi.ttdk.fun` 的小黄云是**开启** 状态
|
||||
2. 检查 Tunnel 是否正常运行
|
||||
|
||||
### 访问仍然很慢？
|
||||
|
||||
**可能原因** ：
|
||||
|
||||
* 主力域名的 CNAME 记录开启了代理
|
||||
* DNS 解析链断裂
|
||||
|
||||
**解决方法** ：
|
||||
|
||||
1. 确保 `hapi.justdo.xin` 和 `cdn.justdo.xin` 的小黄云都是**关闭** 状态
|
||||
2. 使用 `nslookup` 检查 DNS 解析链是否完整
|
||||
|
||||
## 🚀 进阶优化
|
||||
|
||||
### 自建优选 IP 服务
|
||||
|
||||
如果你追求极致稳定，可以：
|
||||
|
||||
1. 使用 CloudflareSpeedTest 工具本地测速
|
||||
2. 手动选择最优 IP
|
||||
3. 创建自己的优选域名，替代 `isp.qzz.io`
|
||||
|
||||
### 多运营商优化
|
||||
|
||||
可以针对不同运营商配置不同的优选路径：
|
||||
|
||||
* 电信用户：`cdn-ct.yourdomain.com`
|
||||
* 联通用户：`cdn-cu.yourdomain.com`
|
||||
* 移动用户：`cdn-cm.yourdomain.com`
|
||||
|
||||
通过 DNS 智能解析（GeoDNS），根据用户运营商返回不同的 CNAME 记录。
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
* [Cloudflare for SaaS 官方文档](<https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/>)
|
||||
* [Cloudflare Tunnel 文档](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/>)
|
||||
* [isp.qzz.io - 优选 IP 调度器](<https://isp.qzz.io/>)
|
||||
* [视频教程：cloudflare优选IP配置](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
|
||||
|
||||
## ⚠️ 安全提醒
|
||||
|
||||
1. 不要泄露你的 Tunnel 令牌
|
||||
2. 定期检查 Custom Hostnames 配置
|
||||
3. [isp.qzz.io](<https://isp.qzz.io/>) 是社区维护的优选 IP 服务，虽然可靠但非官方服务，你也可以选择自建优选服务
|
||||
4. 建议配合 Cloudflare Access 限制访问来源
|
||||
|
||||
## 💡 总结
|
||||
|
||||
通过这套配置，你：
|
||||
|
||||
* ✅ 不花一分钱
|
||||
* ✅ 利用 Cloudflare 企业级 SaaS 功能
|
||||
* ✅ 把原本几百毫秒延迟的内网穿透，优化到接近直连的体验
|
||||
* ✅ 打造了一条"高速内网穿透通道"
|
||||
|
||||
这就是目前免费方案中，提升 Cloudflare 内网穿透速度的**天花板级别配置** ！
|
||||
|
||||
* * *
|
||||
|
||||
**下一步** ：配置完成后，你可以愉快地在任何地方高速访问你的 Hapi 服务了！🎉
|
||||
# Hapi 进阶配置：Cloudflare 优选 IP 高速穿透
|
||||
|
||||
**没有公网 IP？使用 Cloudflare 优选 IP，打造高速内网穿透通道**
|
||||
|
||||
> **适用场景** ：已配置 Cloudflare Tunnel，但访问速度慢、延迟高 **解决方案** ：利用 Cloudflare for SaaS + 优选 IP 服务，绕过拥堵节点 **前置要求** ：已完成 [Hapi 基础配置](</apps/hapi>)，拥有两个域名
|
||||
|
||||
## 📺 视频教程
|
||||
|
||||
推荐观看
|
||||
|
||||
[没有公网IP？cloudflare优选IP，高速内网穿透 - 哔哩哔哩](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
|
||||
|
||||
视频详细演示了完整的配置过程，强烈建议先观看视频再进行操作。
|
||||
|
||||
## 🎯 你正在解决什么问题？
|
||||
|
||||
### 默认 Tunnel 的痛点
|
||||
|
||||
当你直接使用 Cloudflare Tunnel 绑定域名时：
|
||||
|
||||
* ❌ Cloudflare 分配的 Anycast IP 在国内可能被绕路（绕到美国、欧洲）
|
||||
* ❌ 运营商 QoS 限速，访问速度慢
|
||||
* ❌ 延迟高达几百毫秒，严重影响使用体验
|
||||
|
||||
|
||||
|
||||
### 优选 IP 方案的优势
|
||||
|
||||
通过本教程的配置：
|
||||
|
||||
* ✅ 强制流量走对国内网络友好的节点（香港、新加坡等）
|
||||
* ✅ 大幅提升访问速度，延迟降低到几十毫秒
|
||||
* ✅ 完全免费，利用 Cloudflare 企业级功能
|
||||
* ✅ 稳定性高，自动切换最优路由
|
||||
|
||||
|
||||
|
||||
🚀 速度提升对比
|
||||
|
||||
从上面两张图可以看到，优选 IP 后访问速度得到了**显著提升** ，延迟从几百毫秒降低到几十毫秒，页面加载也更加流畅！
|
||||
|
||||
## 🔍 原理解析
|
||||
|
||||
### 流量走向链路
|
||||
|
||||
当用户访问你的域名时，流量是这样流转的：
|
||||
|
||||
|
||||
用户浏览器
|
||||
↓
|
||||
DNS 解析：hapi.justdo.xin
|
||||
↓
|
||||
CNAME → cdn.ttdk.fun
|
||||
↓
|
||||
CNAME → isp.qzz.io（优选 IP 调度器）
|
||||
↓
|
||||
返回最优 Cloudflare IP（根据用户运营商）
|
||||
↓
|
||||
Cloudflare 边缘节点（通过 Host Header 识别）
|
||||
↓
|
||||
SaaS 路由：hapi.justdo.xin → hapi.ttdk.fun
|
||||
↓
|
||||
Cloudflare Tunnel（加密隧道）
|
||||
↓
|
||||
你的本地服务器 localhost:3006
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
13
|
||||
14
|
||||
15
|
||||
16
|
||||
17
|
||||
|
||||
💡 提示
|
||||
|
||||
[isp.qzz.io](<https://isp.qzz.io/>) 在这里充当"智能交警"的角色，根据你的网络环境自动选择最优路线。
|
||||
|
||||
### 核心技术要点
|
||||
|
||||
1. **优选 IP 调度器** ：[isp.qzz.io](<https://isp.qzz.io/>) 会根据用户的网络环境（电信/联通/移动），返回当前速度最快、延迟最低的 Cloudflare 官方 CDN 节点 IP
|
||||
|
||||
2. **Cloudflare for SaaS** ：通过 Custom Hostnames 功能，把"访问域名"和"隧道域名"解耦，实现"走优选 IP 进隧道"
|
||||
|
||||
3. **DNS 链式解析** ：通过 CNAME 链，把用户请求引导到优选 IP，同时保持 Cloudflare 对域名的正确识别
|
||||
|
||||
💡 关于优选 IP 调度器
|
||||
|
||||
[isp.qzz.io](<https://isp.qzz.io/>) 是一个社区维护的 Cloudflare 优选 IP 调度服务，它会自动测速并返回对你当前网络环境最优的 Cloudflare CDN 节点。访问该网站可以查看更多信息和使用说明。
|
||||
|
||||
## 🛠️ 配置步骤
|
||||
|
||||
### 前置准备
|
||||
|
||||
你需要准备：
|
||||
|
||||
1. **主力域名** ：用于展示给用户访问（例如：`hapi.justdo.xin`）
|
||||
2. **辅助域名** ：用于承载 Cloudflare Tunnel（例如：`ttdk.fun`）
|
||||
3. 两个域名都需要托管在 Cloudflare
|
||||
|
||||
⚠️ 重要说明
|
||||
|
||||
* 主力域名和辅助域名**不能是同一个域名**
|
||||
* 辅助域名需要是你自己拥有的，不能用别人的
|
||||
* 两个域名都必须在 Cloudflare 上管理
|
||||
|
||||
### 第一步：配置 Cloudflare Tunnel（辅助域名）
|
||||
|
||||
在辅助域名（例如 `ttdk.fun`）上设置 Tunnel：
|
||||
|
||||
1. 登录 Cloudflare，选择辅助域名
|
||||
2. 进入 **Zero Trust → Access → Tunnels**
|
||||
3. 创建隧道并安装 cloudflared
|
||||
4. 配置公共主机名：
|
||||
* **子域名** ：`hapi`
|
||||
* **域名** ：`ttdk.fun`
|
||||
* **服务** ：`http://localhost:3006`
|
||||
|
||||
完成后你应该能通过 `hapi.ttdk.fun` 访问你的 Hapi 服务。
|
||||
|
||||
### 第二步：启用 Cloudflare for SaaS（辅助域名）
|
||||
|
||||
在辅助域名（`ttdk.fun`）上启用 SaaS 功能：
|
||||
|
||||
1. 进入 Cloudflare 控制台
|
||||
2. 选择 `ttdk.fun` 域名
|
||||
3. 进入 **SSL/TLS → Custom Hostnames**
|
||||
4. 点击 **Add Custom Hostname**
|
||||
5. 填写：
|
||||
* **Custom Hostname** ：`hapi.justdo.xin`（主力域名）
|
||||
* **Wildcard** ：不勾选
|
||||
6. 点击 **Add Custom Hostname**
|
||||
|
||||
💡 提示
|
||||
|
||||
添加后会生成 2 条 TXT 验证记录，先不着急配置，继续下一步。
|
||||
|
||||
### 第三步：配置 DNS 解析（主力域名）
|
||||
|
||||
在主力域名（`justdo.xin`）的 DNS 设置中添加以下记录：
|
||||
|
||||
#### 3.1 添加 SSL 验证记录
|
||||
|
||||
从第二步中复制 Cloudflare 生成的 2 条 TXT 记录，添加到主力域名的 DNS：
|
||||
|
||||
类型| 名称| 内容| 代理状态
|
||||
---|---|---|---
|
||||
TXT| `_acme-challenge.hapi`| `xxxxxxxxxx`（从 SaaS 页面复制）| 仅限 DNS
|
||||
TXT| `_acme-challenge.hapi`| `yyyyyyyyyy`（从 SaaS 页面复制）| 仅限 DNS
|
||||
|
||||
#### 3.2 添加 CNAME 记录
|
||||
|
||||
类型| 名称| 目标| 代理状态
|
||||
---|---|---|---
|
||||
CNAME| `cdn`| `isp.qzz.io`| 仅限 DNS ⚠️
|
||||
CNAME| `hapi`| `cdn.justdo.xin`| 仅限 DNS ⚠️
|
||||
|
||||
🚨 关键配置
|
||||
|
||||
**必须关闭小黄云（代理状态设为 "仅限 DNS"）！**
|
||||
|
||||
如果开启代理，会导致 DNS 解析链中断，无法触发优选 IP。
|
||||
|
||||
### 第四步：配置回退源（辅助域名）
|
||||
|
||||
在辅助域名（`ttdk.fun`）的 DNS 设置中：
|
||||
|
||||
类型| 名称| 目标| 代理状态
|
||||
---|---|---|---
|
||||
CNAME| `hapi`| `[你的隧道ID].cfargotunnel.com`| 已代理 ✅
|
||||
|
||||
💡 提示
|
||||
|
||||
这条记录通常在创建 Tunnel 时自动生成。确保小黄云是**开启** 状态（已代理）。
|
||||
|
||||
### 第五步：等待 SSL 证书生效
|
||||
|
||||
1. 回到辅助域名的 **SSL/TLS → Custom Hostnames** 页面
|
||||
2. 查看 `hapi.justdo.xin` 的状态
|
||||
3. 等待几分钟，状态变为 **Active（有效）** 即表示配置成功
|
||||
|
||||
⏳ 耐心等待
|
||||
|
||||
SSL 证书签发通常需要 5-15 分钟，请耐心等待。如果超过 30 分钟仍未生效，检查 TXT 记录是否正确添加。
|
||||
|
||||
## ✅ 验证配置
|
||||
|
||||
### 测试访问
|
||||
|
||||
在浏览器中访问：`https://hapi.justdo.xin`
|
||||
|
||||
如果能正常打开 Hapi 界面，说明配置成功！
|
||||
|
||||
### 测试速度提升
|
||||
|
||||
使用 ping 或测速工具对比：
|
||||
|
||||
**优化前** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
ping hapi.ttdk.fun
|
||||
# 延迟通常 200-500ms
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
**优化后** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
ping hapi.justdo.xin
|
||||
# 延迟通常 20-100ms
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
## 🎓 角色分配总结
|
||||
|
||||
角色| 域名示例| 作用
|
||||
---|---|---
|
||||
**主力域名**| `hapi.justdo.xin`| 你最终展示给用户访问的地址
|
||||
**辅助域名**| `hapi.ttdk.fun`| 承载 Tunnel 的"回退源"，用户不直接感知
|
||||
**优选 IP 调度器**| [isp.qzz.io](<https://isp.qzz.io/>)| 像"交警"，告诉流量该走哪条不堵的路
|
||||
**中转域名**| `cdn.justdo.xin`| 作为跳板，把主力域名引向优选 IP 池
|
||||
|
||||
## 🔧 故障排查
|
||||
|
||||
### SSL 证书一直显示 Pending？
|
||||
|
||||
**可能原因** ：
|
||||
|
||||
* TXT 记录添加错误或未生效
|
||||
* DNS 传播未完成
|
||||
|
||||
**解决方法** ：
|
||||
|
||||
1. 使用 [DNS 检查工具](<https://dnschecker.org/>) 验证 TXT 记录
|
||||
2. 等待 DNS 全球传播（最多 24 小时）
|
||||
3. 重新添加 Custom Hostname
|
||||
|
||||
### 访问显示 526 错误？
|
||||
|
||||
**可能原因** ：
|
||||
|
||||
* 辅助域名的 `hapi` 记录未开启代理（小黄云）
|
||||
* Tunnel 未正确配置
|
||||
|
||||
**解决方法** ：
|
||||
|
||||
1. 确保 `hapi.ttdk.fun` 的小黄云是**开启** 状态
|
||||
2. 检查 Tunnel 是否正常运行
|
||||
|
||||
### 访问仍然很慢？
|
||||
|
||||
**可能原因** ：
|
||||
|
||||
* 主力域名的 CNAME 记录开启了代理
|
||||
* DNS 解析链断裂
|
||||
|
||||
**解决方法** ：
|
||||
|
||||
1. 确保 `hapi.justdo.xin` 和 `cdn.justdo.xin` 的小黄云都是**关闭** 状态
|
||||
2. 使用 `nslookup` 检查 DNS 解析链是否完整
|
||||
|
||||
## 🚀 进阶优化
|
||||
|
||||
### 自建优选 IP 服务
|
||||
|
||||
如果你追求极致稳定，可以：
|
||||
|
||||
1. 使用 CloudflareSpeedTest 工具本地测速
|
||||
2. 手动选择最优 IP
|
||||
3. 创建自己的优选域名，替代 `isp.qzz.io`
|
||||
|
||||
### 多运营商优化
|
||||
|
||||
可以针对不同运营商配置不同的优选路径：
|
||||
|
||||
* 电信用户：`cdn-ct.yourdomain.com`
|
||||
* 联通用户：`cdn-cu.yourdomain.com`
|
||||
* 移动用户：`cdn-cm.yourdomain.com`
|
||||
|
||||
通过 DNS 智能解析（GeoDNS），根据用户运营商返回不同的 CNAME 记录。
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
* [Cloudflare for SaaS 官方文档](<https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/>)
|
||||
* [Cloudflare Tunnel 文档](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/>)
|
||||
* [isp.qzz.io - 优选 IP 调度器](<https://isp.qzz.io/>)
|
||||
* [视频教程：cloudflare优选IP配置](<https://www.bilibili.com/video/BV1PPy6YzE5C>)
|
||||
|
||||
## ⚠️ 安全提醒
|
||||
|
||||
1. 不要泄露你的 Tunnel 令牌
|
||||
2. 定期检查 Custom Hostnames 配置
|
||||
3. [isp.qzz.io](<https://isp.qzz.io/>) 是社区维护的优选 IP 服务，虽然可靠但非官方服务，你也可以选择自建优选服务
|
||||
4. 建议配合 Cloudflare Access 限制访问来源
|
||||
|
||||
## 💡 总结
|
||||
|
||||
通过这套配置，你：
|
||||
|
||||
* ✅ 不花一分钱
|
||||
* ✅ 利用 Cloudflare 企业级 SaaS 功能
|
||||
* ✅ 把原本几百毫秒延迟的内网穿透，优化到接近直连的体验
|
||||
* ✅ 打造了一条"高速内网穿透通道"
|
||||
|
||||
这就是目前免费方案中，提升 Cloudflare 内网穿透速度的**天花板级别配置** ！
|
||||
|
||||
* * *
|
||||
|
||||
**下一步** ：配置完成后，你可以愉快地在任何地方高速访问你的 Hapi 服务了！🎉
|
||||
|
||||
@ -1,197 +1,197 @@
|
||||
# Hapi 远程控制配置指南
|
||||
|
||||
**随时随地远程控制你的 AI 编程助手**
|
||||
|
||||
> **作者** ：[weishu](<https://github.com/tiann>)**官方文档** ：<https://hapi.run/>
|
||||
|
||||
📋 简介
|
||||
|
||||
Hapi 是一个本地优先的应用程序，可以让你在本地运行 Claude Code / Codex / Gemini 会话，并通过 Web / PWA / Telegram Mini App 进行远程控制。这意味着你可以在手机或浏览器上监控和管理你的 AI 编程任务。
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
资源| 地址
|
||||
---|---
|
||||
Hapi 官网| <https://hapi.run/>
|
||||
Hapi 仓库| <https://github.com/tiann/hapi>
|
||||
快速开始| [官方快速开始文档](<https://hapi.run/docs/guide/quick-start>)
|
||||
Cloudflare Tunnel 文档| [创建远程隧道](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>)
|
||||
|
||||
## ✨ 核心功能
|
||||
|
||||
Hapi 提供以下强大功能：
|
||||
|
||||
* ✅ **无缝切换** ：在本地原生环境和远程控制之间无缝切换
|
||||
* ✅ **远程会话** ：从任何设备发起远程会话
|
||||
* ✅ **移动监控** ：通过手机或浏览器监控和管理任务
|
||||
* ✅ **权限控制** ：远程批准/拒绝工具权限
|
||||
* ✅ **文件浏览** ：浏览文件和查看 git diff
|
||||
* ✅ **进度跟踪** ：通过待办事项列表跟踪进度
|
||||
* ✅ **多后端支持** ：支持 Claude Code、Codex、Gemini
|
||||
|
||||
## 🛠️ 安装步骤
|
||||
|
||||
### 第一步：安装 Hapi
|
||||
|
||||
💡 前置要求
|
||||
|
||||
请确保已安装 Node.js 18+ 环境。如需安装，请参考 [Node.js 环境安装](</node/windows>)。
|
||||
|
||||
访问 [Hapi 官方快速开始文档](<https://hapi.run/docs/guide/quick-start>) 了解详细的安装方法。
|
||||
|
||||
推荐使用 npx 快速启动 Hapi 服务器：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
npx @twsxtd/hapi server
|
||||
|
||||
1
|
||||
|
||||
启动后会显示 Token 凭证和访问地址。
|
||||
|
||||
⚠️ 重要提示
|
||||
|
||||
**请务必保存好 Token 凭证！** 这是你连接和控制 Hapi 服务的唯一凭证。
|
||||
|
||||
|
||||
|
||||
### 第二步：启动 AI 会话
|
||||
|
||||
在项目目录下执行以下命令启动对应的 AI 服务：
|
||||
|
||||
**启动 Claude Code** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
hapi claude
|
||||
|
||||
1
|
||||
|
||||
**启动 Codex** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
hapi codex
|
||||
|
||||
1
|
||||
|
||||
**启动 Gemini** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
hapi gemini
|
||||
|
||||
1
|
||||
|
||||
|
||||
|
||||
启动成功后，前端界面会显示连接状态：
|
||||
|
||||
|
||||
|
||||
🎉 局域网访问
|
||||
|
||||
此时你已经可以在本地局域网内通过 `http://<server-ip>:3006` 访问和控制你的 AI 编程助手了！
|
||||
|
||||
## 🌐 配置 Cloudflare 内网穿透
|
||||
|
||||
如果你想在任何地方（包括外网）访问你的 Hapi 服务，可以通过 Cloudflare Tunnel 实现内网穿透。
|
||||
|
||||
### 前置要求
|
||||
|
||||
* 一个域名（任意域名均可）
|
||||
* Cloudflare 账号（免费账号即可）
|
||||
|
||||
### 配置流程
|
||||
|
||||
按照 [Cloudflare Tunnel 官方文档](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>) 进行配置：
|
||||
|
||||
**1\. 登录 Cloudflare Zero Trust 控制台**
|
||||
|
||||
|
||||
|
||||
**2\. 创建新的 Tunnel**
|
||||
|
||||
|
||||
|
||||
**3\. 安装 cloudflared 客户端**
|
||||
|
||||
|
||||
|
||||
**4\. 配置隧道名称**
|
||||
|
||||
|
||||
|
||||
**5\. 配置公共主机名**
|
||||
|
||||
|
||||
|
||||
**6\. 设置服务地址**
|
||||
|
||||
将服务地址设置为 `localhost:3006`（Hapi 默认端口）
|
||||
|
||||
|
||||
|
||||
**7\. 完成配置**
|
||||
|
||||
|
||||
|
||||
## ✅ 使用 Hapi
|
||||
|
||||
配置完成后，你可以：
|
||||
|
||||
1. **本地访问** ：`http://localhost:3006`
|
||||
2. **局域网访问** ：`http://<server-ip>:3006`
|
||||
3. **公网访问** ：`https://your-domain.com`（如果配置了 Cloudflare Tunnel）
|
||||
|
||||
使用步骤：
|
||||
|
||||
1. 打开浏览器访问 Hapi 地址
|
||||
2. 输入 Token 登录
|
||||
3. 选择要启动的 AI 后端（Claude / Codex / Gemini）
|
||||
4. 开始远程控制你的 AI 编程助手
|
||||
|
||||
💡 使用技巧
|
||||
|
||||
* 在手机浏览器中访问可以随时随地监控任务进度
|
||||
* 可以安装为 PWA 应用，获得类似原生应用的体验
|
||||
* 支持多设备同时连接和控制
|
||||
|
||||
## 🔒 安全建议
|
||||
|
||||
* 不要将 Token 泄露给他人
|
||||
* 如果使用公网访问，建议启用 Cloudflare 的安全功能（如 Access 策略）
|
||||
* 定期更换 Token
|
||||
* 仅在可信网络环境下使用
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 提示无法连接到服务器？
|
||||
|
||||
* 检查 Hapi 服务是否正常运行
|
||||
* 确认防火墙未阻止 3006 端口
|
||||
* 检查 Token 是否正确
|
||||
|
||||
### Cloudflare Tunnel 配置失败？
|
||||
|
||||
* 确认域名已正确添加到 Cloudflare
|
||||
* 检查 cloudflared 客户端是否正确安装
|
||||
* 查看 cloudflared 日志排查问题
|
||||
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](</support/faq>) 或访问 [Hapi GitHub Issues](<https://github.com/tiann/hapi/issues>)。
|
||||
|
||||
## 🚀 进阶优化
|
||||
|
||||
如果你想进一步提升 Hapi 的访问速度（特别是在国内网络环境下），可以配置 Cloudflare 优选 IP：
|
||||
|
||||
💡 速度优化
|
||||
|
||||
通过配置 Cloudflare 优选 IP，可以将访问延迟从几百毫秒降低到几十毫秒，实现接近直连的体验。
|
||||
|
||||
👉 查看详细教程：[Hapi 进阶：Cloudflare 优选 IP 高速穿透](</apps/hapi-advanced>)
|
||||
# Hapi 远程控制配置指南
|
||||
|
||||
**随时随地远程控制你的 AI 编程助手**
|
||||
|
||||
> **作者** ：[weishu](<https://github.com/tiann>)**官方文档** ：<https://hapi.run/>
|
||||
|
||||
📋 简介
|
||||
|
||||
Hapi 是一个本地优先的应用程序，可以让你在本地运行 Claude Code / Codex / Gemini 会话，并通过 Web / PWA / Telegram Mini App 进行远程控制。这意味着你可以在手机或浏览器上监控和管理你的 AI 编程任务。
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
资源| 地址
|
||||
---|---
|
||||
Hapi 官网| <https://hapi.run/>
|
||||
Hapi 仓库| <https://github.com/tiann/hapi>
|
||||
快速开始| [官方快速开始文档](<https://hapi.run/docs/guide/quick-start>)
|
||||
Cloudflare Tunnel 文档| [创建远程隧道](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>)
|
||||
|
||||
## ✨ 核心功能
|
||||
|
||||
Hapi 提供以下强大功能：
|
||||
|
||||
* ✅ **无缝切换** ：在本地原生环境和远程控制之间无缝切换
|
||||
* ✅ **远程会话** ：从任何设备发起远程会话
|
||||
* ✅ **移动监控** ：通过手机或浏览器监控和管理任务
|
||||
* ✅ **权限控制** ：远程批准/拒绝工具权限
|
||||
* ✅ **文件浏览** ：浏览文件和查看 git diff
|
||||
* ✅ **进度跟踪** ：通过待办事项列表跟踪进度
|
||||
* ✅ **多后端支持** ：支持 Claude Code、Codex、Gemini
|
||||
|
||||
## 🛠️ 安装步骤
|
||||
|
||||
### 第一步：安装 Hapi
|
||||
|
||||
💡 前置要求
|
||||
|
||||
请确保已安装 Node.js 18+ 环境。如需安装，请参考 [Node.js 环境安装](</node/windows>)。
|
||||
|
||||
访问 [Hapi 官方快速开始文档](<https://hapi.run/docs/guide/quick-start>) 了解详细的安装方法。
|
||||
|
||||
推荐使用 npx 快速启动 Hapi 服务器：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
npx @twsxtd/hapi server
|
||||
|
||||
1
|
||||
|
||||
启动后会显示 Token 凭证和访问地址。
|
||||
|
||||
⚠️ 重要提示
|
||||
|
||||
**请务必保存好 Token 凭证！** 这是你连接和控制 Hapi 服务的唯一凭证。
|
||||
|
||||
|
||||
|
||||
### 第二步：启动 AI 会话
|
||||
|
||||
在项目目录下执行以下命令启动对应的 AI 服务：
|
||||
|
||||
**启动 Claude Code** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
hapi claude
|
||||
|
||||
1
|
||||
|
||||
**启动 Codex** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
hapi codex
|
||||
|
||||
1
|
||||
|
||||
**启动 Gemini** ：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
hapi gemini
|
||||
|
||||
1
|
||||
|
||||
|
||||
|
||||
启动成功后，前端界面会显示连接状态：
|
||||
|
||||
|
||||
|
||||
🎉 局域网访问
|
||||
|
||||
此时你已经可以在本地局域网内通过 `http://<server-ip>:3006` 访问和控制你的 AI 编程助手了！
|
||||
|
||||
## 🌐 配置 Cloudflare 内网穿透
|
||||
|
||||
如果你想在任何地方（包括外网）访问你的 Hapi 服务，可以通过 Cloudflare Tunnel 实现内网穿透。
|
||||
|
||||
### 前置要求
|
||||
|
||||
* 一个域名（任意域名均可）
|
||||
* Cloudflare 账号（免费账号即可）
|
||||
|
||||
### 配置流程
|
||||
|
||||
按照 [Cloudflare Tunnel 官方文档](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>) 进行配置：
|
||||
|
||||
**1\. 登录 Cloudflare Zero Trust 控制台**
|
||||
|
||||
|
||||
|
||||
**2\. 创建新的 Tunnel**
|
||||
|
||||
|
||||
|
||||
**3\. 安装 cloudflared 客户端**
|
||||
|
||||
|
||||
|
||||
**4\. 配置隧道名称**
|
||||
|
||||
|
||||
|
||||
**5\. 配置公共主机名**
|
||||
|
||||
|
||||
|
||||
**6\. 设置服务地址**
|
||||
|
||||
将服务地址设置为 `localhost:3006`（Hapi 默认端口）
|
||||
|
||||
|
||||
|
||||
**7\. 完成配置**
|
||||
|
||||
|
||||
|
||||
## ✅ 使用 Hapi
|
||||
|
||||
配置完成后，你可以：
|
||||
|
||||
1. **本地访问** ：`http://localhost:3006`
|
||||
2. **局域网访问** ：`http://<server-ip>:3006`
|
||||
3. **公网访问** ：`https://your-domain.com`（如果配置了 Cloudflare Tunnel）
|
||||
|
||||
使用步骤：
|
||||
|
||||
1. 打开浏览器访问 Hapi 地址
|
||||
2. 输入 Token 登录
|
||||
3. 选择要启动的 AI 后端（Claude / Codex / Gemini）
|
||||
4. 开始远程控制你的 AI 编程助手
|
||||
|
||||
💡 使用技巧
|
||||
|
||||
* 在手机浏览器中访问可以随时随地监控任务进度
|
||||
* 可以安装为 PWA 应用，获得类似原生应用的体验
|
||||
* 支持多设备同时连接和控制
|
||||
|
||||
## 🔒 安全建议
|
||||
|
||||
* 不要将 Token 泄露给他人
|
||||
* 如果使用公网访问，建议启用 Cloudflare 的安全功能（如 Access 策略）
|
||||
* 定期更换 Token
|
||||
* 仅在可信网络环境下使用
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 提示无法连接到服务器？
|
||||
|
||||
* 检查 Hapi 服务是否正常运行
|
||||
* 确认防火墙未阻止 3006 端口
|
||||
* 检查 Token 是否正确
|
||||
|
||||
### Cloudflare Tunnel 配置失败？
|
||||
|
||||
* 确认域名已正确添加到 Cloudflare
|
||||
* 检查 cloudflared 客户端是否正确安装
|
||||
* 查看 cloudflared 日志排查问题
|
||||
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](</support/faq>) 或访问 [Hapi GitHub Issues](<https://github.com/tiann/hapi/issues>)。
|
||||
|
||||
## 🚀 进阶优化
|
||||
|
||||
如果你想进一步提升 Hapi 的访问速度（特别是在国内网络环境下），可以配置 Cloudflare 优选 IP：
|
||||
|
||||
💡 速度优化
|
||||
|
||||
通过配置 Cloudflare 优选 IP，可以将访问延迟从几百毫秒降低到几十毫秒，实现接近直连的体验。
|
||||
|
||||
👉 查看详细教程：[Hapi 进阶：Cloudflare 优选 IP 高速穿透](</apps/hapi-advanced>)
|
||||
|
||||
@ -1,498 +1,339 @@
|
||||
# OpenClaw 配置指南
|
||||
# OpenClaw 配置指南
|
||||
|
||||
**多平台 AI 编程代理，支持终端 TUI、Web Dashboard 和 Telegram Bot**
|
||||
|
||||
📋 简介
|
||||
## 📋 简介
|
||||
|
||||
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
|
||||
2
|
||||
3
|
||||
4
|
||||
- ✅ **终端 TUI**：命令行交互界面，适合 SSH 环境
|
||||
- ✅ **Web Dashboard**：浏览器可视化管理面板
|
||||
- ✅ **Telegram Bot**：支持通过 Telegram 远程对话
|
||||
- ✅ **多模型支持**：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 终端中运行以下命令：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
|
||||
1
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
耐心等待安装流程结束。
|
||||
|
||||
### 第二步：初始化配置
|
||||
### 第二步：初始化配置
|
||||
|
||||
安装过程中会依次出现以下选项，按照说明操作：
|
||||
安装过程中会依次出现以下选项，按说明选择：
|
||||
|
||||
步骤| 选择| 说明
|
||||
---|---|---
|
||||
启动方式| **QuickStart**| 快速开始模式
|
||||
供应商设置| **Skip for now**| 先跳过，后续手动编辑配置文件
|
||||
适配器选择| **anthropic**| 选择 Anthropic 适配器
|
||||
模型选择| **opus-4.5**| 或选择你需要的模型
|
||||
社交适配器| 按需选择| 如 Telegram（可选）
|
||||
Skill 安装| 跳过| 后续可通过 Dashboard 安装
|
||||
Hook 选择| 全选| 使用空格键全选后回车确认
|
||||
打开方式| 跳过| 先跳过
|
||||
Shell 补全| **yes**| 安装命令行自动补全
|
||||
|
||||
## ⚙️ 渠道与模型配置
|
||||
| 步骤 | 选择 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 启动方式 | **QuickStart** | 快速开始模式 |
|
||||
| 供应商设置 | **Skip for now** | 先跳过，后续手动编辑配置文件 |
|
||||
| 适配器选择 | **anthropic** | 选择 Anthropic 适配器 |
|
||||
| 模型选择 | **opus-4.5** | 或选择你需要的模型 |
|
||||
| 社交适配器 | 按需选择 | 如 Telegram（可选） |
|
||||
| Skill 安装 | 跳过 | 后续可通过 Dashboard 安装 |
|
||||
| Hook 选择 | 全选 | 使用空格键全选后回车确认 |
|
||||
| 打开方式 | 跳过 | 先跳过 |
|
||||
| Shell 补全 | **yes** | 安装命令行自动补全 |
|
||||
|
||||
### 第一步：编辑配置文件
|
||||
## ⚙️ 渠道与模型配置
|
||||
|
||||
### 第一步：编辑配置文件
|
||||
|
||||
打开 OpenClaw 的配置文件进行编辑：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
vim ~/.openclaw/openclaw.json
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
请在 [创建专属 Key](</guide/create-key>) 时选择逆向分组。
|
||||
|
||||
### 第三步：重启网关
|
||||
|
||||
bash
|
||||
|
||||
|
||||
openclaw gateway restart
|
||||
|
||||
1
|
||||
|
||||
### 第四步：验证配置
|
||||
### 第四步：验证配置
|
||||
|
||||
运行以下命令进入 TUI 界面测试模型是否正常：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
openclaw tui
|
||||
|
||||
1
|
||||
```bash
|
||||
openclaw tui
|
||||
```
|
||||
|
||||
测试成功后输入 `/quit` 退出 TUI。
|
||||
|
||||
## 🌐 浏览器访问 Dashboard
|
||||
## 🌐 浏览器访问 Dashboard
|
||||
|
||||
### 获取 Dashboard URL
|
||||
### 获取 Dashboard URL
|
||||
|
||||
在控制台运行命令获取 Dashboard URL，在浏览器中访问即可进入管理面板。
|
||||
|
||||
⚠️ 服务器用户注意
|
||||
> ⚠️ **服务器用户注意**
|
||||
> 如果你在远程服务器上运行 OpenClaw，需要完成以下额外步骤。
|
||||
|
||||
如果你在远程服务器运行 OpenClaw，需要：
|
||||
**1. 配置反向代理**
|
||||
|
||||
**1\. 配置反向代理**
|
||||
使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并配置 SSL 证书。
|
||||
|
||||
使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并设置 SSL 证书。
|
||||
|
||||
**2\. 修改配置文件**
|
||||
**2. 修改配置文件**
|
||||
|
||||
编辑 `~/.openclaw/openclaw.json`，在 `gateway` 字段下添加：
|
||||
|
||||
json
|
||||
|
||||
|
||||
"controlUi": {
|
||||
"allowInsecureAuth": true
|
||||
}
|
||||
```json
|
||||
"controlUi": {
|
||||
"allowInsecureAuth": true
|
||||
}
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
**3. 重启网关**
|
||||
|
||||
**3\. 重启网关**
|
||||
|
||||
bash
|
||||
|
||||
|
||||
openclaw gateway restart
|
||||
|
||||
1
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
访问带有 Token 的 Dashboard URL 即可进入后台界面。
|
||||
|
||||
## 🤖 配置 Telegram Bot（可选）
|
||||
## 🤖 配置 Telegram Bot（可选）
|
||||
|
||||
如果安装时选择了 Telegram 适配器，可以通过以下步骤配置 Bot 访问权限：
|
||||
如果安装时选择了 Telegram 适配器，可以通过以下步骤配置 Bot 访问权限。
|
||||
|
||||
### 第一步：与 Bot 对话
|
||||
### 第一步：与 Bot 对话
|
||||
|
||||
在 Telegram 中找到你通过 **@BotFather** 创建的机器人，发起对话。
|
||||
|
||||
### 第二步：获取 Pairing Code
|
||||
### 第二步：获取 Pairing Code
|
||||
|
||||
首次对话后会收到一个 **Pairing Code** 。
|
||||
首次对话后会收到一个 **Pairing Code**。
|
||||
|
||||
### 第三步：授权配对
|
||||
### 第三步：授权配对
|
||||
|
||||
在控制台运行以下命令完成授权：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
openclaw pairing approve telegram 你的Pairing_Code
|
||||
|
||||
1
|
||||
```bash
|
||||
openclaw pairing approve telegram 你的Pairing_Code
|
||||
```
|
||||
|
||||
配对成功后，即可通过 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
|
||||
|
||||
|
||||
{
|
||||
"messages": {
|
||||
"ackReactionScope": "group-mentions"
|
||||
```json
|
||||
{
|
||||
"messages": {
|
||||
"ackReactionScope": "group-mentions"
|
||||
},
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "oneinai-claude/claude-opus-4-5-20251101"
|
||||
},
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "ikuncode-claude/claude-opus-4-5-20251101"
|
||||
},
|
||||
"maxConcurrent": 4,
|
||||
"subagents": {
|
||||
"maxConcurrent": 8
|
||||
},
|
||||
"compaction": {
|
||||
"mode": "safeguard"
|
||||
},
|
||||
"workspace": "C:\\\\Users\\\\Administrator\\\\.openclaw\\\\workspace"
|
||||
}
|
||||
"maxConcurrent": 4,
|
||||
"subagents": {
|
||||
"maxConcurrent": 8
|
||||
},
|
||||
"models": {
|
||||
"providers": {
|
||||
"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
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
"compaction": {
|
||||
"mode": "safeguard"
|
||||
},
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"auth": {
|
||||
"mode": "token",
|
||||
"token": "xxxx"
|
||||
"workspace": "C:\\\\Users\\\\Administrator\\\\.openclaw\\\\workspace"
|
||||
}
|
||||
},
|
||||
"models": {
|
||||
"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,
|
||||
"bind": "loopback",
|
||||
"tailscale": {
|
||||
"mode": "off",
|
||||
"resetOnExit": false
|
||||
}
|
||||
},
|
||||
"auth": {
|
||||
"profiles": {}
|
||||
},
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"telegram": {
|
||||
"enabled": true
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"botToken": "xxxxx"
|
||||
}
|
||||
},
|
||||
"logging": {
|
||||
"level": "trace",
|
||||
"consoleLevel": "debug",
|
||||
"consoleStyle": "pretty"
|
||||
},
|
||||
"commands": {
|
||||
"restart": true
|
||||
},
|
||||
"skills": {
|
||||
"install": {
|
||||
"nodeManager": "npm"
|
||||
}
|
||||
"oneinai-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
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
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
|
||||
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"
|
||||
},
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"auth": {
|
||||
"mode": "token",
|
||||
"token": "xxxx"
|
||||
},
|
||||
"port": 18789,
|
||||
"bind": "loopback",
|
||||
"tailscale": {
|
||||
"mode": "off",
|
||||
"resetOnExit": false
|
||||
}
|
||||
},
|
||||
"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` 必须保持示例格式，否则请求会被拦截
|
||||
* 配置完成后执行 `openclaw gateway restart` 重启网关
|
||||
> ⚠️ **注意事项**
|
||||
> - **Headers 中的 Authorization** 必须与 `apiKey` 保持一致，格式为 `Bearer sk-xxxx`
|
||||
> - **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)
|
||||
|
||||
@ -36,7 +36,7 @@ bash
|
||||
|
||||
安装完成后，在终端输入 `opencode` 命令，若出现 TUI 界面则安装成功。
|
||||
|
||||
|
||||
|
||||
|
||||
### 第二步：安装 CC-Switch
|
||||
|
||||
@ -48,7 +48,7 @@ bash
|
||||
|
||||
打开 CC-Switch，上方配置项选择 `OpenCode`，然后点击 **添加供应商** 按钮。
|
||||
|
||||
|
||||
|
||||
|
||||
**2\. 填写供应商信息**
|
||||
|
||||
@ -66,7 +66,7 @@ bash
|
||||
|
||||
根据你需要的模型类型，选择正确分组的 API Key：
|
||||
|
||||
|
||||
|
||||
|
||||
* **Claude 系列** ：只允许逆向分组
|
||||
* **GPT 系列** ：Codex 分组
|
||||
@ -80,11 +80,11 @@ bash
|
||||
2. 输入 `/models` 命令，检查配置的渠道是否出现在模型列表中
|
||||
3. 如果能看到你添加的模型，说明配置成功
|
||||
|
||||
|
||||
|
||||
|
||||
开始愉快地编码吧！🎉
|
||||
|
||||
|
||||
|
||||
|
||||
## 常见问题
|
||||
|
||||
@ -100,4 +100,4 @@ bash
|
||||
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。
|
||||
请查看 [FAQ](</support/faq>)
|
||||
|
||||
@ -336,4 +336,4 @@ source ~/.zshrc
|
||||
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](/support/faq) 或联系 [售后支持](/support/after-sales)。
|
||||
请查看 [FAQ](/support/faq)
|
||||
|
||||
@ -1,393 +1,283 @@
|
||||
# CodeX 部署指南
|
||||
# CodeX 部署指南
|
||||
|
||||
**企业级 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 快速配置工具](</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 应用程序
|
||||
2. 点击顶部的「Codex」标签页
|
||||
3. 点击右上角橙色「+」按钮添加新配置
|
||||
|
||||
|
||||
|
||||
|
||||
> 💡 **提示**
|
||||
> - CC-Switch 会自动创建 `~/.codex/config.toml` 和 `auth.json` 文件
|
||||
> - 可以添加多个提供商配置，随时切换
|
||||
> - 切换配置后，关闭并重启 CodeX 即可生效
|
||||
|
||||
**2\. 填写 CodeX 提供商配置**
|
||||
**3. 启用配置并使用**
|
||||
|
||||
1. **提供商名称** ：自定义名称（如「IkunCoding」）
|
||||
2. **Base URL** ：输入 `https://api.oneinai.com/v1`
|
||||
3. **API Key** ：粘贴您从 IkunCode 平台获取的 CodeX 专用令牌（codex令牌组）
|
||||
4. **Model** ：选择 `gpt-5.4`（书写文档时最新模型为 5.4）
|
||||
5. **其他配置** ：根据需求调整推理强度、网络访问等参数
|
||||
6. 点击「保存」按钮
|
||||
1. 在配置列表中找到刚创建的「oneinai」配置
|
||||
2. 点击配置右侧的「当前使用」按钮
|
||||
3. 配置会被标记为「当前使用」状态（绿色标签）
|
||||
4. 重启 CodeX，新配置即可生效
|
||||
|
||||
|
||||
|
||||
💡 提示
|
||||
|
||||
* CC-Switch 会自动创建 `~/.codex/config.toml` 和 `auth.json` 文件
|
||||
* 可以添加多个提供商配置，随时切换
|
||||
* 切换配置后，关闭并重启 CodeX 即可生效
|
||||
|
||||
**3\. 启用配置并使用**
|
||||
|
||||
1. 在配置列表中找到刚创建的「IkunCoding」配置
|
||||
2. 点击配置右侧的「当前使用」按钮
|
||||
3. 配置会被标记为「当前使用」状态（绿色标签）
|
||||
4. 重启 CodeX，新配置即可生效
|
||||
|
||||
**4\. 系统托盘快速切换**
|
||||
**4. 系统托盘快速切换**
|
||||
|
||||
CC-Switch 支持通过系统托盘快速切换 CodeX 配置：
|
||||
|
||||
* 右键点击系统托盘中的 CC-Switch 图标
|
||||
* 在菜单中选择 Codex 分类
|
||||
* 直接选择要切换到的配置
|
||||
* 配置立即生效，无需打开主界面
|
||||
- 右键点击系统托盘中的 CC-Switch 图标
|
||||
- 在菜单中选择 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
|
||||
|
||||
|
||||
npm install -g @openai/codex@latest
|
||||
codex --version
|
||||
```powershell
|
||||
npm install -g @openai/codex@latest
|
||||
codex --version
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
#### 第二步：集成 oneinai API 服务
|
||||
|
||||
#### 第二步：集成 IkunCoding API 服务
|
||||
**获取专属 API 凭证**：
|
||||
|
||||
**获取专属 API 凭证** ：
|
||||
1. 访问 [oneinai 控制台](https://api.oneinai.com/console/token)
|
||||
2. 完成账户注册或登录
|
||||
3. 进入「API 密钥管理」模块
|
||||
4. 创建新密钥时务必选择「codex」令牌组
|
||||
5. 安全保存生成的 API Key
|
||||
|
||||
1. 访问 IkunCoding 开发者控制台
|
||||
2. 完成账户注册或执行登录操作
|
||||
3. 导航至「API 密钥管理」模块
|
||||
4. 创建新密钥时，务必选择「codex」令牌组
|
||||
5. 安全保存生成的 API Key
|
||||
> 🔐 **安全提醒**
|
||||
> CodeX 要求使用独立的令牌组配置，与 Claude Code 令牌体系完全隔离。
|
||||
|
||||
🔐 安全提醒
|
||||
**构建配置目录结构**：
|
||||
|
||||
CodeX 要求使用独立的令牌组配置，与 Claude Code 令牌体系完全隔离。
|
||||
```powershell
|
||||
mkdir $env:USERPROFILE\.codex
|
||||
cd $env:USERPROFILE\.codex
|
||||
```
|
||||
|
||||
**构建配置目录结构** ：
|
||||
**编写配置文件 `config.toml`**：
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
mkdir %USERPROFILE%\\.codex
|
||||
cd %USERPROFILE%\\.codex
|
||||
```toml
|
||||
model_provider = "oneinai"
|
||||
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
|
||||
|
||||
1
|
||||
2
|
||||
[model_providers.oneinai]
|
||||
name = "oneinai"
|
||||
base_url = "https://api.oneinai.com/v1"
|
||||
wire_api = "responses"
|
||||
requires_openai_auth = true
|
||||
```
|
||||
|
||||
**编写配置文件：config.toml**
|
||||
**编写认证文件 `auth.json`**：
|
||||
|
||||
toml
|
||||
|
||||
|
||||
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
|
||||
```json
|
||||
{
|
||||
"OPENAI_API_KEY": "此处粘贴你的 CodeX 专用令牌"
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
{
|
||||
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
|
||||
}
|
||||
### 🍏 macOS 平台
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
#### 部署 CodeX 工具
|
||||
|
||||
#### 第三步：初始化工作空间
|
||||
```bash
|
||||
npm install -g @openai/codex@latest
|
||||
codex --version
|
||||
```
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
mkdir my-codex-project
|
||||
cd my-codex-project
|
||||
codex
|
||||
#### 集成 API 服务
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
**构建配置目录**：
|
||||
|
||||
### 🍏 macOS 平台
|
||||
```bash
|
||||
mkdir -p ~/.codex
|
||||
cd ~/.codex
|
||||
```
|
||||
|
||||
#### 部署 CodeX 工具
|
||||
**编写 `config.toml` 配置**：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
npm install -g @openai/codex@latest
|
||||
codex --version
|
||||
```bash
|
||||
cat > config.toml << 'EOF'
|
||||
model_provider = "oneinai"
|
||||
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
|
||||
|
||||
1
|
||||
2
|
||||
[model_providers.oneinai]
|
||||
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
|
||||
2
|
||||
```bash
|
||||
mkdir my-codex-project
|
||||
cd my-codex-project
|
||||
codex
|
||||
```
|
||||
|
||||
**编写 config.toml 配置** ：
|
||||
### 🐧 Linux 平台
|
||||
|
||||
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
|
||||
#### 部署 CodeX 工具
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
13
|
||||
14
|
||||
15
|
||||
```bash
|
||||
sudo npm install -g @openai/codex@latest
|
||||
codex --version
|
||||
```
|
||||
|
||||
**编写 auth.json 认证配置** ：
|
||||
#### 集成 API 服务
|
||||
|
||||
bash
|
||||
|
||||
|
||||
cat > auth.json << 'EOF'
|
||||
{
|
||||
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
|
||||
}
|
||||
EOF
|
||||
**构建配置目录**：
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
```bash
|
||||
mkdir -p ~/.codex
|
||||
cd ~/.codex
|
||||
```
|
||||
|
||||
#### 初始化工作空间
|
||||
**编写 `config.toml` 配置**：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
mkdir my-codex-project
|
||||
cd my-codex-project
|
||||
codex
|
||||
```bash
|
||||
cat > config.toml << 'EOF'
|
||||
model_provider = "oneinai"
|
||||
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
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
[model_providers.oneinai]
|
||||
name = "oneinai"
|
||||
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
|
||||
2
|
||||
```bash
|
||||
mkdir my-codex-project
|
||||
cd my-codex-project
|
||||
codex
|
||||
```
|
||||
|
||||
#### 集成 API 服务
|
||||
## ❓ 常见问题
|
||||
|
||||
**构建配置目录** ：
|
||||
|
||||
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 的令牌不通用？
|
||||
### CodeX 和 Claude Code 的令牌不通用？
|
||||
|
||||
是的，两者使用不同的令牌组：
|
||||
|
||||
* Claude Code: 使用 Claude Code 令牌组
|
||||
* CodeX: 使用 "codex" 令牌组
|
||||
- Claude Code：使用 Claude Code 令牌组
|
||||
- CodeX：使用 `codex` 令牌组
|
||||
|
||||
请在 IkunCode 平台创建对应的专用令牌。
|
||||
请在 oneinai 平台创建对应的专用令牌。
|
||||
|
||||
### 配置文件放在哪里？
|
||||
### 配置文件放在哪里？
|
||||
|
||||
* Windows: `%USERPROFILE%\\.codex\\`
|
||||
* macOS/Linux: `~/.codex/`
|
||||
- Windows：`%USERPROFILE%\.codex\`
|
||||
- macOS / Linux：`~/.codex/`
|
||||
|
||||
### 更多问题
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。
|
||||
请查看 [FAQ](/support/faq)
|
||||
|
||||
@ -1,347 +1,259 @@
|
||||
# Gemini CLI 安装步骤
|
||||
# Gemini CLI 安装步骤
|
||||
|
||||
**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>) 进行图形化配置，简单快捷无需手动创建配置文件。
|
||||
|
||||
|
||||
### 配置步骤
|
||||
**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. 点击右上角橙色「+」按钮添加新配置
|
||||
填写完成后点击「保存」按钮。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**2\. 填写 Gemini CLI 提供商配置**
|
||||
> 💡 **提示**
|
||||
> - CC-Switch 会自动创建 `~/.gemini/.env` 和 `settings.json` 文件
|
||||
> - 可以添加多个提供商配置，随时切换
|
||||
> - 切换配置后，关闭并重启 Gemini CLI 即可生效
|
||||
|
||||
1. **提供商名称** ：自定义名称（如「ikuncode」）
|
||||
2. **Base URL** ：输入 `https://api.oneinai.com`
|
||||
3. **API Key** ：粘贴您从 IkunCode 平台获取的 Gemini 专用令牌
|
||||
4. **Model** ：选择 `gemini-3-pro-preview` 或其他可用模型
|
||||
5. **安全设置** ：根据需求调整（可选）
|
||||
6. 点击「保存」按钮
|
||||
**3. 启用配置并使用**
|
||||
|
||||
|
||||
1. 在配置列表中找到刚创建的「oneinai」配置
|
||||
2. 点击配置右侧的「当前使用」按钮
|
||||
3. 配置会被标记为「当前使用」状态（绿色标签）
|
||||
4. 重启 Gemini CLI，新配置即可生效
|
||||
|
||||
💡 提示
|
||||
|
||||
* CC-Switch 会自动创建 `~/.gemini/.env` 和 `settings.json` 文件
|
||||
* 可以添加多个提供商配置，随时切换
|
||||
* 切换配置后，关闭并重启 Gemini CLI 即可生效
|
||||
|
||||
**3\. 启用配置并使用**
|
||||
|
||||
1. 在配置列表中找到刚创建的「ikuncode」配置
|
||||
2. 点击配置右侧的「当前使用」按钮
|
||||
3. 配置会被标记为「当前使用」状态（绿色标签）
|
||||
4. 重启 Gemini CLI，新配置即可生效
|
||||
|
||||
**4\. 系统托盘快速切换**
|
||||
**4. 系统托盘快速切换**
|
||||
|
||||
CC-Switch 支持通过系统托盘快速切换 Gemini CLI 配置：
|
||||
|
||||
* 右键点击系统托盘中的 CC-Switch 图标
|
||||
* 在菜单中选择 Gemini 分类
|
||||
* 直接选择要切换到的配置
|
||||
* 配置立即生效，无需打开主界面
|
||||
- 右键点击系统托盘中的 CC-Switch 图标
|
||||
- 在菜单中选择 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
|
||||
|
||||
|
||||
npm install -g @google/gemini-cli
|
||||
#### 2️⃣ 配置 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
|
||||
|
||||
|
||||
GOOGLE_GEMINI_BASE_URL=https://api.oneinai.com
|
||||
GEMINI_API_KEY=你的专属密钥请到https://ikuncode.cc获取
|
||||
GEMINI_MODEL=gemini-3-pro-preview
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
|
||||
**3.3 创建 settings.json 文件**
|
||||
|
||||
在 `gemini` 文件夹新建 `settings.json` 文件：
|
||||
|
||||
json
|
||||
|
||||
|
||||
{
|
||||
"ide": {
|
||||
"enabled": true
|
||||
},
|
||||
"security": {
|
||||
"auth": {
|
||||
"selectedType": "gemini-api-key"
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"ide": {
|
||||
"enabled": true
|
||||
},
|
||||
"security": {
|
||||
"auth": {
|
||||
"selectedType": "gemini-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
#### 3️⃣ 启动 Gemini CLI
|
||||
|
||||
#### 3️⃣ 启动 Gemini CLI
|
||||
```powershell
|
||||
gemini
|
||||
```
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
gemini
|
||||
> 🎉 **开始使用 Gemini CLI**
|
||||
> - 输入上下文描述快速生成代码
|
||||
> - Agent Mode 自动编程模式
|
||||
> - 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
|
||||
|
||||
|
||||
npm install -g @google/gemini-cli
|
||||
```bash
|
||||
mkdir -p ~/.gemini
|
||||
cd ~/.gemini
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
mkdir -p ~/.gemini
|
||||
cd ~/.gemini
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
**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"
|
||||
}
|
||||
}
|
||||
```bash
|
||||
cat > settings.json << 'EOF'
|
||||
{
|
||||
"ide": {
|
||||
"enabled": true
|
||||
},
|
||||
"security": {
|
||||
"auth": {
|
||||
"selectedType": "gemini-api-key"
|
||||
}
|
||||
EOF
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
#### 3️⃣ 启动 Gemini CLI
|
||||
|
||||
#### 3️⃣ 启动 Gemini CLI
|
||||
```bash
|
||||
gemini
|
||||
```
|
||||
|
||||
bash
|
||||
|
||||
|
||||
gemini
|
||||
### 🐧 Linux 平台
|
||||
|
||||
1
|
||||
#### 1️⃣ 全局安装 Gemini CLI
|
||||
|
||||
### 🐧 Linux 安装流程教程
|
||||
```bash
|
||||
sudo npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
#### 1️⃣ 全局安装 Gemini CLI
|
||||
#### 2️⃣ 配置 Gemini CLI
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo npm install -g @google/gemini-cli
|
||||
**2.1 创建配置目录**：
|
||||
|
||||
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
|
||||
|
||||
|
||||
mkdir -p ~/.gemini
|
||||
cd ~/.gemini
|
||||
**2.3 创建 `settings.json` 文件**：
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
**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"
|
||||
}
|
||||
}
|
||||
```bash
|
||||
cat > settings.json << 'EOF'
|
||||
{
|
||||
"ide": {
|
||||
"enabled": true
|
||||
},
|
||||
"security": {
|
||||
"auth": {
|
||||
"selectedType": "gemini-api-key"
|
||||
}
|
||||
EOF
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
#### 3️⃣ 启动 Gemini CLI
|
||||
|
||||
#### 3️⃣ 启动 Gemini CLI
|
||||
```bash
|
||||
gemini
|
||||
```
|
||||
|
||||
bash
|
||||
|
||||
|
||||
gemini
|
||||
> 🎉 **部署完成！**
|
||||
> 现在你可以使用 Gemini CLI 进行 AI 辅助编程了。
|
||||
|
||||
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 专用令牌。
|
||||
### 更多问题
|
||||
|
||||
### 配置文件位置
|
||||
|
||||
* Windows: `%USERPROFILE%\\.gemini\\`
|
||||
* macOS/Linux: `~/.gemini/`
|
||||
|
||||
### 更多问题
|
||||
|
||||
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。
|
||||
请查看 [FAQ](/support/faq)
|
||||
|
||||
@ -1,437 +1,293 @@
|
||||
#  NanoBanana 图像生成部署指南
|
||||
#  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| 特点| 适用场景
|
||||
---|---|---|---
|
||||
**NanoBananaPro**| `gemini-3-pro-image-preview`| 效果最佳，支持高清输出| 高质量海报、商业素材、精细创作
|
||||
**NanoBanana2**| `gemini-3.1-flash-image-preview`| 速度快、价格低| 快速预览、批量生成、日常使用
|
||||
|
||||
💡 如何选择
|
||||
oneinai 提供两个 NanoBanana 模型：
|
||||
|
||||
* 追求**画质** ：选 NanoBananaPro（Pro 版）
|
||||
* 追求**速度和性价比** ：选 NanoBanana2（Flash 版）
|
||||
| 模型 | 模型 ID | 特点 | 适用场景 |
|
||||
| --- | --- | --- | --- |
|
||||
| **NanoBananaPro** | `gemini-3-pro-image-preview` | 效果最佳，支持高清输出 | 高质量海报、商业素材、精细创作 |
|
||||
| **NanoBanana2** | `gemini-3.1-flash-image-preview` | 速度快、价格低 | 快速预览、批量生成、日常使用 |
|
||||
|
||||
## 📐 支持的宽高比
|
||||
> 💡 **如何选择**
|
||||
> - 追求**画质**：选 NanoBananaPro（Pro 版）
|
||||
> - 追求**速度和性价比**：选 NanoBanana2（Flash 版）
|
||||
|
||||
两个模型均支持以下 **10 种宽高比** ：
|
||||
## 📐 支持的宽高比
|
||||
|
||||
宽高比| 说明| 宽高比| 说明
|
||||
---|---|---|---
|
||||
**1:1**| 正方形图片| **3:2**| 相机常用比例（横）
|
||||
**16:9**| 横屏标准比例| **2:3**| 相机常用比例（竖）
|
||||
**9:16**| 竖屏标准比例| **21:9**| 超宽屏比例
|
||||
**4:3**| 传统横屏比例| **5:4**| 显示器比例（横）
|
||||
**3:4**| 传统竖屏比例| **4:5**| 显示器比例（竖）
|
||||
|
||||
## 📏 支持的分辨率
|
||||
两个模型均支持以下 **10 种宽高比**：
|
||||
|
||||
每种宽高比支持三种分辨率等级：
|
||||
| 宽高比 | 说明 | 宽高比 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| **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 分辨率（推荐使用）
|
||||
每种宽高比支持三种分辨率等级。
|
||||
|
||||
宽高比| 分辨率| 宽高比| 分辨率
|
||||
---|---|---|---
|
||||
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 分辨率（超高清）
|
||||
### 1K 分辨率（快速预览）
|
||||
|
||||
宽高比| 分辨率| 宽高比| 分辨率
|
||||
---|---|---|---
|
||||
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 请求格式
|
||||
| 宽高比 | 分辨率 | 宽高比 | 分辨率 |
|
||||
| --- | --- | --- | --- |
|
||||
| 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 分辨率（推荐使用）
|
||||
|
||||
| 宽高比 | 分辨率 | 宽高比 | 分辨率 |
|
||||
| --- | --- | --- | --- |
|
||||
| 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 格式不同。
|
||||
|
||||
### 基本请求结构
|
||||
### 基本请求结构
|
||||
|
||||
json
|
||||
|
||||
|
||||
{
|
||||
"contents": [{
|
||||
"parts": [
|
||||
{ "text": "您的图片描述" }
|
||||
]
|
||||
}],
|
||||
"generationConfig": {
|
||||
"responseModalities": ["IMAGE"],
|
||||
"imageConfig": {
|
||||
"aspectRatio": "16:9",
|
||||
"image_size": "2K"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"contents": [{
|
||||
"parts": [
|
||||
{ "text": "你的图片描述" }
|
||||
]
|
||||
}],
|
||||
"generationConfig": {
|
||||
"responseModalities": ["IMAGE"],
|
||||
"imageConfig": {
|
||||
"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
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
13
|
||||
14
|
||||
### Python 示例
|
||||
|
||||
### 参数说明
|
||||
```python
|
||||
import requests
|
||||
import base64
|
||||
|
||||
参数| 说明| 可选值
|
||||
---|---|---
|
||||
`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
|
||||
API_KEY = "sk-你的oneinai密钥"
|
||||
API_URL = "https://api.oneinai.com/v1beta/models/gemini-3-pro-image-preview:generateContent"
|
||||
|
||||
1
|
||||
|
||||
* 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": [
|
||||
payload = {
|
||||
"contents": [{
|
||||
"parts": [
|
||||
{"text": "一只可爱的小猫咪坐在花园里，油画风格，高清，细节丰富"}
|
||||
]
|
||||
}],
|
||||
"generationConfig": {
|
||||
"responseModalities": ["IMAGE"],
|
||||
"imageConfig": {
|
||||
]
|
||||
}],
|
||||
"generationConfig": {
|
||||
"responseModalities": ["IMAGE"],
|
||||
"imageConfig": {
|
||||
"aspectRatio": "16:9",
|
||||
"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
|
||||
2
|
||||
3
|
||||
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
|
||||
headers = {
|
||||
"Authorization": f"Bearer {API_KEY}",
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
|
||||
### Node.js 示例
|
||||
response = requests.post(API_URL, headers=headers, json=payload, timeout=600)
|
||||
|
||||
javascript
|
||||
|
||||
|
||||
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);
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
image_base64 = data["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
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
|
||||
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)
|
||||
```
|
||||
|
||||
## 🖼️ 图生图编辑
|
||||
### Node.js 示例
|
||||
|
||||
NanoBananaPro 还支持**图生图** 功能，上传一张图片并描述编辑指令，即可对图片进行修改。
|
||||
```javascript
|
||||
const fs = require('fs');
|
||||
|
||||
json
|
||||
|
||||
|
||||
{
|
||||
"contents": [{
|
||||
"parts": [
|
||||
{
|
||||
"inlineData": {
|
||||
"mimeType": "image/png",
|
||||
"data": "图片的Base64编码字符串"
|
||||
}
|
||||
},
|
||||
{ "text": "将背景改为星空，保持人物不变" }
|
||||
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"
|
||||
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);
|
||||
```
|
||||
|
||||
## 🖼️ 图生图编辑
|
||||
|
||||
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
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
13
|
||||
14
|
||||
15
|
||||
16
|
||||
17
|
||||
18
|
||||
19
|
||||
20
|
||||
> 💡 **图生图使用技巧**
|
||||
> - 编辑指令要**具体明确**，说清楚保留什么、修改什么
|
||||
> - 支持换背景、改风格、加元素、去水印等操作
|
||||
> - 图片需要转为 Base64 编码后放入 `inlineData.data` 字段
|
||||
|
||||
💡 图生图使用技巧
|
||||
## 🤖 在 Claude Code 中使用
|
||||
|
||||
* 编辑指令要**具体明确** ，说清楚保留什么、修改什么
|
||||
* 支持换背景、改风格、加元素、去水印等操作
|
||||
* 图片需要转为 Base64 编码后放入 `inlineData.data` 字段
|
||||
如果你已安装 oneimage Skill，可以在 Claude Code 对话中直接使用自然语言生成图片，无需手动调用 API。
|
||||
|
||||
## 🤖 在 Claude Code 中使用
|
||||
```
|
||||
> 用 oneinai 画一张赛博朋克风格的城市夜景，16:9 比例，2K 分辨率
|
||||
|
||||
如果您已安装 [ikunimage Skill](</skills/ikunimage>)，可以在 Claude Code 对话中直接使用自然语言生成图片，无需手动调用 API。
|
||||
|
||||
|
||||
> 用 ikun 画一张赛博朋克风格的城市夜景，16:9 比例，2K 分辨率
|
||||
|
||||
> ikun 生成一张水墨风格的山水画，竖屏 9:16
|
||||
|
||||
> 用 ikun 编辑这张图片 /path/to/image.png，把背景换成海边日落
|
||||
> oneinai 生成一张水墨风格的山水画，竖屏 9:16
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
> 用 oneinai 编辑这张图片 /path/to/image.png，把背景换成海边日落
|
||||
```
|
||||
|
||||
详细安装和使用说明请参考：[ikunimage AI 生图](</skills/ikunimage>)
|
||||
详细安装和使用说明请参考 oneimage AI 生图技能文档。
|
||||
|
||||
## ⏱️ 性能建议
|
||||
## ⏱️ 性能建议
|
||||
|
||||
### 推荐超时时间
|
||||
### 推荐超时时间
|
||||
|
||||
不同分辨率的处理时间差异较大，建议设置合理的超时：
|
||||
|
||||
分辨率| 推荐超时| 适用场景
|
||||
---|---|---
|
||||
**1K**| 360 秒（6 分钟）| 快速预览、测试效果
|
||||
**2K**| 600 秒（10 分钟）| 日常使用（推荐）
|
||||
**4K**| 1200 秒（20 分钟）| 超高清输出、商业用途
|
||||
|
||||
### 带宽注意
|
||||
| 分辨率 | 推荐超时 | 适用场景 |
|
||||
| --- | --- | --- |
|
||||
| **1K** | 360 秒（6 分钟） | 快速预览、测试效果 |
|
||||
| **2K** | 600 秒（10 分钟） | 日常使用（推荐） |
|
||||
| **4K** | 1200 秒（20 分钟） | 超高清输出、商业用途 |
|
||||
|
||||
### 带宽注意
|
||||
|
||||
图片数据使用 Base64 编码传输，数据量较大：
|
||||
|
||||
* 建议使用**稳定高速的网络连接**
|
||||
* 4K 图片的 Base64 数据可能超过 **10MB**
|
||||
* 避免在网络高峰时段生成 4K 图片
|
||||
- 建议使用**稳定高速的网络连接**
|
||||
- 4K 图片的 Base64 数据可能超过 **10MB**
|
||||
- 避免在网络高峰时段生成 4K 图片
|
||||
|
||||
## ⚠️ 注意事项
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **API Key** ：需从 [OneinAI 平台](<https://api.oneinai.com>) 创建支持图像模型的令牌
|
||||
2. **API 格式** ：NanoBanana 使用**谷歌原生格式** ，不是 OpenAI 兼容格式，请注意区分
|
||||
3. **分辨率与耗时** ：分辨率越高，生成时间越长，请根据实际需求选择
|
||||
4. **文字渲染** ：支持在图片中渲染中文文字（如招牌、海报文案），在 prompt 中直接写明即可
|
||||
5. **价格差异** ：不同模型和分辨率价格不同，详见 OneinAI 平台定价页面
|
||||
1. **API Key**：需从 [oneinai 平台](https://api.oneinai.com) 创建支持图像模型的令牌
|
||||
2. **API 格式**：NanoBanana 使用**谷歌原生格式**，不是 OpenAI 兼容格式，请注意区分
|
||||
3. **分辨率与耗时**：分辨率越高，生成时间越长，请根据实际需求选择
|
||||
4. **文字渲染**：支持在图片中渲染中文文字（如招牌、海报文案），在 prompt 中直接写明即可
|
||||
5. **价格差异**：不同模型和分辨率价格不同，详见 oneinai 平台定价页面
|
||||
|
||||
@ -1,45 +1,39 @@
|
||||
# 创建专属 Key
|
||||
# 创建专属 Key
|
||||
|
||||
注册登录后，点击创建专属 Key。
|
||||
|
||||
## 创建步骤
|
||||
## 创建步骤
|
||||
|
||||
1. 登录 OneinAI 平台
|
||||
2. 访问"[令牌管理](<https://api.oneinai.com/console/token>)"
|
||||
3. 点击"添加令牌"按钮
|
||||
4. 创建需要使用的令牌，不要选择用户分组，请根据[监测站](<https://status.ikuncode.cc/>)的模型状态和令牌说明、倍率综合选择适合您的分组。
|
||||
5. 保存并复制 Key
|
||||
1. 登录 oneinai 平台
|
||||
2. 访问 [令牌管理](https://api.oneinai.com/console/token)
|
||||
3. 点击「添加令牌」按钮
|
||||
4. 创建需要使用的令牌，**不要选择用户分组**。请根据[监测站](https://status.oneinai.com/)的模型状态、令牌说明与倍率综合选择适合你的分组
|
||||
5. 保存并复制 Key
|
||||
|
||||
💡 小提示
|
||||
> 💡 **小提示**
|
||||
> **模型限制列表**留空即可，无需配置（除非你了解它的作用）。
|
||||
|
||||
**模型限制列表** 留空即可，不需要配置。除非您看懂了它的作用。
|
||||
## 安全建议
|
||||
|
||||
## 安全建议
|
||||
> 🔐 **安全提醒**
|
||||
> - **不要**将 Key 分享给他人
|
||||
> - **不要**将 Key 提交到代码仓库
|
||||
> - **不要**在公开场合展示 Key
|
||||
> - 询问配置是否正确时，请给 Key 打码
|
||||
> - 使用环境变量或配置文件存储 Key
|
||||
> - 定期更换 Key 提高安全性
|
||||
|
||||
🔐 安全提醒
|
||||
## 保存 Key
|
||||
|
||||
* **不要** 将 Key 分享给他人
|
||||
* **不要** 将 Key 提交到代码仓库
|
||||
* **不要** 在公开场合展示 Key
|
||||
* 询问配置是否正确时，给Key打码
|
||||
* 使用环境变量或配置文件存储 Key
|
||||
* 定期更换 Key 提高安全性
|
||||
创建成功后，请立即保存好你的 Key：
|
||||
|
||||
## 保存 Key
|
||||
```bash
|
||||
# 示例 Key（请替换为你的实际 Key）
|
||||
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
创建成功后，请立即保存好您的 Key：
|
||||
## 下一步
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 示例 Key（请替换为您的实际 Key）
|
||||
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
## 下一步
|
||||
|
||||
* [修改令牌设置](</guide/modify-token>) \- 调整令牌参数
|
||||
* [配置环境变量](</deploy/claude-code#配置环境变量>) \- 在工具中使用 Key
|
||||
* [充值](</guide/recharge>) \- 确保账户有足够余额
|
||||
- [修改令牌设置](/guide/modify-token) - 调整令牌参数
|
||||
- [配置环境变量](/deploy/claude-code#配置环境变量) - 在工具中使用 Key
|
||||
- [充值](/guide/recharge) - 确保账户有足够余额
|
||||
|
||||
@ -1,71 +1,71 @@
|
||||
# 修改令牌设置
|
||||
|
||||
创建 Key 后，您可以根据需要修改令牌的各项设置。
|
||||
|
||||
|
||||
|
||||
## 可修改的设置
|
||||
|
||||
### 令牌名称
|
||||
|
||||
修改令牌的显示名称，便于区分和管理。
|
||||
|
||||
### 配额限制
|
||||
|
||||
调整令牌的使用额度：
|
||||
|
||||
* 无限额度
|
||||
* 设置每日/每月限额
|
||||
* 设置总额度
|
||||
|
||||
### 速率限制
|
||||
|
||||
控制请求频率：
|
||||
|
||||
* 每分钟请求数
|
||||
* 每小时请求数
|
||||
* 并发请求数
|
||||
|
||||
### 启用/禁用
|
||||
|
||||
临时禁用令牌而不删除，方便后续再次使用。
|
||||
|
||||
## 修改步骤
|
||||
|
||||
1. 登录控制台
|
||||
2. 找到要修改的令牌
|
||||
3. 点击"编辑"按钮
|
||||
4. 修改相关设置
|
||||
5. 保存更改
|
||||
|
||||
## 重要提示
|
||||
|
||||
⚠️ 注意
|
||||
|
||||
* 修改设置后立即生效
|
||||
* 某些设置可能需要重启工具才能应用
|
||||
* 修改令牌组需要重新创建 Key
|
||||
|
||||
## 保留好 Key 备用
|
||||
|
||||
修改设置后，请确保保存好您的 Key，后续配置环境变量需要使用。
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# Windows PowerShell
|
||||
$env:ANTHROPIC_AUTH_TOKEN="您的Key"
|
||||
|
||||
# macOS/Linux
|
||||
export ANTHROPIC_AUTH_TOKEN="您的Key"
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
|
||||
## 下一步
|
||||
|
||||
* [充值](</guide/recharge>) \- 为账户充值
|
||||
* [开始部署](</deploy/claude-code>) \- 配置 AI 编程工具
|
||||
# 修改令牌设置
|
||||
|
||||
创建 Key 后，您可以根据需要修改令牌的各项设置。
|
||||
|
||||
|
||||
|
||||
## 可修改的设置
|
||||
|
||||
### 令牌名称
|
||||
|
||||
修改令牌的显示名称，便于区分和管理。
|
||||
|
||||
### 配额限制
|
||||
|
||||
调整令牌的使用额度：
|
||||
|
||||
* 无限额度
|
||||
* 设置每日/每月限额
|
||||
* 设置总额度
|
||||
|
||||
### 速率限制
|
||||
|
||||
控制请求频率：
|
||||
|
||||
* 每分钟请求数
|
||||
* 每小时请求数
|
||||
* 并发请求数
|
||||
|
||||
### 启用/禁用
|
||||
|
||||
临时禁用令牌而不删除，方便后续再次使用。
|
||||
|
||||
## 修改步骤
|
||||
|
||||
1. 登录控制台
|
||||
2. 找到要修改的令牌
|
||||
3. 点击"编辑"按钮
|
||||
4. 修改相关设置
|
||||
5. 保存更改
|
||||
|
||||
## 重要提示
|
||||
|
||||
⚠️ 注意
|
||||
|
||||
* 修改设置后立即生效
|
||||
* 某些设置可能需要重启工具才能应用
|
||||
* 修改令牌组需要重新创建 Key
|
||||
|
||||
## 保留好 Key 备用
|
||||
|
||||
修改设置后，请确保保存好您的 Key，后续配置环境变量需要使用。
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# Windows PowerShell
|
||||
$env:ANTHROPIC_AUTH_TOKEN="您的Key"
|
||||
|
||||
# macOS/Linux
|
||||
export ANTHROPIC_AUTH_TOKEN="您的Key"
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
|
||||
## 下一步
|
||||
|
||||
* [充值](</guide/recharge>) \- 为账户充值
|
||||
* [开始部署](</deploy/claude-code>) \- 配置 AI 编程工具
|
||||
|
||||
@ -88,9 +88,6 @@
|
||||
* 可能享受优惠价格
|
||||
* 支持开具发票
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有充值相关问题，请查看[售前售后](</support/after-sales>)页面获取联系方式。
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@
|
||||
* 使用邮箱注册
|
||||
* 使用第三方账号快捷注册
|
||||
|
||||
|
||||
|
||||
|
||||
## 注册方式
|
||||
|
||||
|
||||
@ -1,35 +1,35 @@
|
||||
# 友情链接
|
||||
|
||||
🤝 推荐说明
|
||||
|
||||
本站管理员推荐，与站长无利益相关。**不做任何背书，请自行判断。**
|
||||
|
||||
## Claude Code 镜像站
|
||||
|
||||
[EasyChatClaude Code 免费账号网页版镜像站，无需注册即可体验 Claude 对话→](<https://easychat.top/>)
|
||||
|
||||
### 简介
|
||||
|
||||
EasyChat 是面向 Claude 网页 Chat 使用场景推出的镜像服务，主要服务于内容创作、学习、日常办公等用户群体。自 2024 年 9 月创建 [easychat.top](<https://easychat.top/>) 站点以来持续运行至今，一直保证稳定可用。
|
||||
|
||||
系统全部自主研发，并持续更新改善，力求给用户提供最接近官网的使用体验。
|
||||
|
||||
### 使用方式
|
||||
|
||||
**1\. 选择账号**
|
||||
|
||||
打开 [EasyChat](<https://easychat.top/>) 后，页面会展示多个可用的免费共享账号卡片，点击任意一个状态为「可用」的账号即可开始对话。
|
||||
|
||||
|
||||
|
||||
**2\. 开始聊天**
|
||||
|
||||
进入后即为标准的 Claude 聊天界面，支持中文对话、多轮上下文、代码生成等全部功能。
|
||||
|
||||
|
||||
|
||||
注意
|
||||
|
||||
* 共享账号为公共资源，请合理使用，勿滥用
|
||||
* 超长对话会消耗更多使用次数，请合理规划用量
|
||||
* 如遇账号不可用，请稍后再试或选择其他账号
|
||||
# 友情链接
|
||||
|
||||
🤝 推荐说明
|
||||
|
||||
本站管理员推荐，与站长无利益相关。**不做任何背书，请自行判断。**
|
||||
|
||||
## Claude Code 镜像站
|
||||
|
||||
[EasyChatClaude Code 免费账号网页版镜像站，无需注册即可体验 Claude 对话→](<https://easychat.top/>)
|
||||
|
||||
### 简介
|
||||
|
||||
EasyChat 是面向 Claude 网页 Chat 使用场景推出的镜像服务，主要服务于内容创作、学习、日常办公等用户群体。自 2024 年 9 月创建 [easychat.top](<https://easychat.top/>) 站点以来持续运行至今，一直保证稳定可用。
|
||||
|
||||
系统全部自主研发，并持续更新改善，力求给用户提供最接近官网的使用体验。
|
||||
|
||||
### 使用方式
|
||||
|
||||
**1\. 选择账号**
|
||||
|
||||
打开 [EasyChat](<https://easychat.top/>) 后，页面会展示多个可用的免费共享账号卡片，点击任意一个状态为「可用」的账号即可开始对话。
|
||||
|
||||
|
||||
|
||||
**2\. 开始聊天**
|
||||
|
||||
进入后即为标准的 Claude 聊天界面，支持中文对话、多轮上下文、代码生成等全部功能。
|
||||
|
||||
|
||||
|
||||
注意
|
||||
|
||||
* 共享账号为公共资源，请合理使用，勿滥用
|
||||
* 超长对话会消耗更多使用次数，请合理规划用量
|
||||
* 如遇账号不可用，请稍后再试或选择其他账号
|
||||
|
||||
@ -72,4 +72,3 @@ OneinAI 作为中间层：
|
||||
|
||||
* [注册账号](</guide/registration>)开始使用
|
||||
* 查看[常见问题](</support/faq>)了解更多
|
||||
* 联系[售后支持](</support/after-sales>)获取帮助
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 欢迎使用 OneinAI！
|
||||
|
||||
OneinAI 是一家专注于给编码人员生产提效的中转站（目前主要是 Claude Code、Codex等服务），我们始终坚持"真诚 热爱"的服务理念，希望能和用户交朋友。有任何服务不周到、用得不爽的地方，请直接联系（见[售前售后](</support/after-sales>)）我们的服务人员。
|
||||
OneinAI 是一家专注于给编码人员生产提效的中转站（目前主要是 Claude Code、Codex等服务），我们始终坚持"真诚 热爱"的服务理念，希望能和用户交朋友。有任何服务不周到、用得不爽的地方，请直接联系我们的服务人员。
|
||||
|
||||
💡 提示
|
||||
|
||||
|
||||
@ -1,147 +1,147 @@
|
||||
# Linux 平台安装 Node.js
|
||||
|
||||
**三大 AI 编程工具的必备运行环境**
|
||||
|
||||
💡 重要说明
|
||||
|
||||
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
|
||||
|
||||
## Ubuntu/Debian 发行版
|
||||
|
||||
### 使用 NodeSource 仓库（推荐）
|
||||
|
||||
bash
|
||||
|
||||
|
||||
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
|
||||
## CentOS/RHEL 发行版
|
||||
|
||||
bash
|
||||
|
||||
|
||||
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
|
||||
sudo yum install -y nodejs
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
|
||||
## Fedora 发行版
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo dnf install -y nodejs npm
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
|
||||
## Arch Linux
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo pacman -S nodejs npm
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
|
||||
## 使用 nvm（推荐进阶用户）
|
||||
|
||||
nvm 允许您管理多个 Node.js 版本：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 安装 nvm
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
|
||||
# 重新加载 shell 配置
|
||||
source ~/.bashrc
|
||||
|
||||
# 安装 Node.js LTS
|
||||
nvm install --lts
|
||||
|
||||
# 设置默认版本
|
||||
nvm use --lts
|
||||
nvm alias default node
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 权限问题
|
||||
|
||||
如果遇到权限问题，可以配置 npm 使用用户目录：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
mkdir ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
|
||||
### 版本过旧
|
||||
|
||||
如果系统自带的 Node.js 版本过旧，建议使用 NodeSource 仓库或 nvm 安装最新 LTS 版本。
|
||||
|
||||
## 下一步
|
||||
|
||||
✅ 环境准备完成！
|
||||
|
||||
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
|
||||
|
||||
* [安装 Claude Code](</deploy/claude-code>)
|
||||
* [安装 CodeX](</deploy/codex>)
|
||||
* [安装 Gemini CLI](</deploy/gemini-cli>)
|
||||
# Linux 平台安装 Node.js
|
||||
|
||||
**三大 AI 编程工具的必备运行环境**
|
||||
|
||||
💡 重要说明
|
||||
|
||||
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
|
||||
|
||||
## Ubuntu/Debian 发行版
|
||||
|
||||
### 使用 NodeSource 仓库（推荐）
|
||||
|
||||
bash
|
||||
|
||||
|
||||
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
|
||||
## CentOS/RHEL 发行版
|
||||
|
||||
bash
|
||||
|
||||
|
||||
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
|
||||
sudo yum install -y nodejs
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
|
||||
## Fedora 发行版
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo dnf install -y nodejs npm
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
|
||||
## Arch Linux
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo pacman -S nodejs npm
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
|
||||
## 使用 nvm（推荐进阶用户）
|
||||
|
||||
nvm 允许您管理多个 Node.js 版本：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 安装 nvm
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
|
||||
# 重新加载 shell 配置
|
||||
source ~/.bashrc
|
||||
|
||||
# 安装 Node.js LTS
|
||||
nvm install --lts
|
||||
|
||||
# 设置默认版本
|
||||
nvm use --lts
|
||||
nvm alias default node
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 权限问题
|
||||
|
||||
如果遇到权限问题，可以配置 npm 使用用户目录：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
mkdir ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
|
||||
### 版本过旧
|
||||
|
||||
如果系统自带的 Node.js 版本过旧，建议使用 NodeSource 仓库或 nvm 安装最新 LTS 版本。
|
||||
|
||||
## 下一步
|
||||
|
||||
✅ 环境准备完成！
|
||||
|
||||
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
|
||||
|
||||
* [安装 Claude Code](</deploy/claude-code>)
|
||||
* [安装 CodeX](</deploy/codex>)
|
||||
* [安装 Gemini CLI](</deploy/gemini-cli>)
|
||||
|
||||
@ -1,87 +1,87 @@
|
||||
# macOS 平台安装 Node.js
|
||||
|
||||
**三大 AI 编程工具的必备运行环境**
|
||||
|
||||
💡 重要说明
|
||||
|
||||
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
|
||||
|
||||
## 方法一：Homebrew 包管理器（推荐）
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 安装 Homebrew（如果未安装）
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# 安装 Node.js
|
||||
brew install node
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
|
||||
## 方法二：官方安装包
|
||||
|
||||
1. 访问 Node.js 官网：<https://nodejs.org>
|
||||
2. 下载 LTS 版本的 .pkg 安装包
|
||||
3. 运行安装程序并按照提示完成安装
|
||||
|
||||
## 验证安装
|
||||
|
||||
打开终端，执行：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
如果显示版本号（如 v18.x.x 或更高），说明安装成功。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Homebrew 安装慢
|
||||
|
||||
可以使用国内镜像：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
|
||||
|
||||
1
|
||||
|
||||
### 权限问题
|
||||
|
||||
如果遇到权限问题，不要使用 `sudo`，而是修复 Homebrew 权限：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo chown -R $(whoami) /usr/local/bin /usr/local/lib
|
||||
|
||||
1
|
||||
|
||||
## 下一步
|
||||
|
||||
✅ 环境准备完成！
|
||||
|
||||
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
|
||||
|
||||
* [安装 Claude Code](</deploy/claude-code>)
|
||||
* [安装 CodeX](</deploy/codex>)
|
||||
* [安装 Gemini CLI](</deploy/gemini-cli>)
|
||||
# macOS 平台安装 Node.js
|
||||
|
||||
**三大 AI 编程工具的必备运行环境**
|
||||
|
||||
💡 重要说明
|
||||
|
||||
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
|
||||
|
||||
## 方法一：Homebrew 包管理器（推荐）
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 安装 Homebrew（如果未安装）
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# 安装 Node.js
|
||||
brew install node
|
||||
|
||||
# 验证安装
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
|
||||
## 方法二：官方安装包
|
||||
|
||||
1. 访问 Node.js 官网：<https://nodejs.org>
|
||||
2. 下载 LTS 版本的 .pkg 安装包
|
||||
3. 运行安装程序并按照提示完成安装
|
||||
|
||||
## 验证安装
|
||||
|
||||
打开终端，执行：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
如果显示版本号（如 v18.x.x 或更高），说明安装成功。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Homebrew 安装慢
|
||||
|
||||
可以使用国内镜像：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
|
||||
|
||||
1
|
||||
|
||||
### 权限问题
|
||||
|
||||
如果遇到权限问题，不要使用 `sudo`，而是修复 Homebrew 权限：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo chown -R $(whoami) /usr/local/bin /usr/local/lib
|
||||
|
||||
1
|
||||
|
||||
## 下一步
|
||||
|
||||
✅ 环境准备完成！
|
||||
|
||||
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
|
||||
|
||||
* [安装 Claude Code](</deploy/claude-code>)
|
||||
* [安装 CodeX](</deploy/codex>)
|
||||
* [安装 Gemini CLI](</deploy/gemini-cli>)
|
||||
|
||||
@ -1,88 +1,88 @@
|
||||
# Windows 平台安装 Node.js
|
||||
|
||||
**三大 AI 编程工具的必备运行环境**
|
||||
|
||||
💡 重要说明
|
||||
|
||||
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
|
||||
|
||||
## 方法一：官方安装包（推荐）
|
||||
|
||||
1. 访问 Node.js 官网：<https://nodejs.org/zh-cn/download>
|
||||
2. 下载 LTS（长期支持）版本的 Windows Installer (.msi)
|
||||
3. 运行安装包，采用默认配置完成安装
|
||||
4. 安装程序会自动配置系统 PATH 环境变量
|
||||
|
||||
|
||||
|
||||
## 方法二：包管理器安装
|
||||
|
||||
### 使用 Winget
|
||||
|
||||
Windows 11 或 Windows 10 最新版：
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
winget install OpenJS.NodeJS.LTS
|
||||
|
||||
1
|
||||
|
||||
### 使用 Chocolatey
|
||||
|
||||
需先安装 Chocolatey：
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
choco install nodejs-lts
|
||||
|
||||
1
|
||||
|
||||
### 使用 Scoop
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
scoop install nodejs-lts
|
||||
|
||||
1
|
||||
|
||||
## 验证安装
|
||||
|
||||
打开命令提示符或 PowerShell，执行：
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
如果显示版本号（如 v18.x.x 或更高），说明安装成功。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 提示"不是内部或外部命令"
|
||||
|
||||
* 重新打开终端窗口
|
||||
* 检查 PATH 环境变量是否包含 Node.js 路径
|
||||
* 重启电脑后再试
|
||||
|
||||
### 安装失败
|
||||
|
||||
* 以管理员身份运行安装程序
|
||||
* 关闭杀毒软件后重试
|
||||
* 检查系统盘空间是否充足
|
||||
|
||||
## 下一步
|
||||
|
||||
✅ 环境准备完成！
|
||||
|
||||
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
|
||||
|
||||
* [返回环境安装总览](</node/windows>)
|
||||
* [安装 Claude Code](</deploy/claude-code>)
|
||||
* [使用 CC-Switch 工具](</tools/cc-switch>)
|
||||
# Windows 平台安装 Node.js
|
||||
|
||||
**三大 AI 编程工具的必备运行环境**
|
||||
|
||||
💡 重要说明
|
||||
|
||||
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 运行环境。 如果您已安装 Node.js 18 或更高版本，可跳过本章节。 验证命令：`node -v`
|
||||
|
||||
## 方法一：官方安装包（推荐）
|
||||
|
||||
1. 访问 Node.js 官网：<https://nodejs.org/zh-cn/download>
|
||||
2. 下载 LTS（长期支持）版本的 Windows Installer (.msi)
|
||||
3. 运行安装包，采用默认配置完成安装
|
||||
4. 安装程序会自动配置系统 PATH 环境变量
|
||||
|
||||
|
||||
|
||||
## 方法二：包管理器安装
|
||||
|
||||
### 使用 Winget
|
||||
|
||||
Windows 11 或 Windows 10 最新版：
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
winget install OpenJS.NodeJS.LTS
|
||||
|
||||
1
|
||||
|
||||
### 使用 Chocolatey
|
||||
|
||||
需先安装 Chocolatey：
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
choco install nodejs-lts
|
||||
|
||||
1
|
||||
|
||||
### 使用 Scoop
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
scoop install nodejs-lts
|
||||
|
||||
1
|
||||
|
||||
## 验证安装
|
||||
|
||||
打开命令提示符或 PowerShell，执行：
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
如果显示版本号（如 v18.x.x 或更高），说明安装成功。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 提示"不是内部或外部命令"
|
||||
|
||||
* 重新打开终端窗口
|
||||
* 检查 PATH 环境变量是否包含 Node.js 路径
|
||||
* 重启电脑后再试
|
||||
|
||||
### 安装失败
|
||||
|
||||
* 以管理员身份运行安装程序
|
||||
* 关闭杀毒软件后重试
|
||||
* 检查系统盘空间是否充足
|
||||
|
||||
## 下一步
|
||||
|
||||
✅ 环境准备完成！
|
||||
|
||||
现在您可以继续安装 Claude Code、CodeX 或 Gemini CLI 了。
|
||||
|
||||
* [返回环境安装总览](</node/windows>)
|
||||
* [安装 Claude Code](</deploy/claude-code>)
|
||||
* [使用 CC-Switch 工具](</tools/cc-switch>)
|
||||
|
||||
@ -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>)。
|
||||
@ -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>)。
|
||||
@ -1,89 +0,0 @@
|
||||
# 售前售后
|
||||
|
||||
有任何不懂的，可以进群咨询，可提供人工一对一服务。
|
||||
|
||||
## 联系方式
|
||||
|
||||
### Telegram 群组
|
||||
|
||||
**推荐方式** ：加入我们的 Telegram 群组，快速获得帮助。
|
||||
|
||||
* **群组链接** ：<https://t.me/ikuncode>
|
||||
|
||||
群内可以：
|
||||
|
||||
* 咨询使用问题
|
||||
* 反馈bug和建议
|
||||
* 获取最新消息
|
||||
* 与其他用户交流
|
||||
|
||||
### QQ 群
|
||||
|
||||
* **QQ 群号** ：请扫描下方二维码加入
|
||||
|
||||
### 扫码加群
|
||||
|
||||
|
||||
|
||||
## 服务时间
|
||||
|
||||
* **工作日** ：9:00 - 00:00
|
||||
* **节假日** ：11:00 - 00:00
|
||||
|
||||
💡 提示
|
||||
|
||||
紧急问题建议在工作时间联系，响应更快。
|
||||
|
||||
## 服务内容
|
||||
|
||||
### 售前咨询
|
||||
|
||||
* 产品功能介绍
|
||||
* 价格方案说明
|
||||
* 技术可行性咨询
|
||||
* 企业方案定制
|
||||
|
||||
### 售后支持
|
||||
|
||||
* 使用问题解答
|
||||
* 技术故障排查
|
||||
* 配置指导
|
||||
* 一对一人工服务
|
||||
|
||||
### 企业服务
|
||||
|
||||
如需企业服务，请联系客服
|
||||
|
||||
## 常见问题快速通道
|
||||
|
||||
在联系客服前，建议先查看：
|
||||
|
||||
* [常见问题 FAQ](</support/faq>)
|
||||
* [部署指南](</deploy/claude-code>)
|
||||
* [配置工具](</tools/cc-switch>)
|
||||
|
||||
## 反馈建议
|
||||
|
||||
我们欢迎您的反馈和建议：
|
||||
|
||||
* 功能需求
|
||||
* 使用体验
|
||||
* 问题反馈
|
||||
* 改进建议
|
||||
|
||||
所有反馈都会认真对待，帮助我们持续改进服务。
|
||||
|
||||
## 服务承诺
|
||||
|
||||
💪 我们的承诺
|
||||
|
||||
* **真诚服务** ：坦诚沟通，不夸大宣传
|
||||
* **热爱产品** ：持续优化，追求卓越
|
||||
* **快速响应** ：及时处理问题和反馈
|
||||
* **用户至上** ：以用户体验为中心
|
||||
|
||||
* * *
|
||||
|
||||
OneinAI - 真诚 热爱
|
||||
|
||||
我们希望能和用户交朋友
|
||||
@ -1,159 +1,148 @@
|
||||
# 常见问题（FAQ）
|
||||
# 常见问题（FAQ）
|
||||
|
||||
## 账号与 Key
|
||||
## 账号与 Key
|
||||
|
||||
### 1\. 可以开发票对吧？
|
||||
### 1. 可以开发票吗？
|
||||
|
||||
对。支持普票、专票。累计充值满500元可提交开发票需求。
|
||||
可以，支持普票和专票。累计充值满 500 元可提交开票需求。
|
||||
|
||||
### 2\. Key 无效/鉴权失败怎么办？
|
||||
### 2. Key 无效 / 鉴权失败怎么办？
|
||||
|
||||
* 检查是否复制了多余空格
|
||||
* 检查 Key 是否过期/被禁用
|
||||
* 检查请求是否使用了正确的 Header/参数
|
||||
* 确认使用了对应工具的专用令牌组
|
||||
- 检查是否复制了多余空格
|
||||
- 检查 Key 是否过期或被禁用
|
||||
- 检查请求是否使用了正确的 Header / 参数
|
||||
- 确认使用了对应工具的专用令牌组
|
||||
|
||||
### 3\. 如何查看余额和消费记录？
|
||||
### 3. 如何查看余额和消费记录？
|
||||
|
||||
登录控制台即可查看：
|
||||
登录 [oneinai 控制台](https://api.oneinai.com/console/token) 即可查看：
|
||||
|
||||
* 当前余额
|
||||
* 充值记录
|
||||
* 消费明细
|
||||
* 账单详情
|
||||
- 当前余额
|
||||
- 充值记录
|
||||
- 消费明细
|
||||
- 账单详情
|
||||
|
||||
## 网站访问
|
||||
## 网站访问
|
||||
|
||||
### 网站进入为什么白屏？
|
||||
### 网站打开为什么白屏？
|
||||
|
||||
很有可能是你的广告过滤插件导致，请手动将我们的域名添加到白名单。
|
||||
很可能是浏览器的广告过滤插件导致，请手动将我们的域名添加到白名单。
|
||||
|
||||
常见的广告过滤插件：
|
||||
|
||||
* AdBlock
|
||||
* uBlock Origin
|
||||
* AdGuard
|
||||
- AdBlock
|
||||
- uBlock Origin
|
||||
- AdGuard
|
||||
|
||||
解决方法：
|
||||
|
||||
1. 打开插件设置
|
||||
2. 添加 `api.ikuncode.cc` 到白名单
|
||||
3. 刷新页面
|
||||
4. 尝试浏览器强制刷新（Windows：`Ctrl + Shift + R`，macOS：`Cmd + Shift + R`）
|
||||
1. 打开插件设置
|
||||
2. 将 `api.oneinai.com` 添加到白名单
|
||||
3. 刷新页面
|
||||
4. 必要时使用浏览器强制刷新（Windows：`Ctrl + Shift + R`，macOS：`Cmd + Shift + R`）
|
||||
|
||||
## 环境与安装
|
||||
## 环境与安装
|
||||
|
||||
### npm 安装很慢/失败？
|
||||
### npm 安装很慢 / 失败？
|
||||
|
||||
可以使用国内镜像：
|
||||
可以切换为国内镜像：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 设置淘宝镜像
|
||||
npm config set registry https://registry.npmmirror.com
|
||||
|
||||
# 验证配置
|
||||
npm config get registry
|
||||
```bash
|
||||
# 设置淘宝镜像
|
||||
npm config set registry https://registry.npmmirror.com
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
# 验证配置
|
||||
npm config get registry
|
||||
```
|
||||
|
||||
### Node.js 版本过低怎么办？
|
||||
### Node.js 版本过低怎么办？
|
||||
|
||||
Claude Code、CodeX 和 Gemini CLI 都需要 Node.js 18+ 版本。
|
||||
|
||||
升级方法：
|
||||
|
||||
* Windows: 重新下载安装最新版本
|
||||
* macOS: `brew upgrade node`
|
||||
* Linux: 使用 nvm 或 NodeSource 仓库
|
||||
- **Windows**：重新下载安装最新版本
|
||||
- **macOS**：`brew upgrade node`
|
||||
- **Linux**：使用 nvm 或 NodeSource 仓库
|
||||
|
||||
### 环境变量设置后不生效？
|
||||
### 环境变量设置后不生效？
|
||||
|
||||
* Windows: 重启终端窗口或重启电脑
|
||||
* macOS/Linux: 执行 `source ~/.bashrc` 或 `source ~/.zshrc`
|
||||
- **Windows**：重启终端窗口或重启电脑
|
||||
- **macOS / Linux**：执行 `source ~/.bashrc` 或 `source ~/.zshrc`
|
||||
|
||||
## 工具使用
|
||||
## 工具使用
|
||||
|
||||
### CC-Switch 无法启动？
|
||||
### CC-Switch 无法启动？
|
||||
|
||||
1. 检查是否有权限问题
|
||||
2. 尝试以管理员身份运行
|
||||
3. 查看是否有杀毒软件拦截
|
||||
4. 重新下载安装最新版本
|
||||
1. 检查是否有权限问题
|
||||
2. 尝试以管理员身份运行
|
||||
3. 查看是否有杀毒软件拦截
|
||||
4. 重新下载安装最新版本
|
||||
|
||||
### Claude Code 提示连接失败？
|
||||
### Claude Code 提示连接失败？
|
||||
|
||||
检查项：
|
||||
请按顺序排查：
|
||||
|
||||
* 网络连接是否正常
|
||||
* API 密钥是否正确
|
||||
* 环境变量是否设置正确
|
||||
* 余额是否充足
|
||||
- 网络连接是否正常
|
||||
- API 密钥是否正确
|
||||
- 环境变量是否设置正确
|
||||
- 余额是否充足
|
||||
|
||||
### CodeX 和 Claude Code 的令牌不通用？
|
||||
### CodeX 和 Claude Code 的令牌不通用？
|
||||
|
||||
是的，不同工具需要不同的令牌组：
|
||||
|
||||
* Claude Code: 使用 Claude Code 令牌组
|
||||
* CodeX: 使用 "codex测试" 令牌组
|
||||
* Gemini CLI: 使用 Gemini 令牌组
|
||||
- **Claude Code**：使用 Claude Code 令牌组
|
||||
- **CodeX**：使用 `codex` 令牌组
|
||||
- **Gemini CLI**：使用 Gemini 令牌组
|
||||
|
||||
请在 IkunCode 平台创建对应的专用令牌。
|
||||
请在 oneinai 平台创建对应的专用令牌。
|
||||
|
||||
## 计费相关
|
||||
## 计费相关
|
||||
|
||||
### 如何计费？
|
||||
### 如何计费？
|
||||
|
||||
* 按实际使用量计费
|
||||
* 不同模型价格不同
|
||||
* 详细计费规则请查看控制台
|
||||
- 按实际使用量计费
|
||||
- 不同模型价格不同
|
||||
- 详细计费规则请查看控制台
|
||||
|
||||
### 余额不足会怎样？
|
||||
### 余额不足会怎样？
|
||||
|
||||
* 服务会暂停
|
||||
* 请及时充值以继续使用
|
||||
* 充值后立即恢复服务
|
||||
- 服务会暂停
|
||||
- 请及时充值以继续使用
|
||||
- 充值后立即恢复服务
|
||||
|
||||
### 支持退款吗？
|
||||
### 支持退款吗？
|
||||
|
||||
* 未使用的余额可以申请退款
|
||||
* 已使用的部分不支持退款
|
||||
* 具体政策请咨询客服
|
||||
- 未使用的余额可以申请退款
|
||||
- 已使用的部分不支持退款
|
||||
- 具体政策请咨询客服
|
||||
|
||||
## 技术问题
|
||||
## 技术问题
|
||||
|
||||
### 代码会被保存吗？
|
||||
### 代码会被保存吗？
|
||||
|
||||
不会。我们不会存储您的代码内容，仅转发请求和响应。
|
||||
不会。我们不会存储你的代码内容，仅转发请求与响应。
|
||||
|
||||
### 是否支持企业使用？
|
||||
### 是否支持企业使用？
|
||||
|
||||
支持。企业用户可以：
|
||||
|
||||
* 联系客服获取企业方案
|
||||
* 支持大额充值和发票
|
||||
* 可能享受优惠价格
|
||||
- 联系客服获取企业方案
|
||||
- 支持大额充值和开票
|
||||
- 可能享受优惠价格
|
||||
|
||||
### 如何获得技术支持？
|
||||
|
||||
请查看[售前售后](</support/after-sales>)页面获取联系方式。
|
||||
## 更多问题
|
||||
|
||||
## 更多问题
|
||||
|
||||
### 遇到技术难题？
|
||||
### 遇到技术难题？
|
||||
|
||||
如果遇到启动失败、报错、超时等技术问题，请查看：
|
||||
|
||||
👉 **[疑难杂症排查指南](</support/troubleshooting>)** \- 详细的错误排查和解决方案
|
||||
👉 **[疑难杂症排查指南](/support/troubleshooting)** - 详细的错误排查与解决方案
|
||||
|
||||
### 仍未解决？
|
||||
### 仍未解决？
|
||||
|
||||
如果上述问题没有解决您的疑问，请：
|
||||
如果上述内容没有解决你的疑问，请联系我们：
|
||||
|
||||
* 加入 Telegram 群组：<https://t.me/ikuncode>
|
||||
* 查看[售前售后](</support/after-sales>)联系客服
|
||||
- 加入 Telegram 群组：<https://t.me/oneinai>
|
||||
|
||||
@ -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 初始化设置](</tools/cc-switch#第一步：初始化设置>)
|
||||
|
||||
#### 方案二：手动修改配置文件
|
||||
#### 方案二：手动修改配置文件
|
||||
|
||||
参考教程：<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.ikuncode.cc/status/api>)确认服务可用性
|
||||
**服务状态查看**：<https://status.oneinai.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
|
||||
|
||||
|
||||
npm install -g @anthropic-ai/claude-code@2.0.72
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code@2.0.72
|
||||
```
|
||||
|
||||
1
|
||||
回退到稳定的 2.0.72 版本即可恢复。
|
||||
|
||||
回退到稳定的 2.0.72 版本。
|
||||
---
|
||||
|
||||
* * *
|
||||
## 八、关闭 Claude Code 自动更新
|
||||
|
||||
## 十三、如何关闭 Claude Code 自动更新
|
||||
|
||||
### 问题描述
|
||||
### 问题描述
|
||||
|
||||
不希望 Claude Code 自动更新到新版本。
|
||||
|
||||
### 解决方案
|
||||
### 解决方案
|
||||
|
||||
在 `settings.json` 中添加以下环境变量：
|
||||
|
||||
json
|
||||
|
||||
|
||||
{
|
||||
"env": {
|
||||
"DISABLE_AUTOUPDATER": "1"
|
||||
}
|
||||
}
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"DISABLE_AUTOUPDATER": "1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
或在系统环境变量中设置：
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# macOS/Linux
|
||||
export DISABLE_AUTOUPDATER=1
|
||||
|
||||
# Windows PowerShell
|
||||
$Env:DISABLE_AUTOUPDATER = "1"
|
||||
```bash
|
||||
# macOS / Linux
|
||||
export DISABLE_AUTOUPDATER=1
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
$Env:DISABLE_AUTOUPDATER = "1"
|
||||
```
|
||||
|
||||
* * *
|
||||
---
|
||||
|
||||
## 🔧 排查技巧总结
|
||||
## 排查技巧总结
|
||||
|
||||
### 快速诊断流程
|
||||
### 快速诊断流程
|
||||
|
||||
1. ✅ 查看[服务状态页](<https://status.ikuncode.cc/status/api>)
|
||||
2. ✅ 检查环境变量配置
|
||||
3. ✅ 验证令牌是否有效
|
||||
4. ✅ 检查网络和代理状态
|
||||
5. ✅ 查看 Token 余额
|
||||
6. ✅ 尝试重新开启会话
|
||||
1. 查看 [oneinai 服务状态页](<https://status.oneinai.cc/status/api>)
|
||||
2. 检查环境变量配置
|
||||
3. 验证令牌是否有效
|
||||
4. 检查网络和代理状态
|
||||
5. 查看 Token 余额
|
||||
6. 尝试重新开启会话
|
||||
|
||||
### 常用调试命令
|
||||
### 常用调试命令
|
||||
|
||||
#### Claude Code
|
||||
#### Claude Code
|
||||
|
||||
bash
|
||||
|
||||
|
||||
/status # 查看当前会话状态
|
||||
/context # 查看上下文 Token 使用
|
||||
/clear # 清空当前会话
|
||||
```bash
|
||||
/status # 查看当前会话状态
|
||||
/context # 查看上下文 Token 使用
|
||||
/clear # 清空当前会话
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
### 环境变量检查
|
||||
|
||||
### 环境变量检查
|
||||
#### Windows
|
||||
|
||||
#### Windows
|
||||
```powershell
|
||||
# 查看所有 ANTHROPIC 相关变量
|
||||
Get-ChildItem Env: | Where-Object { $_.Name -like "*ANTHROPIC*" }
|
||||
```
|
||||
|
||||
powershell
|
||||
|
||||
|
||||
# 查看所有 ANTHROPIC 相关变量
|
||||
Get-ChildItem Env: | Where-Object {$_.Name -like "*ANTHROPIC*"}
|
||||
#### macOS / Linux
|
||||
|
||||
1
|
||||
2
|
||||
```bash
|
||||
# 查看所有 ANTHROPIC 相关变量
|
||||
env | grep ANTHROPIC
|
||||
```
|
||||
|
||||
#### macOS/Linux
|
||||
---
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 查看所有 ANTHROPIC 相关变量
|
||||
env | grep ANTHROPIC
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
* * *
|
||||
|
||||
## 📮 获取帮助
|
||||
## 获取帮助
|
||||
|
||||
如果以上方法都无法解决您的问题，请：
|
||||
|
||||
* 📧 查看[售前售后](</support/after-sales>)联系客服
|
||||
* 💬 加入 Telegram 群组：<https://t.me/ikuncode>
|
||||
* 📖 查看[常见问题 FAQ](</support/faq>)
|
||||
- 加入 Telegram 群组：<https://t.me/oneinai>
|
||||
- 查看 [常见问题 FAQ](</support/faq>)
|
||||
|
||||
* * *
|
||||
---
|
||||
|
||||
_本文档持续更新中，如有新的疑难杂症欢迎反馈..._
|
||||
_本文档持续更新中，如有新的疑难杂症欢迎反馈。_
|
||||
|
||||
@ -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>)
|
||||
CC-Switch 文档站| [ccswitch.lovable.app](<https://ccswitch.lovable.app/>)
|
||||
|
||||
## 🎯 工具介绍
|
||||
| 资源 | 地址 |
|
||||
| --- | --- |
|
||||
| GitHub 发布页 | [cc-switch/releases](https://github.com/farion1231/cc-switch/releases) |
|
||||
| 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://`）
|
||||
> - 环境变量冲突检测
|
||||
|
||||
|
||||
|
||||
|
||||
## 📦 安装方法
|
||||
## 📦 安装方法
|
||||
|
||||
### 🖥️ Windows 平台
|
||||
### 🖥️ Windows 平台
|
||||
|
||||
#### 方法一：MSI 安装器（推荐）
|
||||
**方法一：MSI 安装器（推荐）**
|
||||
|
||||
1. 访问项目发布页：<https://github.com/farion1231/cc-switch/releases>
|
||||
2. 下载最新版本的 `.msi` 安装器
|
||||
3. 运行安装器，按照向导完成安装
|
||||
4. 安装完成后从开始菜单启动 CC-Switch
|
||||
1. 访问 [Releases 页面](https://github.com/farion1231/cc-switch/releases)
|
||||
2. 下载最新版本的 `.msi` 安装器
|
||||
3. 运行安装器，按向导完成安装
|
||||
4. 从开始菜单启动 CC-Switch
|
||||
|
||||
#### 方法二：便携版（无需安装）
|
||||
**方法二：便携版（免安装）**
|
||||
|
||||
1. 下载 `.zip` 便携版压缩包
|
||||
2. 解压到任意目录
|
||||
3. 运行 `cc-switch.exe` 即可使用
|
||||
1. 下载 `.zip` 便携版压缩包
|
||||
2. 解压到任意目录
|
||||
3. 双击 `cc-switch.exe` 即可使用
|
||||
|
||||
### 🍏 macOS 平台
|
||||
### 🍏 macOS 平台
|
||||
|
||||
#### 推荐方式：Homebrew 安装
|
||||
**推荐方式：Homebrew 安装**
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 添加 tap 源
|
||||
brew tap farion1231/ccswitch
|
||||
|
||||
# 安装 cc-switch
|
||||
brew install --cask cc-switch
|
||||
```bash
|
||||
# 添加 tap 源
|
||||
brew tap farion1231/ccswitch
|
||||
|
||||
1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
# 安装 cc-switch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
#### 手动安装
|
||||
**手动安装**
|
||||
|
||||
1. 访问 [Releases 页面](<https://github.com/farion1231/cc-switch/releases>)
|
||||
2. 下载 `.dmg` 安装包
|
||||
3. 打开 DMG 文件，将 CC-Switch 拖入应用程序文件夹
|
||||
4. 从启动台或应用程序文件夹启动
|
||||
1. 访问 [Releases 页面](https://github.com/farion1231/cc-switch/releases)
|
||||
2. 下载 `.dmg` 安装包
|
||||
3. 打开 DMG，将 CC-Switch 拖入「应用程序」文件夹
|
||||
4. 从启动台或「应用程序」启动
|
||||
|
||||
### 🐧 Linux 平台
|
||||
### 🐧 Linux 平台
|
||||
|
||||
#### Debian/Ubuntu 系列（推荐）
|
||||
**Debian / Ubuntu 系列（推荐）**
|
||||
|
||||
bash
|
||||
|
||||
|
||||
sudo dpkg -i cc-switch_*.deb
|
||||
sudo apt-get install -f # 修复依赖
|
||||
```bash
|
||||
sudo dpkg -i cc-switch_*.deb
|
||||
sudo apt-get install -f # 修复依赖
|
||||
```
|
||||
|
||||
1
|
||||
2
|
||||
**AppImage 通用版本**
|
||||
|
||||
#### AppImage 通用版本
|
||||
```bash
|
||||
chmod +x cc-switch_*.AppImage
|
||||
./cc-switch_*.AppImage
|
||||
```
|
||||
|
||||
bash
|
||||
|
||||
|
||||
chmod +x cc-switch_*.AppImage
|
||||
./cc-switch_*.AppImage
|
||||
**Arch Linux（AUR）**
|
||||
|
||||
1
|
||||
2
|
||||
```bash
|
||||
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
|
||||
2
|
||||
3
|
||||
打开 CC-Switch，进入「设置 → 通用」，将「窗口行为」中的所有开关全部启用，确保自启动、Claude Code 插件集成、托盘最小化等功能正常生效。
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
|
||||
### 第一步：初始化设置
|
||||
> 💡 **推荐配置**
|
||||
> 建议启用以下选项以获得最佳体验：
|
||||
> - 开机自启
|
||||
> - 静默启动
|
||||
> - 应用到 Claude Code 插件
|
||||
> - 跳过初次安装确认
|
||||
> - 关闭时最小化到托盘
|
||||
|
||||
打开 CC-Switch，进入「设置」页面，在「通用」标签下将「窗口行为」中的所有开关全部打开，确保自启动、Claude Code 插件集成、托盘最小化等功能正常生效。
|
||||
### 第二步：添加供应商配置
|
||||
|
||||
|
||||
**1. 添加 Claude / Gemini 供应商**
|
||||
|
||||
💡 推荐配置
|
||||
点击右上角的「+」按钮，进入添加面板。
|
||||
|
||||
建议将「窗口行为」中的所有开关全部启用，以获得最佳使用体验：开机自启、静默启动、应用到 Claude Code 插件、跳过初次安装确认、关闭时最小化到托盘。
|
||||
|
||||
|
||||
### 第二步：添加提供商配置
|
||||
> 💡 **Gemini 用户提示**
|
||||
> 使用 Gemini CLI 时，请在 oneinai 平台创建 **Gemini 分组**的令牌，而非 Claude 分组。
|
||||
|
||||
1. 点击右上角的加号按钮来添加提供商(Claude/Gemini)
|
||||
**2. 添加 Codex 供应商**
|
||||
|
||||
|
||||
切换到 Codex 标签后，同样点击右上角「+」按钮添加。
|
||||
|
||||
💡 Gemini 用户
|
||||
|
||||
|
||||
如果使用的是 Gemini CLI，请在平台创建**对应的** 令牌，而非 Claude 分组。
|
||||
**3. 保存配置**
|
||||
|
||||
2. 点击右上角的加号按钮来添加提供商(Codex)
|
||||
填写完成后点击「保存」即可。
|
||||
|
||||
|
||||
> ⚠️ **重要提示**
|
||||
> 不同 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. 在提供商列表中选择要使用的配置
|
||||
2. 点击「启用」按钮
|
||||
3. **或** 使用系统托盘图标进行即时切换
|
||||
切换完成后，启动对应的 AI 工具即可享受新配置。
|
||||
|
||||
**系统托盘快速切换：**
|
||||
## 📖 进阶使用
|
||||
|
||||
* 右键点击系统托盘中的 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 编程工具的配置，享受高效的开发体验。
|
||||
|
||||
@ -1,62 +1,62 @@
|
||||
# Claude Code Hub (CCH)
|
||||
|
||||
**团队级多供应商 AI Coding 代理调度平台**
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
资源| 地址
|
||||
---|---
|
||||
官网| [claude-code-hub.app](<https://claude-code-hub.app/>)
|
||||
官方文档| [claude-code-hub.app/docs](<https://claude-code-hub.app/docs>)
|
||||
GitHub| [ding113/claude-code-hub](<https://github.com/ding113/claude-code-hub>)
|
||||
|
||||
## 🎯 工具介绍
|
||||
|
||||
Claude Code Hub (CCH) 是一个服务器部署的多租户 AI Coding 工具调度平台，帮助团队统一管理 Claude、Codex、Gemini 等多家 AI 服务商，实现智能负载均衡与自动故障转移。
|
||||
|
||||
💡 适用场景
|
||||
|
||||
* **敏捷开发团队** ：多人共用 AI 工具，需要统一管理和用量追踪
|
||||
* **AI 驱动开发团队** ：重度依赖 AI Coding，需要高可用和自动故障转移
|
||||
* **创业公司** ：预算有限，需要精细的成本控制和多维限流
|
||||
* **中小软件公司** ：需要合规审计、访问控制和完整日志
|
||||
|
||||
## ✨ 核心功能
|
||||
|
||||
* **智能负载均衡** ：权重 + 优先级 + 分组调度，内置熔断保护与最多 3 次自动故障转移
|
||||
* **多供应商管理** ：同时接入 Claude、Codex、Gemini、OpenAI Compatible 等多种供应商
|
||||
* **限流与并发控制** ：支持 RPM（每分钟请求数）、金额限制（5小时/周/月）、并发 Session 控制
|
||||
* **实时监控与统计** ：仪表盘展示调用量、成本、活跃 Session 和供应商健康状态
|
||||
* **Session 管理** ：5 分钟上下文缓存，同一会话自动路由到相同供应商，提高缓存命中率
|
||||
* **OpenAI 兼容层** ：支持 `/v1/chat/completions` 端点，无缝对接现有工具链
|
||||
|
||||
## 🛠️ 快速部署
|
||||
|
||||
### 一键脚本部署
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 使用官方部署脚本，5 分钟完成安装
|
||||
curl -fsSL https://claude-code-hub.app/install.sh | bash
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
详细部署文档请参考：[脚本部署指南](<https://claude-code-hub.app/docs/deployment/script>)
|
||||
|
||||
### 客户端接入
|
||||
|
||||
部署完成后，将 Claude Code、Codex 等工具的 API 地址指向 CCH 代理即可使用。
|
||||
|
||||
详细接入文档请参考：[客户端接入指南](<https://claude-code-hub.app/docs/deployment/client-setup>)
|
||||
|
||||
## 常见问题
|
||||
|
||||
### CCH和CCS有什么区别？
|
||||
|
||||
CCH更适合团队内部使用，而CCS更适合个人用户。
|
||||
|
||||
### CCH 和直接使用 API 有什么区别？
|
||||
|
||||
CCH 提供了供应商故障自动切换、负载均衡、用量统计、Session 粘性等团队级功能，单人使用直接配 API 即可，多人协作推荐使用 CCH。
|
||||
# Claude Code Hub (CCH)
|
||||
|
||||
**团队级多供应商 AI Coding 代理调度平台**
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
资源| 地址
|
||||
---|---
|
||||
官网| [claude-code-hub.app](<https://claude-code-hub.app/>)
|
||||
官方文档| [claude-code-hub.app/docs](<https://claude-code-hub.app/docs>)
|
||||
GitHub| [ding113/claude-code-hub](<https://github.com/ding113/claude-code-hub>)
|
||||
|
||||
## 🎯 工具介绍
|
||||
|
||||
Claude Code Hub (CCH) 是一个服务器部署的多租户 AI Coding 工具调度平台，帮助团队统一管理 Claude、Codex、Gemini 等多家 AI 服务商，实现智能负载均衡与自动故障转移。
|
||||
|
||||
💡 适用场景
|
||||
|
||||
* **敏捷开发团队** ：多人共用 AI 工具，需要统一管理和用量追踪
|
||||
* **AI 驱动开发团队** ：重度依赖 AI Coding，需要高可用和自动故障转移
|
||||
* **创业公司** ：预算有限，需要精细的成本控制和多维限流
|
||||
* **中小软件公司** ：需要合规审计、访问控制和完整日志
|
||||
|
||||
## ✨ 核心功能
|
||||
|
||||
* **智能负载均衡** ：权重 + 优先级 + 分组调度，内置熔断保护与最多 3 次自动故障转移
|
||||
* **多供应商管理** ：同时接入 Claude、Codex、Gemini、OpenAI Compatible 等多种供应商
|
||||
* **限流与并发控制** ：支持 RPM（每分钟请求数）、金额限制（5小时/周/月）、并发 Session 控制
|
||||
* **实时监控与统计** ：仪表盘展示调用量、成本、活跃 Session 和供应商健康状态
|
||||
* **Session 管理** ：5 分钟上下文缓存，同一会话自动路由到相同供应商，提高缓存命中率
|
||||
* **OpenAI 兼容层** ：支持 `/v1/chat/completions` 端点，无缝对接现有工具链
|
||||
|
||||
## 🛠️ 快速部署
|
||||
|
||||
### 一键脚本部署
|
||||
|
||||
bash
|
||||
|
||||
|
||||
# 使用官方部署脚本，5 分钟完成安装
|
||||
curl -fsSL https://claude-code-hub.app/install.sh | bash
|
||||
|
||||
1
|
||||
2
|
||||
|
||||
详细部署文档请参考：[脚本部署指南](<https://claude-code-hub.app/docs/deployment/script>)
|
||||
|
||||
### 客户端接入
|
||||
|
||||
部署完成后，将 Claude Code、Codex 等工具的 API 地址指向 CCH 代理即可使用。
|
||||
|
||||
详细接入文档请参考：[客户端接入指南](<https://claude-code-hub.app/docs/deployment/client-setup>)
|
||||
|
||||
## 常见问题
|
||||
|
||||
### CCH和CCS有什么区别？
|
||||
|
||||
CCH更适合团队内部使用，而CCS更适合个人用户。
|
||||
|
||||
### CCH 和直接使用 API 有什么区别？
|
||||
|
||||
CCH 提供了供应商故障自动切换、负载均衡、用量统计、Session 粘性等团队级功能，单人使用直接配 API 即可，多人协作推荐使用 CCH。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user