# 🌐 OmniRoute Proxy Guide (Yorùbá)

🌐 **Languages:** 🇺🇸 [English](../../../../ops/PROXY_GUIDE.md) · 🇪🇹 [am](../../../am/docs/ops/PROXY_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/PROXY_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/PROXY_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/PROXY_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/PROXY_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/ops/PROXY_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/PROXY_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/PROXY_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/PROXY_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/PROXY_GUIDE.md) · 🇪🇸 [es](../../../es/docs/ops/PROXY_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/PROXY_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/PROXY_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/PROXY_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/PROXY_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/PROXY_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/PROXY_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/PROXY_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/PROXY_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/PROXY_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/PROXY_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/PROXY_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/PROXY_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/PROXY_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/PROXY_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/PROXY_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/PROXY_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/PROXY_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/PROXY_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/PROXY_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/PROXY_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/PROXY_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/PROXY_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/PROXY_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/PROXY_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/PROXY_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/PROXY_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/PROXY_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/PROXY_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/PROXY_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/PROXY_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/PROXY_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/PROXY_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/PROXY_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/PROXY_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/PROXY_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/PROXY_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/PROXY_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/PROXY_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/PROXY_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/PROXY_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/PROXY_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/PROXY_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/PROXY_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/PROXY_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/PROXY_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/PROXY_GUIDE.md)

---

> **Forí àwọn ìdènà àgbègbè kọjá, dáàbò bo ìdánimọ̀ rẹ, kí o sì darí ìṣàn AI gba proxy èyíkéyìí — láìsí ìṣòro ìṣètò kankan.**

OmniRoute ní ètò ìṣàkóso proxy tó péye, èyí tó ń jẹ́ kí o darí ìṣàn sí àwọn olupèsè AI òkè gba àwọn proxy HTTP, HTTPS, tàbí SOCKS5. Yálà o wà ní agbègbè tí a ti dí mọ́, o nílò yíyí IP padà, tàbí o fẹ́ ìfipamọ́ fingerprint — ìtọ́sọ́nà yìí ṣàlàyé gbogbo rẹ̀.

---

## Àkójọ Àwọn Àkóónú

- [Kí Nìdí Tí A Fi Lo Àwọn Proxy?](#why-use-proxies)
- [Àkópọ̀ Ìṣètò Ẹ̀rọ](#architecture-overview)
- [Ètò Proxy Ìpele Mẹ́rin](#4-level-proxy-system)
- [Ìforúkọsílẹ̀ Proxy (CRUD)](#proxy-registry-crud)
- [Ọjà Ọ̀fẹ́ 1proxy](#1proxy-free-proxy-marketplace)
- [Yíyí Proxy Padà](#proxy-rotation)
- [Ìdènà Ìṣàwárí & Ìfipamọ́](#anti-detection--stealth)
- [Àwọn Ìpo Proxy Òkè](#upstream-proxy-modes)
- [UI Pátákó Ìdarí](#dashboard-ui)
- [Ìtọ́kasí API](#api-reference)
- [Àwọn Àyípadà Àyíká](#environment-variables)
- [Yíyanjú Ìṣòro](#troubleshooting)

---

## Kí Nìdí Tí A Fi Lo Àwọn Proxy?

Ọ̀pọ̀ àwọn olupèsè AI ló ń fi ààlà sí ìwọlé gẹ́gẹ́ bí agbègbè ilẹ̀ ayé. Àwọn olùgbéejáde ní **Rọ́ṣíà, Ṣáínà, Íránì, Kúbà, Tọ́kì**, àti àwọn orílẹ̀-èdè mìíràn máa ń pàdé àwọn àṣìṣe bíi:

```
unsupported_country_region_territory
```

Kódà níta àwọn agbègbè tí a ti dí mọ́, àwọn proxy wúlò fún:

| Ìlò                          | Àpèjúwe                                                                     |
| ---------------------------- | --------------------------------------------------------------------------- |
| **Fíforí ààlà àgbègbè kọjá** | Wọlé sí OpenAI, Anthropic, Codex, Copilot láti àwọn orílẹ̀-èdè tí a ti dí mọ́ |
| **Yíyí IP padà**             | Pín àwọn ìbéèrè káàkiri ọ̀pọ̀ IP láti yẹra fún fífi ààlà sí iye ìbéèrè        |
| **Àṣírí**                    | Fi IP gidi rẹ pamọ́ fún àwọn olupèsè òkè                                     |
| **Ìbámu pẹ̀lú òfin**          | Darí ìṣàn gba àwọn agbègbè àṣẹ òfin pàtó                                    |
| **Ìdánwò**                   | Ṣe àfarawé àwọn ìbéèrè láti àwọn agbègbè ọ̀tọ̀ọ̀tọ̀                             |

---

## Àkópọ̀ Ìṣètò Ẹ̀rọ

```
┌───────────────────────────────────────────────────────────────┐
│                       Sẹ́fà OmniRoute                          │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ Ìforúkọsílẹ̀ │    │ Olùpín       │    │ Proxy            │  │
│  │ Proxy       │───▶│ Proxy        │───▶│ Fetch (undici)   │  │
│  │ (SQLite)    │    │ (cached)     │    │                  │  │
│  └─────────────┘    └──────────────┘    └────────┬─────────┘  │
│         ▲                                        │            │
│         │                                        ▼            │
│  ┌──────┴──────┐                        ┌──────────────────┐  │
│  │ Ìbámu 1proxy│                        │ API Olùpèsè      │  │
│  │ (adágún ọ̀fẹ́)│                        │ Òkè              │  │
│  └─────────────┘                        └──────────────────┘  │
└───────────────────────────────────────────────────────────────┘
```

### Àwọn Ẹ̀ka Pàtàkì

| Ẹ̀ka                   | Fáìlì                                        | Ipa                                                           |
| --------------------- | -------------------------------------------- | ------------------------------------------------------------- |
| **Ìforúkọsílẹ̀ Proxy** | `src/lib/db/proxies.ts`                      | CRUD fún àwọn àkọsílẹ̀ proxy + àwọn ìsọ̀rí ààlà lílò            |
| **Olùpín Proxy**      | `open-sse/utils/proxyDispatcher.ts`          | Ṣẹ̀dá àwọn olùpín `undici` ProxyAgent/SOCKS pẹ̀lú ìfipamọ́ cache |
| **Proxy Fetch**       | `open-sse/utils/proxyFetch.ts`               | Fi ìfisí olùpín proxy yí `fetch()` ká                         |
| **Ọ̀nà Ìṣètò**         | `src/app/api/settings/proxy/route.ts`        | API ìṣètò proxy àtijọ́ (GET/PUT/DELETE)                        |
| **Ọ̀nà Ìṣàkóso**       | `src/app/api/v1/management/proxies/route.ts` | API CRUD ìforúkọsílẹ̀ (GET/POST/PATCH/DELETE)                  |
| **DB 1proxy**         | `src/lib/db/oneproxy.ts`                     | Ìtọ́jú àìpéye fún ọjà proxy ọ̀fẹ́                                |

---

## Ètò Proxy Onípele Mẹ́rin

OmniRoute ṣe àtìlẹ́yìn fún ìṣètò proxy ní **àwọn ìpele òmìnira mẹ́rin**, tí a ń yanjú ní ìbámu pẹ̀lú bí ààyò wọn ṣe tẹ̀ lé ara wọn:

```
Ìtòlẹ́sẹẹsẹ Ìyanjú Ààyò (tí ó ga jù → tí ó kéré jù):

  1. 🔵 Proxy Àkọọ́lẹ̀/Àsopọ̀  →  fún kọ́kọ́rọ́ API / àsopọ̀ OAuth kọ̀ọ̀kan
  2. 🟡 Proxy Olùpèsè         →  fún olùpèsè kọ̀ọ̀kan (fún àpẹẹrẹ, gbogbo ìrìnàjò OpenAI)
  3. 🟠 Proxy Combo           →  fún ìṣètò combo/ìdarí-ọ̀nà kọ̀ọ̀kan
  4. 🟢 Proxy Àgbáyé          →  gbogbo ìrìnàjò, gbogbo àwọn olùpèsè
```

### Bí Ìyanjú Ṣe Ń Ṣiṣẹ́

Nígbà tí OmniRoute bá fi ìbéèrè ránṣẹ́ sí olùpèsè upstream kan, ó máa ń pe `resolveProxyForConnectionFromRegistry()`, èyí tí yóò yẹ ipele kọ̀ọ̀kan wò ní ìtòlẹ́sẹẹsẹ:

1. **Ipele àkọọ́lẹ̀** — Ṣé proxy kan wà tí a yàn sí ID àsopọ̀ pàtó yìí?
2. **Ipele olùpèsè** — Ṣé proxy kan wà tí a yàn sí olùpèsè yìí (fún àpẹẹrẹ, `openai`)?
3. **Ipele àgbáyé** — Ṣé proxy àgbáyé kan wà tí a ti ṣètò?
4. **Kò sí proxy** — Àsopọ̀ tààrà sí olùpèsè náà.

Èyí tí ó kọ́kọ́ bá mu ni a ó lò. Èyí túmọ̀ sí pé o lè ṣètò proxy àgbáyé gẹ́gẹ́ bí ìrànlọ́wọ́ ìkẹyìn, ṣùgbọ́n kí o kọ̀ ọ́ sílẹ̀ fún àwọn olùpèsè tàbí àsopọ̀ pàtó.

### Ohun Tí A Ń Darí Nípasẹ̀ Proxy

| Irú Ìrìnàjò          | Nípasẹ̀ Proxy? | Àwọn Àkíyèsí                                 |
| -------------------- | ------------- | -------------------------------------------- |
| Àwọn ìparí ìfọ̀rọ̀wérọ̀ | ✅            | Gbogbo àwọn ìbéèrè `/v1/chat/completions`    |
| Àwọn embeddings      | ✅            | `/v1/embeddings`                             |
| Ṣíṣẹ̀dá àwòrán        | ✅            | `/v1/images/generations`                     |
| Ohùn (TTS/STT)       | ✅            | `/v1/audio/*`                                |
| Pàṣípààrọ̀ àmì OAuth  | ✅            | Yanjú `unsupported_country_region_territory` |
| Àwọn ìdánwò àsopọ̀    | ✅            | Bọ́tìnì "Dán Àsopọ̀ Wò" ń lo proxy             |
| Ìsọdọ̀tun àmì         | ✅            | Ìsọdọ̀tun OAuth ní abẹ́lẹ̀                      |
| Ìmúdọ́gba awoṣe       | ✅            | Àkójọ àti ìṣàwárí àwọn awoṣe                 |

---

## Ìforúkọsílẹ̀ Proxy (CRUD)

Ìforúkọsílẹ̀ proxy jẹ́ tábìlì SQLite (`proxy_registry`) tí ó ń tọ́jú gbogbo àwọn proxy rẹ. Proxy kọ̀ọ̀kan ní:

| Ààyè       | Irú     | Àpèjúwe                                        |
| ---------- | ------- | ---------------------------------------------- |
| `id`       | UUID    | Olùdámọ̀ aláìlẹ́gbẹ́                              |
| `name`     | String  | Àkọlé tí ènìyàn lè kà                          |
| `type`     | String  | Prótókólì: `http`, `https`, `socks5`           |
| `host`     | String  | Orúkọ host tàbí IP proxy                       |
| `port`     | Integer | Nọ́ńbà port                                     |
| `username` | String  | Orúkọ onílò fún ìfàṣẹsí (ti paroko níbi ìpamọ́) |
| `password` | String  | Ọ̀rọ̀ aṣínà fún ìfàṣẹsí (ti paroko níbi ìpamọ́)   |
| `region`   | String  | Àkọlé agbègbè ilẹ̀-ayé                          |
| `notes`    | String  | Àwọn àkíyèsí ọ̀rọ̀ òmìnira                       |
| `status`   | String  | `active` tàbí `inactive`                       |
| `source`   | String  | `manual` tàbí `oneproxy`                       |

### Ṣíṣẹ̀dá Proxy Kan

**Nípasẹ̀ Dashboard:**

1. Lọ sí **Settings → Proxy**
2. Tẹ **Add Proxy**
3. Kún irú, host, port, àti àwọn ẹ̀rí ìfàṣẹsí àṣàyàn
4. Fi pamọ́

**Nípasẹ̀ API:**

```bash
curl -X POST http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Proxy",
    "type": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "user",
    "password": "pass",
    "region": "US"
  }'
```

### Ṣíṣe Ìmúdójúìwọ̀n Proxy Kan

```bash
curl -X PATCH http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "id": "proxy-uuid-here",
    "host": "new-proxy.example.com",
    "port": 9090
  }'
```

> **Àkíyèsí:** A ó pa àwọn ẹ̀rí ìfàṣẹsí mọ́ àyàfi tí o bá fi àwọn arọ́pò tí kò ṣófo ránṣẹ́ ní kedere. Fífi àwọn string òfo ránṣẹ́ fún `username`/`password` yóò jẹ́ kí àwọn iye tí a ti tọ́jú dúró.

### Pípa Proxy Kan Rẹ́

```bash
# Yóò kùnà bí a bá ti yan proxy náà sí ìpele èyíkéyìí
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"

# Fipá parẹ́ (yóò tún yọ àwọn ìyàn kúrò)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"
```

### Ṣíṣe Àkójọ Àwọn Proxy

```bash
curl "http://localhost:20128/api/v1/management/proxies?limit=50&offset=0"
```

### Yíyan Àwọn Proxy Sí Àwọn Ìpele

```bash
# Yàn án sí ipele àgbáyé
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "global", "proxy": {"type":"http","host":"proxy.example.com","port":8080}}'

# Yàn án sí olùpèsè pàtó kan
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "provider", "id": "openai", "proxy": {"type":"socks5","host":"socks.example.com","port":1080}}'

# Yàn án sí àsopọ̀/kọ́kọ́rọ́ pàtó kan
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "key", "id": "connection-uuid", "proxy": {"type":"http","host":"key-proxy.com","port":3128}}'
```

### Yíyan Proxy Tí Ó Fẹsẹ̀ Múlẹ̀

Ṣàyẹ̀wò proxy tí a ó lò fún àsopọ̀ kan:

```bash
curl "http://localhost:20128/api/settings/proxy?resolve=connection-uuid"
```

Ó máa dá proxy tí a yanjú padà pẹ̀lú ipele rẹ̀ (`account`, `provider`, tàbí `global`) àti orísun rẹ̀.

### Ìyàn Ní Ọ̀pọ̀lọpọ̀

Yan proxy kan sí ọ̀pọ̀ olùpèsè tàbí àsopọ̀ lẹ́ẹ̀kan náà:

```bash
curl -X POST http://localhost:20128/api/v1/management/proxies/bulk-assign \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "provider",
    "scopeIds": ["openai", "anthropic", "codex"],
    "proxyId": "proxy-uuid"
  }'
```

### Gbígbé Wọlé/Gbígbé Jáde

Àwọn proxy wà nínú ètò **Backup/Restore**. Nígbà tí o bá gbé ìṣètò OmniRoute rẹ jáde:

1. Lọ sí **Dashboard → Settings → Backup**
2. Tẹ **Export** — ìforúkọsílẹ̀ proxy àti àwọn ìyàn rẹ̀ wà nínú rẹ̀
3. Láti mú un padà, tẹ **Import**, kí o sì gbe fáìlì àfẹ́yinti náà sókè

Ìforúkọsílẹ̀ proxy tún ṣe àtìlẹ́yìn fún **upsert nípasẹ̀ host+port** — bí o bá gbé proxy kan wọlé tí ó ti wà tẹ́lẹ̀ (host àti port kan náà), yóò ṣe ìmúdójúìwọ̀n rẹ̀ dípò ṣíṣẹ̀dá àdákọ míì.

### Ìṣíkiri Láti Ètò Àtijọ́

Tí o bá ti ṣètò àwọn aṣojú nínú ẹ̀yà àtijọ́ kan (ṣáájú registry), OmniRoute yóò ṣí wọn lọ láìfọwọ́sí:

```
Ibi ìpamọ́ key_value àtijọ́ → proxy_registry + proxy_assignments
```

Èyí máa ṣẹlẹ̀ lẹ́ẹ̀kan ṣoṣo ní ìgbà ìbẹ̀rẹ̀ àkọ́kọ́ lẹ́yìn ìgbéga. Lo `migrateLegacyProxyConfigToRegistry({ force: true })` láti tún un ṣe.

---

## Ọjà Aṣojú Ọ̀fẹ́ 1proxy

> 🆕 **Ìfikún láti ọwọ́ [@oyi77](https://github.com/oyi77)** — PR [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847) (Ọ̀ràn [#1788](https://github.com/diegosouzapw/OmniRoute/issues/1788))

OmniRoute ṣepọ̀ mọ́ pèpéle àwùjọ **[1proxy](https://1proxy-api.aitradepulse.com)** láti pèsè ààyè sí **ọ̀pọ̀ ọgọ́rùn-ún àwọn aṣojú ọ̀fẹ́ tí a ti fọwọ́sí** láti gbogbo àgbáyé. Èyí dára gan-an fún àwọn aṣàmúlò tí kò ní ohun amáyédẹrùn aṣojú tiwọn.

### Bí Ó Ṣe Ń Ṣiṣẹ́

```
┌─────────────┐    Múdọ́gba   ┌─────────────────┐    Yípadà    ┌──────────┐
│  1proxy API │ ────────────▶ │  proxy_registry  │ ────────────▶ │ Olùpèsè  │
│  (òde)      │ tó 500 péré   │  source=oneproxy │ nípa dídára  │   API    │
└─────────────┘    aṣojú      └─────────────────┘               └──────────┘
```

1. **Múdọ́gba** — OmniRoute máa ń gba àwọn aṣojú tí a ti fọwọ́sí láti 1proxy API
2. **Tọ́jú** — A máa ń fi àwọn aṣojú pamọ́ sínú tábìlì `proxy_registry` kan náà pẹ̀lú `source = 'oneproxy'`
3. **Ṣàsẹ̀** — Ṣàsẹ̀ nípa ìlànà ìbánisọ̀rọ̀, orílẹ̀-èdè, àti àmì dídára
4. **Yípadà** — Yan aṣojú tó dára jù lọ nípa lílo dídára, àṣàyàn láìlétòlétò, tàbí àwọn ọgbọ́n títẹ̀lé ara wọn
5. **Dín dídára kù láìfọwọ́ṣe** — A máa ń dín àmì dídára àwọn aṣojú tí ó kùnà kù; nígbà tó bá wà lábẹ́ ààlà → a máa samisi rẹ̀ gẹ́gẹ́ bí aláìṣiṣẹ́

### Mímú Àwọn Aṣojú Dọ́gba

**Nípasẹ̀ Dasibodu:**

1. Lọ sí táàbù **Settings → 1proxy**
2. Tẹ **"Sync Now"**
3. Wo àwọn ìṣirò: àpapọ̀ àwọn aṣojú, iye àwọn tó ń ṣiṣẹ́, àárín àmì dídára, àti ìpín gẹ́gẹ́ bí orílẹ̀-èdè

**Nípasẹ̀ API:**

```bash
# Bẹ̀rẹ̀ ìmúdọ́gba
curl -X POST http://localhost:20128/api/settings/oneproxy \
  -H "Content-Type: application/json" \
  -d '{}'

# Ìdáhùn:
# { "success": true, "added": 127, "updated": 45, "failed": 2, "total": 172 }
```

### Ṣíṣe Àṣàyàn Àwọn Aṣojú

```bash
# Ṣàsẹ̀ nípa ìlànà ìbánisọ̀rọ̀
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"

# Ṣàsẹ̀ nípa orílẹ̀-èdè
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"

# Ṣàsẹ̀ nípa àmì dídára tó kéré jù lọ
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"

# Darapọ̀ àwọn àsẹ̀
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"
```

### Àwọn Àmì Dídára Aṣojú

Aṣojú 1proxy kọ̀ọ̀kan ní metadata:

| Pápá            | Àpèjúwe                                  |
| --------------- | ---------------------------------------- |
| `qualityScore`  | Ìwọ̀n 0-100 láti inú ìfọwọ́sí 1proxy       |
| `latencyMs`     | Ìdádúró nẹ́tíwọ́ọ̀kì tí a wọ̀n               |
| `anonymity`     | `transparent`, `anonymous`, tàbí `elite` |
| `googleAccess`  | Bóyá aṣojú náà lè wọ àwọn iṣẹ́ Google     |
| `countryCode`   | Kóòdù orílẹ̀-èdè ISO onílẹ́tà méjì         |
| `lastValidated` | Àmì àkókò ìfọwọ́sí tó ṣẹ̀ṣẹ̀ jù lọ          |

A máa ń ṣàtúnṣe àwọn àmì dídára lọ́nà alágbára:

- **Àwọn ìbéèrè tó kùnà** máa ń dín àmì náà kù ní àmì 10
- **Àmì bá lọ sí ≤10** → a máa samisi aṣojú náà gẹ́gẹ́ bí `inactive`
- A kì í fi àwọn aṣojú aláìṣiṣẹ́ sínú ìyípadà

### Àwọn Ọgbọ́n Ìyípadà

```bash
# Yípadà nípa dídára (aṣojú tó dára jù lọ ni yóò kọ́kọ́ wá) — àkọ́ṣe
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -H "Content-Type: application/json" \
  -d '{"strategy": "quality"}'

# Ìyípadà láìlétòlétò
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "random"}'

# Títẹ̀lé ara wọn (èyí tí a kò tíì fọwọ́sí láìpẹ́ jù lọ ni yóò kọ́kọ́ wá)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "sequential"}'
```

### Olùdásí Ìyíká

Ìmúdọ́gba 1proxy ní olùdásí ìyíká tí a kọ́ sínú rẹ̀:

- Lẹ́yìn **ìkùnà ìmúdọ́gba márùn-ún léraléra**, a máa dí àwọn ìgbìyànjú ìmúdọ́gba míì
- Tún un ṣe pẹ̀lú: `resetOneproxyCircuitBreaker()` tàbí tún olupin náà bẹ̀rẹ̀
- Ipò ìmúdọ́gba wà ní `GET /api/settings/oneproxy?action=status`

### Pípa Àwọn Aṣojú 1proxy Rẹ́

```bash
# Pa aṣojú 1proxy kan ṣoṣo rẹ́
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"

# Pa GBOGBO àwọn aṣojú 1proxy rẹ́ (àwọn aṣojú àfọwọ́ṣe kò ní yípadà)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"
```

---

## Ìdènà Ìṣàwárí & Ìfarapamọ́

OmniRoute kì í kàn darí ìrìnàjò nẹ́tíwọ́ọ̀kì gba aṣojú kọjá — ó tún ń mú kí ìrìnàjò náà dà bí èyí tó bófin mu:

### Ṣíṣe Àfarawé Ìtẹ̀wọ́-ọwọ́ TLS

Ó ń lo `wreq-js` láti ṣe ìtẹ̀wọ́-ọwọ́ TLS tó dà bí ti aṣàwákiri, èyí tó ń forí kọ àwọn ètò ìṣàwárí bot tó máa ń ṣàmì sí àwọn ìbáṣepọ̀ TLS tí kì í ṣe ti aṣàwákiri.

### Ìbámu Ìtẹ̀wọ́-ọwọ́ CLI

**Bọ́tìnì Ìtẹ̀wọ́-ọwọ́ CLI** (`Settings → Security`) máa ń tún ètò àwọn àkọlé HTTP àti àwọn pápá ara JSON ṣe kí wọ́n lè bá ìtẹ̀wọ́-ọwọ́ gangan ti àwọn fáìlì aláṣiṣẹ́ CLI àbínibí mu (Claude Code, Codex, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ). Èyí ń ṣiṣẹ́ **lórí àfikún sí** aṣojú náà:

```
IP rẹ (tí a dí) → IP Aṣojú (US) → API Olùpèsè
                  + àfarawé TLS
                  + ìtẹ̀wọ́-ọwọ́ CLI
```

O máa rí **ìbojúbo IP** àti **ìjẹ́rìísí ojúlówó ìbéèrè** ní àkókò kan náà.

### Ìtọ́jú IP Aṣojú

Àwọn báàjì aláwọ̀ orí pátákó ìdarí máa ń fi ipele aṣojú tó ń ṣiṣẹ́ hàn:

| Báàjì | Ipele   | Ìtumọ̀                                     |
| ----- | ------- | ----------------------------------------- |
| 🟢    | Àgbáyé  | Gbogbo ìrìnàjò ń gba inú aṣojú yìí kọjá   |
| 🟡    | Olùpèsè | Ìrìnàjò olùpèsè yìí nìkan ni a ń ṣojú fún |
| 🔵    | Ìsopọ̀   | Kọ́kọ́rọ́/àkọọ́lẹ̀ pàtó yìí ń lo aṣojú yìí     |

Báàjì náà tún máa ń fi IP aṣojú tí a ti yanjú hàn fún ìjẹ́rìísí.

---

## Àwọn Ìpo Aṣojú Òkè

Fún àwọn olùpèsè tó ń lo àpẹẹrẹ CLIProxyAPI, OmniRoute ń ṣe àtìlẹ́yìn fún àwọn ìpo aṣojú òkè mẹ́ta:

| Ìpo           | Àpèjúwe                                                       |
| ------------- | ------------------------------------------------------------- |
| `native`      | OmniRoute ń bójú tó ìdarí aṣojú tààrà (àìyípadà)              |
| `cliproxyapi` | Ó ń fi iṣẹ́ lé ẹ̀dà CLIProxyAPI ìta lọ́wọ́                        |
| `fallback`    | Ó kọ́kọ́ gbìyànjú native, ó sì padà sí CLIProxyAPI bí ó bá kùnà |

Ṣètò rẹ̀ fún olùpèsè kọ̀ọ̀kan:

```bash
curl -X PUT "http://localhost:20128/api/upstream-proxy/openai" \
  -H "Content-Type: application/json" \
  -d '{"mode": "native", "enabled": true}'
```

---

## Ìrísí Pátákó Ìdarí

### Settings → Proxy Tab

- Ìṣètò **aṣojú àgbáyé** (ṣètò lẹ́ẹ̀kan fún gbogbo ìrìnàjò)
- Àwọn ìṣètò **aṣojú fún olùpèsè kọ̀ọ̀kan** tó borí ti àgbáyé
- Àwọn ìyàn **aṣojú fún ìsopọ̀ kọ̀ọ̀kan**
- **Ìdánwò ìsopọ̀** nípasẹ̀ aṣojú tí a ṣètò
- **Àwọn báàjì aláwọ̀** tó ń fi ipele aṣojú tó ń ṣiṣẹ́ hàn

### Settings → 1proxy Tab

- Bọ́tìnì **Ṣàmúdójúìwọ̀n Nísinsìnyí** láti gba àwọn aṣojú ọ̀fẹ́
- **Àwọn káàdì ìṣirò**: Àpapọ̀, Tó ń ṣiṣẹ́, Àárín Gbùngbùn Didára, Ìmúdójúìwọ̀n Tó Kẹ́yìn
- **Àwọn àlẹ̀mọ́**: Ìlànà, Kóòdù Orílẹ̀-èdè, Didára Kéré Jù
- **Tábìlì aṣojú** pẹ̀lú olùgbàlejò, ìlànà, orílẹ̀-èdè, àmì didára, ìdádúró, àìdánimọ̀, àti àyè sí Google
- Pánẹ́ẹ̀lì **ipò ìmúdójúìwọ̀n** pẹ̀lú títọpa àṣeyọrí/ìkùnà àti iye ìkùnà tẹ̀léra
- **Pa Gbogbo Rẹ́** láti yọ gbogbo àkọsílẹ̀ 1proxy kúrò

---

## Ìtọ́kasí API

### API Ìṣètò Aṣojú

| Ọ̀nà      | Ojú-ọ̀nà                                        | Àpèjúwe                    |
| -------- | ---------------------------------------------- | -------------------------- |
| `GET`    | `/api/settings/proxy`                          | Gba àkójọpọ̀ ìṣètò aṣojú    |
| `GET`    | `/api/settings/proxy?level=global`             | Gba aṣojú àgbáyé           |
| `GET`    | `/api/settings/proxy?level=provider&id=openai` | Gba aṣojú olùpèsè          |
| `GET`    | `/api/settings/proxy?resolve=connectionId`     | Yanjú aṣojú tó ń ṣiṣẹ́      |
| `PUT`    | `/api/settings/proxy`                          | Ṣe àfikún ìṣètò aṣojú      |
| `DELETE` | `/api/settings/proxy?level=provider&id=openai` | Yọ aṣojú kúrò ní ipele náà |

### API Ìforúkọsílẹ̀ Aṣojú

| Ọ̀nà      | Ojú-ọ̀nà                                           | Àpèjúwe                  |
| -------- | ------------------------------------------------- | ------------------------ |
| `GET`    | `/api/v1/management/proxies`                      | Ṣàkójọ gbogbo àwọn aṣojú |
| `GET`    | `/api/v1/management/proxies?id=uuid`              | Gba aṣojú nípasẹ̀ ID      |
| `GET`    | `/api/v1/management/proxies?id=uuid&where_used=1` | Gba àwọn ìyàn aṣojú      |
| `POST`   | `/api/v1/management/proxies`                      | Ṣẹ̀dá aṣojú               |
| `PATCH`  | `/api/v1/management/proxies`                      | Ṣe àfikún aṣojú          |
| `DELETE` | `/api/v1/management/proxies?id=uuid`              | Pa aṣojú rẹ́              |
| `DELETE` | `/api/v1/management/proxies?id=uuid&force=1`      | Fipá pa á rẹ́             |
| `POST`   | `/api/v1/management/proxies/bulk-assign`          | Yan ọ̀pọ̀lọpọ̀ lẹ́ẹ̀kan       |
| `GET`    | `/api/v1/management/proxies/assignments`          | Ṣàkójọ àwọn ìyàn         |
| `GET`    | `/api/v1/management/proxies/health`               | Ìṣirò ìlera aṣojú        |

### API Tunnels

Fún ṣíṣí ẹ̀dà OmniRoute rẹ sí íńtánẹ́ẹ̀tì gbogbogbò (Cloudflare/ngrok/Tailscale) dípò dídarí ìrìnàjò jáde nípasẹ̀ aṣojú, wo [TUNNELS_GUIDE.md](./TUNNELS_GUIDE.md). API REST tunnel wà lábẹ́ `/api/tunnels/{cloudflared,ngrok,tailscale}/*`, ó sì dúró lọ́tọ̀ sí ẹ̀wọ̀n aṣojú ìrìnàjò jáde tí a ṣàkọsílẹ̀ lókè.

### API 1proxy

| Ọ̀nà      | Ojú-ọ̀nà                                | Àpèjúwe                     |
| -------- | -------------------------------------- | --------------------------- |
| `GET`    | `/api/settings/oneproxy`               | Ṣàkójọ àwọn aṣojú 1proxy    |
| `GET`    | `/api/settings/oneproxy?action=stats`  | Gba ìṣirò + ipò ìmúdójúìwọ̀n |
| `GET`    | `/api/settings/oneproxy?action=status` | Gba ipò ìmúdójúìwọ̀n nìkan   |
| `POST`   | `/api/settings/oneproxy`               | Bẹ̀rẹ̀ ìmúdójúìwọ̀n            |
| `POST`   | `/api/settings/oneproxy/rotate`        | Yí padà sí aṣojú tó kàn     |
| `DELETE` | `/api/settings/oneproxy?id=uuid`       | Pa ọ̀kan rẹ́                  |
| `DELETE` | `/api/settings/oneproxy?clearAll=1`    | Pa gbogbo rẹ́                |

### API Aṣojú Òkè

| Ọ̀nà      | Ojú-ọ̀nà                           | Àpèjúwe                 |
| -------- | --------------------------------- | ----------------------- |
| `GET`    | `/api/upstream-proxy/:providerId` | Gba ìṣètò aṣojú òkè     |
| `PUT`    | `/api/upstream-proxy/:providerId` | Ṣètò ìpo aṣojú òkè      |
| `DELETE` | `/api/upstream-proxy/:providerId` | Yọ ìṣètò aṣojú òkè kúrò |

---

## Àwọn Àyípadà Àyíká

| Àyípadà               | Àìyípadà | Àpèjúwe                                                                |
| --------------------- | -------- | ---------------------------------------------------------------------- |
| `ENABLE_SOCKS5_PROXY` | `true`   | Mú àtìlẹ́yìn aṣojú SOCKS5 ṣiṣẹ́ (àìyípadà jẹ́ `true` nínú `.env.example`) |

---

## Yíyanjú Ìṣòro

### "SOCKS5 proxy is disabled"

Ṣètò `ENABLE_SOCKS5_PROXY=true` nínú fáìlì `.env` rẹ, kí o sì tún un bẹ̀rẹ̀.

### Àwọn àṣìṣe "socket hang up" nípasẹ̀ aṣojú

Èyí jẹ́ ohun tó wọ́pọ̀ pẹ̀lú àwọn aṣojú olówó poku tí ń já àwọn ìsopọ̀ tí kò ṣiṣẹ́ mọ́. OmniRoute ti ń bójú tó èyí tẹ́lẹ̀ nípa:

- Mímú keep-alive ṣiṣẹ́ kúrò lórí àwọn ìsopọ̀ aṣojú (`keepAliveTimeout: 1`)
- Mímú pipelining ṣiṣẹ́ kúrò (`pipelining: 0`)
- Ṣíṣe cache àwọn dispatchers láti yẹra fún handshakes léraléra

Tí ó bá ń bá a lọ, gbìyànjú aṣojú mìíràn tàbí lo ẹ̀ya ìyípo 1proxy.

### "unsupported_country_region_territory" nígbà OAuth

Rí i dájú pé a ti ṣètò aṣojú náà **ṣáájú** kí o tó bẹ̀rẹ̀ ìṣàn OAuth. OmniRoute ń darí pàṣípààrọ̀ token OAuth nípasẹ̀ aṣojú tí a ṣètò. Kọ́kọ́ ṣètò aṣojú àgbáyé tàbí ti ìpele provider, lẹ́yìn náà ni kí o sopọ̀.

### A kò lo aṣojú náà

Ṣàyẹ̀wò ìtòlẹ́sẹẹsẹ ìpinnu:

1. Jẹ́rìí sí i pẹ̀lú `GET /api/settings/proxy?resolve=your-connection-id`
2. Ṣàyẹ̀wò bóyá `status` aṣojú jẹ́ `active` (kì í ṣe `inactive`)
3. Rí i dájú pé scope ìfiṣàmúlò aṣojú bá ìsopọ̀ rẹ mu

### Ìmúdọ́gba 1proxy ń kùnà

Ṣàyẹ̀wò ipò ìmúdọ́gba:

```bash
curl "http://localhost:20128/api/settings/oneproxy?action=status"
```

Tí `consecutiveFailures >= 5`, circuit breaker ti ṣiṣẹ́. Tún server náà bẹ̀rẹ̀ láti tún un ṣètò, tàbí dúró de àtúntò afọwọ́ṣe.

---

## Àwòrán Ìṣètò Database

### Tábìlì `proxy_registry`

```sql
CREATE TABLE proxy_registry (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  type TEXT NOT NULL DEFAULT 'http',
  host TEXT NOT NULL,
  port INTEGER NOT NULL,
  username TEXT DEFAULT '',
  password TEXT DEFAULT '',
  region TEXT,
  notes TEXT,
  status TEXT DEFAULT 'active',
  source TEXT NOT NULL DEFAULT 'manual',    -- 'manual' tàbí 'oneproxy'
  quality_score INTEGER,                     -- 0-100 (1proxy nìkan)
  latency_ms INTEGER,                        -- milliseconds (1proxy nìkan)
  anonymity TEXT,                            -- transparent/anonymous/elite
  google_access INTEGER DEFAULT 0,           -- ṣé ó lè ráyè sí Google? (1proxy)
  last_validated TEXT,                       -- timestamp ISO (1proxy)
  country_code TEXT,                         -- kóòdù ISO onílẹ́tà méjì (1proxy)
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);
```

### Tábìlì `proxy_assignments`

```sql
CREATE TABLE proxy_assignments (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  proxy_id TEXT NOT NULL REFERENCES proxy_registry(id),
  scope TEXT NOT NULL,        -- 'global', 'provider', 'account', 'combo'
  scope_id TEXT,              -- ID provider, ID ìsopọ̀, tàbí ID combo
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(scope, scope_id)
);
```

---

## Ṣíṣàyẹ̀wò Ìlera Aṣojú (v3.8.16+)

Ẹ̀rọ **proxy fast-fail** ti OmniRoute (`src/lib/proxyHealth.ts`) ń ṣàwárí àwọn aṣojú tí kò ṣiṣẹ́ lábẹ́ 2s nípasẹ̀ àyẹ̀wò ìsopọ̀ TCP kánkán, lẹ́yìn náà ó **ń fi àbájáde náà pamọ́ sínú cache** láti yẹra fún àfikún iṣẹ́ lórí ìbéèrè kọ̀ọ̀kan.

### Bí Ó Ṣe Ń Ṣiṣẹ́

```
Ìbéèrè ──▶ ProxyHealthCache.get(url)
             │
             ├─ Ó wà nínú cache + ó ṣì tuntun?  ──▶ dá ipò inú cache padà
             │
             └─ Kò sí nínú cache / ó ti pẹ́?  ──▶ so TCP pọ̀ mọ́ host:port
                                          (àkókò tó pọ̀jù: FAST_FAIL_TIMEOUT_MS)
                                          ──▶ fi pamọ́ sínú cache fún HEALTH_CACHE_TTL_MS
                                          ──▶ dá àbájáde padà
```

Láìsí èyí, aṣojú tí kò ṣiṣẹ́ yóò dí gbogbo ìbéèrè fún gbogbo iye `PROXY_TIMEOUT_MS` (àìyípadà jẹ́ 30s) kí ó tó kùnà.

### Àwọn Àyípadà Àyíká Tí A Lè Ṣàtúnṣe

| Àyípadà                      | Àìyípadà | Ète                                                |
| ---------------------------- | -------- | -------------------------------------------------- |
| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000`   | Àkókò tó pọ̀jù fún ìsopọ̀ TCP fún àyẹ̀wò ìlera kọ̀ọ̀kan |
| `PROXY_HEALTH_CACHE_TTL_MS`  | `30000`  | Bí àbájáde ìlera ṣe máa pẹ́ tó nínú cache           |

**Àwọn iye tí a dámọ̀ràn:**

| Ipò                                | Àkókò tó pọ̀jù fún fast-fail | TTL cache | Ìdí                                                                          |
| ---------------------------------- | --------------------------- | --------- | ---------------------------------------------------------------------------- |
| API gateway aláwọlé-púpọ̀           | 1500ms                      | 60000ms   | Ìkùnà kánkán tó le, cache tó gùn láti dín àwọn àyẹ̀wò kù                      |
| Àwọn node tí a pín káàkiri agbègbè | 3000ms                      | 15000ms   | Àwọn network tó lọ́ra nílò àkókò púpọ̀ sí i; cache tó kúrú fún failover kánkán |
| Ìdàgbàsókè / ìdánwò                | 1000ms                      | 10000ms   | Àtúnṣe kánkán lórí àwọn aṣojú agbègbè                                        |
| Ìfarapamọ́ / ìdènà ìṣàwárí          | 2500ms                      | 45000ms   | Yẹra fún àyẹ̀wò kánkán léraléra tó lè mú àwọn ààlà rate ṣiṣẹ́                  |

### Ṣíṣàyẹ̀wò Ìlera Aṣojú

```ts
import { getAllProxyHealthStatuses, invalidateProxyHealth } from "omniroute/proxyHealth";

const statuses = getAllProxyHealthStatuses();
for (const s of statuses) {
  console.log(`${s.proxyUrl} → healthy=${s.healthy}, stale=${s.stale}`);
}

// Fipá mú àtúnyẹ̀wò aṣojú pàtó kan
invalidateProxyHealth("http://user:pass@203.0.113.7:8080");
```

Àmì `stale` jẹ́ `true` nígbà tí àkọsílẹ̀ cache bá ti kọjá `HEALTH_CACHE_TTL_MS`, tí ìbéèrè tó tẹ̀lé yóò sì fa àyẹ̀wò tuntun.

### Àwọn Àìyípadà Fún Irú Aṣojú Kọ̀ọ̀kan

Àyẹ̀wò ìlera ń lo àwọn àìyípadà tó bójú mu gẹ́gẹ́ bí URL scheme:

| Scheme                     | Port àìyípadà |
| -------------------------- | ------------- |
| `http://`                  | 8080          |
| `https://`                 | 443           |
| `socks5://` / `socks5h://` | 1080          |

Àwọn port àdáni nínú URL (`http://host:9999`) máa ń ní ààyè àkọ́kọ́ lórí àìyípadà scheme ní gbogbo ìgbà.

---

## Ìtúpalẹ̀ & Àkíyèsí Proxy

OmniRoute ń tọpinpin lílò proxy kọ̀ọ̀kan láti ran àwọn olùṣàkóso lọ́wọ́ láti ṣàyẹ̀wò àwọn àṣà ìdarí ọ̀nà, ìlọ́ra tó ga lójijì, àti àwọn ìkùnà tó ń ṣẹlẹ̀ léraléra.

### Ohun Tí A Ń Tọpinpin

Fún gbogbo ìbéèrè tó gba inú proxy tí a ti ṣètò kọjá, OmniRoute ń ṣe àkọsílẹ̀:

| Ìwọ̀n         | Àpèjúwe                                                 |
| ------------ | ------------------------------------------------------- |
| `proxy_url`  | URL proxy kíkún (pẹ̀lú àwọn ẹ̀rí ìfàṣẹsí tí a fi pamọ́)    |
| `provider`   | ID olùpèsè upstream (openai, anthropic, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ) |
| `latency_ms` | Àpapọ̀ àkókò ìrìn-àti-padà, pẹ̀lú ìbáṣepọ̀ proxy           |
| `connect_ms` | Àkókò ìsopọ̀ TCP nìkan                                   |
| `status`     | Kóòdù ipò HTTP láti upstream                            |
| `error`      | Ẹ̀ka àṣìṣe bí ìbéèrè bá kùnà                             |
| `timestamp`  | ISO 8601 UTC                                            |

### Wíwọlé sí Dátà Náà

```bash
# Àwọn ìṣẹ̀lẹ̀ proxy àìpẹ́
curl -H "Authorization: Bearer $OMNIROUTE_KEY" \
  "http://localhost:20128/api/usage/proxy-logs?limit=100"
```

Endpoint gidi náà ni `/api/usage/proxy-logs` (wo `src/app/api/usage/proxy-logs/route.ts`). Endpoint yìí ń ṣe àtìlẹ́yìn fún:

- `GET /api/usage/proxy-logs` — gba àwọn àkọsílẹ̀ proxy
- `DELETE /api/usage/proxy-logs` — pa gbogbo àwọn àkọsílẹ̀ proxy rẹ́

A lè béèrè àwọn ìṣirò àkójọpọ̀ tààrà láti inú tábìlì `proxy_logs` nípasẹ̀ SQL bí ó bá yẹ. UI dashboard lè pèsè àwọn ìwòye àkójọpọ̀.

### Àwọn Àṣà Tó Wọ́pọ̀

**Ṣàwárí proxy tó ń ṣiṣẹ́ tí ó sì ń kùnà lẹ́ẹ̀kọ̀ọ̀kan** (ó ń yí padà láàárín àṣeyọrí/ìkùnà):

```sql
SELECT proxy_url,
       COUNT(*) AS total,
       SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) AS errors,
       ROUND(100.0 * SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END) / COUNT(*), 1) AS error_pct
FROM proxy_logs
WHERE timestamp > datetime('now', '-1 hour')
GROUP BY proxy_url
HAVING error_pct > 5
ORDER BY error_pct DESC;
```

**Wá àwọn proxy tó lọ́ra** (ìlọ́ra p95 > 2s):

```sql
WITH ranked AS (
  SELECT proxy_url, latency_ms,
         PERCENT_RANK() OVER (PARTITION BY proxy_url ORDER BY latency_ms) AS pct
  FROM proxy_logs
  WHERE timestamp > datetime('now', '-24 hour')
)
SELECT proxy_url, latency_ms
FROM ranked
WHERE pct >= 0.95
ORDER BY latency_ms DESC;
```

---

## Igi Ìpinnu Ọgbọ́n Ìyípo

Nígbà tí a bá yan ọ̀pọ̀ proxy sí scope kan, OmniRoute máa ń lo **ọgbọ́n ìyípo** láti yan èyí tí yóò lò fún ìbéèrè kọ̀ọ̀kan. A máa ń ṣètò ọgbọ́n náà ní ìpele scope (àgbáyé, fún olùpèsè kọ̀ọ̀kan, fún àkọọ́lẹ̀ kọ̀ọ̀kan, fún àkópọ̀ kọ̀ọ̀kan).

### Àwọn Ọgbọ́n Tó Wà

| Ọgbọ́n                | Ìgbà tí o yẹ kí a lò ó                              | Àlejò                                                                             |
| -------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
| `quality` (àìyípadà) | Iṣẹ́ gidi pẹ̀lú àwọn proxy tó ní ìdánilójú oríṣiríṣi  | Ó fẹ́ràn àwọn proxy tí wọ́n ní ìwọ̀n gíga; ó lè má fún àwọn tó ní ìwọ̀n kékeré ní iṣẹ́ |
| `random`             | Pínpín ẹrù iṣẹ́, àṣírí                               | Pínpín tó dọ́gba; kò ka àwọn àmì ìdánilójú sí                                      |
| `sequential`         | Ṣíṣe àtúnṣe àṣìṣe, ìdánwò tí àbájáde rẹ̀ ṣeé sọ tẹ́lẹ̀ | Ó ń gba àwọn proxy lọ́kọ̀ọ̀kan ní ìtòlẹ́sẹẹsẹ; ó rọrùn láti lóye                      |

### Igi Ìpinnu

```
                    Ṣé o ní àwọn ìwọ̀n ìdánilójú fún àwọn proxy rẹ?
                    │
        ┌───────────┴───────────┐
        │                       │
      BẸ́Ẹ̀NI                  RÁRÁ
        │                       │
   Ṣé gbogbo proxy             │
   fẹ́rẹ̀ẹ́ dọ́gba              │
   ní ìdánilójú?                │
        │                       │
   ┌────┴────┐                  │
   │         │                  │
 BẸ́Ẹ̀NI    RÁRÁ               Lo
   │         │              `random`
   │         │              (pínpín dọ́gba
   │         │              ń kó dátà
   │         │              ìdánilójú jọ
   │         │              bí àkókò ti ń lọ)
   │         │
   │    Lo `quality`
   │    (ó dára jù fún
   │    ìdánilójú oríṣiríṣi)
   │
Lo `random`
(pín ẹrù iṣẹ́
ní dọ́gba)
```

## Yíyọ Àṣìṣe Kúrò Láìfọwọ́ṣe fún Àwọn Proxy Tirẹ

Àkójọpọ̀ ọjà 1proxy ti máa ń dín ìwọ̀n àwọn proxy tí ó kùnà kù láìfọwọ́ṣe fúnra rẹ̀ (wo
[Àwọn Ìwọ̀n Didára Proxy](#proxy-quality-scores)). Fún
àwọn proxy tí **ìwọ** ṣàfikún sí registry, olùṣètò ìlera abẹ́lẹ̀
(`src/lib/proxyHealth/scheduler.ts`) ń pèsè ìhùwàsí kan náà ti “yọ ọmọ ẹgbẹ́ tí kò
ṣiṣẹ́ kúrò nínú chain láìfọwọ́ṣe”, láìpa ohunkóhun rẹ́:

```bash
# .env — pa proxy kan fún ìgbà díẹ̀ lẹ́yìn probe mẹ́ta tí ó kùnà léraléra, kí o sì tún mú un ṣiṣẹ́
# láìfọwọ́ṣe ní kété tí ó bá bẹ̀rẹ̀ sí í dáhùn sí àwọn probe lẹ́ẹ̀kan sí i.
PROXY_AUTO_DISABLE=true
PROXY_AUTO_REMOVE_AFTER=3
```

Bí ó ṣe wọ inú chain proxy-púpọ̀:

1. Olùṣètò náà ń ṣe probe gbogbo proxy tí a forúkọsílẹ̀ ní gbogbo `PROXY_HEALTH_INTERVAL_MS`
   (àìyípadà jẹ́ ìṣẹ́jú 10; èyí tí ó kéré jù jẹ́ ìṣẹ́jú 1).
2. Lẹ́yìn àwọn ìkùnà **tí a fìdí rẹ̀ múlẹ̀** léraléra tó jẹ́ `PROXY_AUTO_REMOVE_AFTER` (ìkùnà
   àsopọ̀ gidi — timeout tàbí 5xx ti ibi-afẹ́ probe fúnra rẹ̀ kì í kà rárá, wo
   [Ṣíṣe Àyẹ̀wò Ìlera Proxy](#proxy-health-checking-v3816)), a ó ṣètò `status` proxy náà
   sí `dead`.
3. `dead` jẹ́ ọ̀kan lára àwọn status tí àlẹ̀mọ́ status-alààyè, tí ìṣàtúnṣe pool/rotation
   ń lò, máa ń yọ kúrò; nítorí náà rotation ti scope kan (round-robin / random / sticky /
   latency — wo [Igi Ìpinnu Ètò Rotation](#rotation-strategy-decision-tree))
   máa dá fífi proxy náà fún àwọn request tuntun dúró lẹ́sẹ̀kẹsẹ̀. Kò sí proxy mìíràn nínú
   pool tí èyí máa kan, gbogbo pool náà kò sì ní yí padà sí àsopọ̀ tààrà láìsọ —
   wo olùṣọ́ fail-closed ti [Ètò Proxy Ìpele Mẹ́rin](#4-level-proxy-system).
4. Olùṣètò náà ń bá a lọ láti ṣe probe àwọn proxy `dead` ní àárín àkókò kan náà. Probe
   àṣeyọrí tó tẹ̀lé máa yí `status` padà sí `active`, yóò sì tún wọ rotation —
   kò nílò àfikún-ọ̀wọ́ lẹ́ẹ̀kan sí i.

A mọ̀ọ́mọ̀ ṣe èyí ní ọ̀nà **opt-in tí kì í ba nǹkan jẹ́**: nípa àìyípadà, olùṣètò náà kàn
ń ka àwọn ìkùnà, ó sì ń kọ wọ́n sínú log (wo policy C nínú `decision.ts`), àti pé
`PROXY_AUTO_DISABLE` kì í pa row kan rẹ́ láé — flag ọ̀tọ̀ tí ó le koko jù,
`PROXY_AUTO_REMOVE`, ni a fi ń ṣe bẹ́ẹ̀. Bí a bá ṣètò àwọn méjèèjì sí `true`,
`PROXY_AUTO_REMOVE` ni yóò borí (proxy tí a fẹ́rẹ̀ẹ́ pa rẹ́ kò nílò soft-disable
láàárín). Wo ìtọ́kasí [Àtúnṣe Environment](../reference/ENVIRONMENT.md) fún àkójọ
variable ní ẹ̀kúnrẹ́rẹ́.

---

> 📖 **Ìwé ìtọ́kasí tó jẹmọ́:**
>
> - [Ìtọ́sọ́nà Olùlò](../guides/USER_GUIDE.md) — Ìṣètò àti àtúnṣe gbogbogbòò
> - [Ìtọ́kasí API](../reference/API_REFERENCE.md) — Ìwé API ní ẹ̀kúnrẹ́rẹ́
> - [Àtúnṣe Environment](../reference/ENVIRONMENT.md) — Gbogbo environment variable