zyc123/Aiapi-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

111

Browse Source
This commit is contained in:
zyc123 2026-05-14 13:40:25 +08:00
parent 5f293ab440
commit 22aa869a75
3 changed files with 595 additions and 442 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
apps/hapi-advanced.md
View File

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

91
apps/opencode.md
View File

@ -2,25 +2,24 @@
**开源 AI 编程助手，终端中的智能编码伙伴**
## 📋 简介
📋 简介
OpenCode 是一款开源的 AI 编程助手，可在终端、IDE 或桌面环境中辅助编写、调试和改进代码。支持原生终端 TUI 界面、多会话并行、75+ 模型提供商接入，是命令行开发者的理想工具。
## 🔗 相关链接
| 资源 | 地址 |
| --- | --- |
| OpenCode 项目 | <https://github.com/opencode-ai/opencode> |
| oneinai 控制台 | <https://api.oneinai.com/console/token> |
资源| 地址
---|---
OpenCode 项目| <https://github.com/opencode-ai/opencode>
## ✨ 功能特点
- ✅ **原生终端 TUI**：专为命令行开发者设计，高效流畅
- ✅ **智能 LSP 加载**：自动加载正确的语言服务器，提升上下文理解
- ✅ **多会话并行**：支持多个会话同时运行，互不干扰
- ✅ **会话链接共享**：可分享会话链接给他人协作
- ✅ **75+ 模型支持**：支持多种模型提供商，包括本地模型
- ✅ **多平台支持**：终端 CLI、桌面应用（Beta）、IDE 扩展
* ✅ **原生终端 TUI** ：专为命令行开发者设计，高效流畅
* ✅ **智能 LSP 加载** ：自动加载正确的语言服务器，提升上下文理解
* ✅ **多会话并行** ：支持多个会话同时运行，互不干扰
* ✅ **会话链接共享** ：可分享会话链接给他人协作
* ✅ **75+ 模型支持** ：支持多种模型提供商，包括本地模型
* ✅ **多平台支持** ：终端 CLI、桌面应用（Beta）、IDE 扩展
## 🛠️ 安装与配置
@ -28,46 +27,52 @@ OpenCode 是一款开源的 AI 编程助手，可在终端、IDE 或桌面环境
打开终端，运行以下命令全局安装 OpenCode：
```bash
bash
npm install -g opencode-ai
```
1
安装完成后，在终端输入 `opencode` 命令，若出现 TUI 界面则安装成功。
![安装成功界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode02.png)
![安装成功界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode01.png)
### 第二步：安装 CC-Switch
查看 [CC-Switch 配置工具](/tools/cc-switch) 文档，下载并安装 CC-Switch 到本地。
查看 [CC-Switch 配置工具](</tools/cc-switch>) 文档，下载并安装 CC-Switch 到本地。
### 第三步：添加 oneinai 供应商
### 第三步：添加 IkunCode 供应商
**1. 选择配置项**
**1\. 选择配置项**
打开 CC-Switch，上方配置项选择 `OpenCode`，然后点击 **添加供应商** 按钮。
![添加供应商界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode01.png)
![添加供应商界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode02.png)
**2. 填写供应商信息**
**2\. 填写供应商信息**
按以下说明配置各项参数：
| 配置项 | 说明 |
| --- | --- |
| **预设供应商** | 选择 `oneinai` |
| **供应商标识** | 自定义名称，如 `oneinai-Claude` |
| **接口格式** | Claude 模型选 `Anthropic`；GPT 模型选 `OpenAI`；Gemini 模型选 `Google (Gemini)` |
| **API Key** | 填入你在 [oneinai 控制台](https://api.oneinai.com/console/token) 创建的 Key |
| **额外选项** | 填写 `{"setCacheKey":true}` |
配置项| 说明
---|---
**预设供应商**| 选择 `IkunCode`
**供应商标识**| 自定义名称，如 `IkunCode-Claude`
**接口格式**| Claude 模型选 `Anthropic`；GPT 模型选 `OpenAI`；Gemini 模型选 `Google (Gemini)`
**API Key**| 填入你在 [IkunCode 控制台](<https://api.oneinai.com/console/token>) 创建的 Key
**额外选项**| 填写 `{"setCacheKey":true}`
> 💡 **支持的分组**
> 根据你需要的模型类型，选择对应分组的 API Key：
>
> - **Claude 系列**：只允许逆向分组
> - **GPT 系列**：Codex 分组
> - **Gemini 系列**：Gemini 分组
>
> 请在[创建专属 Key](/guide/create-key) 时选择对应分组。
💡 支持的分组
根据你需要的模型类型，选择正确分组的 API Key：
![只允许逆向分组]('+t+')
* **Claude 系列** ：只允许逆向分组
* **GPT 系列** ：Codex 分组
* **Gemini 系列** ：Gemini 分组
请在 [创建专属 Key](</guide/create-key>) 时选择对应分组。
## ✅ 验证配置
@ -75,24 +80,24 @@ npm install -g opencode-ai
2. 输入 `/models` 命令，检查配置的渠道是否出现在模型列表中
3. 如果能看到你添加的模型，说明配置成功
![模型列表验证](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode06.png)
![模型列表验证](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode03.png)
开始愉快地编码吧 🎉
开始愉快地编码吧！🎉
![使用中的对话界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode07.png)
![使用中的对话界面](https://minio.oneinai.com/oneinai/images/docs/opencode/opencode04.png)
## ❓ 常见问题
## 常见问题
### 安装时提示 npm 未找到？
请先安装 Node.js 环境，参考 [Node.js 环境安装](/node/windows) 文档。
请先安装 Node.js 环境，参考 [Node.js 环境安装](</node/windows>) 文档。
### 模型列表中看不到配置的渠道？
- 确认 CC-Switch 中已正确保存配置
- 重启终端后再次运行 `opencode`
- 检查 API Key 是否填写正确
* 确认 CC-Switch 中已正确保存配置
* 重启终端后再次运行 `opencode`
* 检查 API Key 是否填写正确
### 更多问题
请查看 [FAQ](/support/faq) 或联系[售后支持](/support/after-sales)。
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。

328
deploy/codex.md
View File

@ -2,36 +2,40 @@
**企业级 AI 编码助手 - 完整部署手册**
| 资源 | 地址 |
| --- | --- |
| 官方文档 | [developers.openai.com/codex](https://developers.openai.com/codex/) |
| oneinai 控制台 | <https://api.oneinai.com/console/token> |
资源| 地址
---|---
官方文档| [developers.openai.com/codex](<https://developers.openai.com/codex/>)
> 📋 **前置要求**
> 请先完成 [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 集成 ➜ 开发环境就绪
## 🚀 使用 CC-Switch 快速配置（推荐）
> ⚠️ **前置条件**
> 使用 CC-Switch 配置 CodeX 之前，请确保已通过 npm 全局安装 CodeX 工具：
>
> ```bash
> npm install -g @openai/codex@latest
> ```
>
> 验证安装：`codex --version`
⚠️ 前置条件
推荐使用 [CC-Switch 快速配置工具](/tools/cc-switch) 进行图形化配置，简单快捷无需命令行操作。
使用 CC-Switch 配置 CodeX 之前，请确保已通过 npm 全局安装 CodeX 工具：
bash
npm install -g @openai/codex@latest
1
验证安装：`codex --version`
推荐使用 [CC-Switch 快速配置工具](</tools/cc-switch>) 进行图形化配置，简单快捷无需命令行操作。
### 配置步骤
**1. 启动 CC-Switch 并切换到 Codex 标签**
**1\. 启动 CC-Switch 并切换到 Codex 标签**
1. 打开 CC-Switch 应用程序
2. 点击顶部的「Codex」标签页
@ -39,51 +43,49 @@ CodeX 是基于 GPT-5 架构的智能编程助手，为开发者提供卓越的
![CC-Switch Codex 标签页](https://minio.oneinai.com/oneinai/images/docs/codex/codex01.png)
**2. 填写 CodeX 提供商配置**
**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. **提供商名称** ：自定义名称（如「IkunCoding」）
2. **Base URL** ：输入 `https://api.oneinai.com/v1`
3. **API Key** ：粘贴您从 IkunCode 平台获取的 CodeX 专用令牌（codex令牌组）
4. **Model** ：选择 `gpt-5.4`（书写文档时最新模型为 5.4）
5. **其他配置** ：根据需求调整推理强度、网络访问等参数
6. 点击「保存」按钮
填写完成后点击「保存」按钮。
![CC-Switch 添加 CodeX 配置](https://minio.oneinai.com/oneinai/images/docs/codex/codex02.png)![CC-Switch CodeX 配置详情](https://minio.oneinai.com/oneinai/images/docs/codex/codex03.png)
![CC-Switch 添加 CodeX 配置](https://minio.oneinai.com/oneinai/images/docs/codex/codex02.png)
![CC-Switch CodeX 配置详情](https://minio.oneinai.com/oneinai/images/docs/codex/codex03.png)
💡 提示
> 💡 **提示**
> - CC-Switch 会自动创建 `~/.codex/config.toml` 和 `auth.json` 文件
> - 可以添加多个提供商配置，随时切换
> - 切换配置后，关闭并重启 CodeX 即可生效
* CC-Switch 会自动创建 `~/.codex/config.toml` 和 `auth.json` 文件
* 可以添加多个提供商配置，随时切换
* 切换配置后，关闭并重启 CodeX 即可生效
**3. 启用配置并使用**
**3\. 启用配置并使用**
1. 在配置列表中找到刚创建的「oneinai」配置
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 平台
@ -91,35 +93,46 @@ CC-Switch 支持通过系统托盘快速切换 CodeX 配置：
以管理员权限启动命令提示符或 PowerShell，执行：
```powershell
powershell
npm install -g @openai/codex@latest
codex --version
```
#### 第二步：集成 oneinai API 服务
1
2
#### 第二步：集成 IkunCoding API 服务
**获取专属 API 凭证** ：
1. 访问 [oneinai 控制台](https://api.oneinai.com/console/token)
2. 完成账户注册或登录
3. 进入「API 密钥管理」模块
4. 创建新密钥时务必选择「codex」令牌组
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
```
powershell
**编写配置文件 `config.toml`**：
```toml
model_provider = "oneinai"
mkdir %USERPROFILE%\\.codex
cd %USERPROFILE%\\.codex
1
2
**编写配置文件：config.toml**
toml
model_provider = "IkunCoding"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
@ -127,52 +140,85 @@ approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
[model_providers.oneinai]
name = "oneinai"
[model_providers.IkunCoding]
name = "ikun"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
```
**编写认证文件 `auth.json`**：
1
2
3
4
5
6
7
8
9
10
11
12
13
**编写认证文件：auth.json**
json
```json
{
"OPENAI_API_KEY": "此处粘贴你的 CodeX 专用令牌"
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
}
```
1
2
3
#### 第三步：初始化工作空间
```powershell
powershell
mkdir my-codex-project
cd my-codex-project
codex
```
1
2
3
### 🍏 macOS 平台
#### 部署 CodeX 工具
```bash
bash
npm install -g @openai/codex@latest
codex --version
```
1
2
#### 集成 API 服务
**构建配置目录** ：
```bash
bash
mkdir -p ~/.codex
cd ~/.codex
```
**编写 `config.toml` 配置**：
1
2
**编写 config.toml 配置** ：
bash
```bash
cat > config.toml << 'EOF'
model_provider = "oneinai"
model_provider = "IkunCoding"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
@ -180,55 +226,92 @@ approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
[model_providers.oneinai]
name = "oneinai"
[model_providers.IkunCoding]
name = "ikun"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF
```
**编写 `auth.json` 认证配置**：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
**编写 auth.json 认证配置** ：
bash
```bash
cat > auth.json << 'EOF'
{
"OPENAI_API_KEY": "此处粘贴你的 CodeX 专用令牌"
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
}
EOF
```
1
2
3
4
5
#### 初始化工作空间
```bash
bash
mkdir my-codex-project
cd my-codex-project
codex
```
1
2
3
### 🐧 Linux 平台
#### 部署 CodeX 工具
```bash
bash
sudo npm install -g @openai/codex@latest
codex --version
```
1
2
#### 集成 API 服务
**构建配置目录** ：
```bash
bash
mkdir -p ~/.codex
cd ~/.codex
```
**编写 `config.toml` 配置**：
1
2
**编写 config.toml 配置** ：
bash
```bash
cat > config.toml << 'EOF'
model_provider = "oneinai"
model_provider = "IkunCoding"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
@ -236,48 +319,75 @@ approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true
[model_providers.oneinai]
name = "oneinai"
[model_providers.IkunCoding]
name = "ikun"
base_url = "https://api.oneinai.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF
```
**编写 `auth.json` 认证配置**：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
**编写 auth.json 认证配置** ：
bash
```bash
cat > auth.json << 'EOF'
{
"OPENAI_API_KEY": "此处粘贴你的 CodeX 专用令牌"
"OPENAI_API_KEY": "此处粘贴您的 CodeX 专用令牌"
}
EOF
```
1
2
3
4
5
#### 初始化工作空间
```bash
bash
mkdir my-codex-project
cd my-codex-project
codex
```
## ❓ 常见问题
1
2
3
## 常见问题
### CodeX 和 Claude Code 的令牌不通用？
是的，两者使用不同的令牌组：
- Claude Code：使用 Claude Code 令牌组
- CodeX：使用 `codex` 令牌组
* Claude Code: 使用 Claude Code 令牌组
* CodeX: 使用 "codex" 令牌组
请在 oneinai 平台创建对应的专用令牌。
请在 IkunCode 平台创建对应的专用令牌。
### 配置文件放在哪里？
- Windows：`%USERPROFILE%\.codex\`
- macOS / Linux：`~/.codex/`
* Windows: `%USERPROFILE%\\.codex\\`
* macOS/Linux: `~/.codex/`
### 更多问题
请查看 [FAQ](/support/faq) 或联系[售后支持](/support/after-sales)。
请查看 [FAQ](</support/faq>) 或联系[售后支持](</support/after-sales>)。