Skip to content

Commit d16eca3

Browse files
zhengkunwang223zhengkunwang223
committed
feat: 增加 AI 编程接入指南
1 parent f464409 commit d16eca3

3 files changed

Lines changed: 265 additions & 0 deletions

File tree

‎docs/faq/ai_coding.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
## 1 AI 编程工具如何接入 1Panel AI 网关？
2+
3+
![AI 编程接入 1Panel AI 网关示意图](../img/ai/ai_coding_gateway.svg)
4+
5+
!!! note ""
6+
大多数 AI 编程工具只要支持 OpenAI 兼容接口，就可以接入 1Panel AI 网关。接入时主要填写三个参数：
7+
8+
- **Base URL**：填写 AI 网关的外部访问地址，通常格式为 `http://<服务器 IP>:<端口>/v1`
9+
- **API Key**：填写 AI 网关中创建的 API Key
10+
- **Model**：填写 AI 网关模型映射中的请求模型名称，例如 `qwen3-coder`
11+
12+
`Model` 不一定是上游模型的真实名称。客户端请求的模型名称需要先在 **AI -> AI 网关 -> 模型池** 中完成映射，再由网关转发到实际模型。
13+
14+
推荐先使用以下命令确认 AI 网关可以正常访问：
15+
16+
```bash
17+
curl http://<服务器 IP>:4000/v1/chat/completions \
18+
-H "Authorization: Bearer <API Key>" \
19+
-H "Content-Type: application/json" \
20+
-d '{
21+
"model": "qwen3-coder",
22+
"messages": [
23+
{
24+
"role": "user",
25+
"content": "Hello"
26+
}
27+
],
28+
"stream": true
29+
}'
30+
```
31+
32+
## 2 OpenCode 如何接入 AI 网关？
33+
34+
!!! note ""
35+
OpenCode 支持在配置文件中自定义 Provider，并可以通过 `baseURL` 指向自定义 OpenAI 兼容接口。
36+
37+
在用户级配置 `~/.config/opencode/opencode.json` 或项目根目录的 `opencode.json` 中添加如下配置：
38+
39+
```json
40+
{
41+
"$schema": "https://opencode.ai/config.json",
42+
"provider": {
43+
"onepanel-ai-gateway": {
44+
"npm": "@ai-sdk/openai-compatible",
45+
"name": "1Panel AI Gateway",
46+
"options": {
47+
"baseURL": "http://<服务器 IP>:4000/v1"
48+
},
49+
"models": {
50+
"qwen3-coder": {
51+
"name": "qwen3-coder"
52+
}
53+
}
54+
}
55+
},
56+
"model": "onepanel-ai-gateway/qwen3-coder"
57+
}
58+
```
59+
60+
启动 `opencode` 后，通过 `/connect` 配置该 Provider 的 API Key，然后通过 `/models` 选择模型。
61+
62+
如果当前 OpenCode 版本未在 `/connect` 中展示自定义 Provider，可以改用 OpenCode 已支持的 OpenAI 兼容 Provider，并将其 `baseURL` 覆盖为 AI 网关的外部访问地址。
63+
64+
## 3 Qwen Code 如何接入 AI 网关？
65+
66+
!!! note ""
67+
Qwen Code 支持 OpenAI 兼容协议，可以在 `~/.qwen/settings.json` 中通过 `modelProviders.openai` 配置自定义服务地址。
68+
69+
示例配置如下：
70+
71+
```json
72+
{
73+
"modelProviders": {
74+
"openai": [
75+
{
76+
"id": "qwen3-coder",
77+
"name": "1Panel AI Gateway - qwen3-coder",
78+
"baseUrl": "http://<服务器 IP>:4000/v1",
79+
"envKey": "ONEPANEL_AI_GATEWAY_API_KEY"
80+
}
81+
]
82+
},
83+
"security": {
84+
"auth": {
85+
"selectedType": "openai"
86+
}
87+
},
88+
"model": {
89+
"name": "qwen3-coder"
90+
}
91+
}
92+
```
93+
94+
建议将 API Key 写入 `~/.qwen/.env`，不要直接提交到项目代码中：
95+
96+
```bash
97+
ONEPANEL_AI_GATEWAY_API_KEY=sk-xxxx
98+
```
99+
100+
启动 `qwen` 后，可以通过 `/model` 切换到 AI 网关中的模型。
101+
102+
## 4 Codex 如何接入 AI 网关？
103+
104+
!!! note ""
105+
Codex 支持通过 `config.toml` 配置模型供应商。接入 AI 网关时，建议将配置写入用户级配置文件 `~/.codex/config.toml`，不要写入项目级 `.codex/config.toml`。
106+
107+
如果希望通过独立 Provider 接入 AI 网关，可以使用如下配置：
108+
109+
```toml
110+
model = "qwen3-coder"
111+
model_provider = "onepanel-ai-gateway"
112+
113+
[model_providers.onepanel-ai-gateway]
114+
name = "1Panel AI Gateway"
115+
base_url = "http://<服务器 IP>:4000/v1"
116+
env_key = "ONEPANEL_AI_GATEWAY_API_KEY"
117+
```
118+
119+
然后在终端中设置 AI 网关 API Key：
120+
121+
```bash
122+
export ONEPANEL_AI_GATEWAY_API_KEY="sk-xxxx"
123+
```
124+
125+
启动 Codex CLI 后，Codex 会将请求发送到 AI 网关。`model` 需要填写 AI 网关模型映射中的请求模型名称，例如 `qwen3-coder`。
126+
127+
如果只是想让 Codex 内置 OpenAI Provider 走代理或网关，也可以在 `~/.codex/config.toml` 中设置：
128+
129+
```toml
130+
model = "qwen3-coder"
131+
openai_base_url = "http://<服务器 IP>:4000/v1"
132+
```
133+
134+
这种方式仍使用 OpenAI Provider 的认证方式；如果 AI 网关使用独立 API Key，优先使用上面的自定义 Provider 配置。
135+
136+
## 5 其他 AI 编程工具如何接入？
137+
138+
!!! note ""
139+
Cursor、Continue、Cline、Aider 等工具如果支持 OpenAI 兼容接口，一般也可以按以下方式配置：
140+
141+
- 将 **OpenAI Base URL** 或 **API Base** 设置为 AI 网关外部访问地址，例如 `http://<服务器 IP>:4000/v1`
142+
- 将 **API Key** 设置为 AI 网关中创建的 API Key
143+
- 将 **Model** 设置为 AI 网关模型映射中的请求模型名称
144+
145+
如果工具支持环境变量，也可以按工具要求设置：
146+
147+
```bash
148+
export OPENAI_API_KEY="sk-xxxx"
149+
export OPENAI_BASE_URL="http://<服务器 IP>:4000/v1"
150+
export OPENAI_MODEL="qwen3-coder"
151+
```
152+
153+
不同工具读取的环境变量名称可能不同。如果环境变量不生效，请以该工具设置页面中的 Base URL、API Key、Model 字段为准。
154+
155+
## 6 常见问题如何排查？
156+
157+
!!! note ""
158+
**返回 401 或 API Key 无效**
159+
160+
检查 AI 网关 API Key 是否填写正确，API Key 绑定的用户组是否启用，请求头是否为 `Authorization: Bearer <API Key>`。
161+
162+
**返回 model not found**
163+
164+
检查客户端填写的模型名称是否等于 AI 网关模型映射中的请求模型名称，而不是上游供应商的真实模型名称。
165+
166+
**连接失败或返回 404**
167+
168+
检查 Base URL 是否包含 `/v1`，AI 网关服务是否已启动，监听端口、防火墙和外部访问地址是否配置正确。
169+
170+
**工具调用或代码编辑失败**
171+
172+
优先选择支持 tool calling / function calling 的编程模型，例如 Qwen Coder、DeepSeek Coder 等。部分工具对工具调用格式要求较严格，需要更换模型或调整工具侧 Provider 类型。
173+
174+
**流式输出中断或请求超时**
175+
176+
检查 AI 网关设置中的最大并发、队列等待超时、非流式请求超时和流式空闲超时，并结合 AI 网关日志、用量统计排查上游模型响应情况。
177+
178+
## 7 参考链接
179+
180+
!!! note ""
181+
- [OpenCode Providers](https://opencode.ai/docs/providers/)
182+
- [OpenCode Config](https://opencode.ai/docs/config/)
183+
- [Qwen Code Authentication](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/)
184+
- [Codex Configuration](https://developers.openai.com/codex/config-basic)
185+
- [Codex Advanced Configuration](https://developers.openai.com/codex/config-advanced)

‎docs/img/ai/ai_coding_gateway.svg‎

Lines changed: 79 additions & 0 deletions
Loading

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,7 @@ nav:
170170
- 系统功能相关: faq/system_function.md
171171
- 服务器架构相关: faq/server_architecture.md
172172
- OpenClaw 相关: faq/openclaw.md
173+
- AI 编程接入指南: faq/ai_coding.md
173174
- API 接口: dev_manual/api_manual.md
174175
- Skills 技能: dev_manual/skills.md
175176
- 版本迭代: changelog.md

0 commit comments

Comments
 (0)