---
name: codex-oauth-plus-onboarding
description: "Low-token, stable workflow for BOSS's Codex/OpenAI OAuth onboarding: ClawEmail signup, optional 5sim SMS phone verification, and callback import into CPA/Codex2API/SUB2API."
version: 2.0.0
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [codex, oauth, clawemail, 5sim, cpa, codex2api, sub2api, browser-automation]
related_skills: [clawemail-operations, browser-extension-storage-audit]
---
# Codex OAuth + CPA/Codex2API Onboarding — low-token runbook
Use when BOSS asks to register/login an OpenAI/Codex OAuth account, verify it via ClawEmail and possibly 5sim SMS, then import the OAuth callback into **CPA / CLI Proxy API**, Codex2API, or SUB2API.
Safety: BOSS-owned infra/accounts only. Stop for CAPTCHA/security challenge/payment confirmation unless BOSS explicitly approves the next step. Never reveal API keys, passwords, proxy URLs, full phone numbers, OAuth `code=`, SMS/email codes, admin keys, or tokens; report `[REDACTED]`.
## 0. Required companion skill
Before ClawEmail work, load:
```text
clawemail-operations
```
## 1. Low-token operating mode
Prefer script-driven runs that emit compact JSONL. Only send screenshots or long logs when a gate fails.
### Tool/reporting rules
- Read secrets only from `~/.hermes/env/codex_oauth_onboarding.env`; do not paste them into chat.
- **Do not blindly `source` this env file in shell**: values such as `CHROME_BIN=/Applications/Google Chrome.app/...` may contain spaces and break `source` if unquoted. For probes/runners, parse `KEY=VALUE` safely in Python or require quoted values before shell sourcing.
- Reports should contain: phase, account email, country slug, activation id, high-level status, HTTP status, and redacted error class.
- Avoid dumping HTML, callback URLs, headers, full 5sim responses, or full phone numbers.
- Save detailed evidence to `references/` or local logs; final response stays concise.
## 2. Environment constants for BOSS
```text
env: ~/.hermes/env/codex_oauth_onboarding.env
workspace: /Users/chick/.Hermes/workspace
OAuth Chrome CDP default: 9223
ClawEmail Dashboard CDP default: 9224
OAuth profile root: /Users/chick/.Hermes/workspace/browser-profiles/codex-oauth
Dashboard profile: /Users/chick/.Hermes/workspace/browser-profiles/clawemail-dashboard-persistent
Preferred browser proxy when unspecified: socks5://192.168.2.8:1085
Chrome: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
```
Use visible Google Chrome for OpenAI/Auth pages. Do not use BOSS's personal browser profile.
## 3. Hard gates — do not skip
1. **Target gate**: exactly one target mode: `cpa`, `codex2api`, or `sub2api`. No default if env is empty.
2. **Password gate**: `CUSTOM_PASSWORD` must be set unless BOSS approves generating one.
3. **Proxy gate**: verify proxy TCP and OpenAI reachability before browser flow.
4. **Mailbox gate**: new ClawEmail sub-mailbox must have external receive enabled before OpenAI signup.
5. **OpenAI identity gate before phone**: only buy 5sim if active page is a usable `https://auth.openai.com/add-phone` for a non-deactivated account.
6. **Country gate before phone buy/submit**: OpenAI select value and visible dial code must match target country before buying and again before clicking Continue.
7. **SMS-only gate**: if OpenAI resend channel probes as WhatsApp, do not click it; cancel/rotate under SMS-only policy.
8. **Callback state gate**: callback `state` must match generated OAuth state when known.
9. **Payment gate**: any Plus/GoPay paid action needs explicit BOSS confirmation.
## 4. Recommended decision tree
```text
Need OAuth import?
├─ Target CPA available? → prefer CPA (most reliable after 2026-05-10 success)
├─ Codex2API requested? → try Codex2API; if token exchange returns unsupported_country_region_territory, switch/fix backend proxy or use CPA
└─ SUB2API requested? → use original extension/content-script path
Need new OpenAI account?
├─ Create ClawEmail sub-mailbox with 8 lowercase letters
├─ Enable external receive via Dashboard API
├─ Submit email/password, poll ClawEmail code
└─ If phone page appears → 5sim SMS flow
Already phone-verified account?
└─ Generate fresh target OAuth URL, login/consent, submit callback to target
```
## 5. ClawEmail sub-mailbox gate
BOSS preference: per-run ClawEmail prefix is **exactly 8 lowercase letters** with no `codex` prefix, e.g. `chickliu.ktqcxzux@claw.163.com`.
After creation, enable external receive. Observed Dashboard API base:
```text
https://claw.163.com/mailserv-claw-dashboard/api/v1
```
Do not use relative `/api/v1/...` if it returns public ClawEmail HTML. Working sequence: `GET /workspaces` -> `GET /mailboxes?workspaceId=` -> find the target sub-mailbox id -> `POST /mailboxes/comm-settings?id=` with the payload above. If controlling the persistent Dashboard Chrome on CDP `9224` fails with `Handshake status 403 Forbidden ... remote-allow-origins`, use `websocket.create_connection(ws_url, suppress_origin=True)` or restart Chrome with `--remote-allow-origins=*`.
Required final values:
```json
{"commLevel":2,"extReceiveType":1,"extSendType":0}
```
Use Dashboard persistent Chrome/profile for master login, not the disposable OAuth profile. If Dashboard login needs a master QQ mailbox code and the agent cannot retrieve it, ask BOSS. If automating through CDP, Chrome may reject WebSocket Origin unless launched with `--remote-allow-origins=*`; Python `websocket-client` can connect with `suppress_origin=True`. If relative `/api/v1/workspaces` returns raw/empty data, inspect Dashboard resource URLs and try the full `https://claw.163.com/mailserv-claw-dashboard/api/v1/...` base before diagnosing mailbox absence; see `clawemail-operations` reference `references/clawemail-dashboard-cdp-origin-and-api-base-pitfalls-2026-05-10.md`.
Key references:
- `references/clawemail-external-receive-gate-openai-2026-05-10.md`
- `references/clawemail-random-suffix-policy-2026-05.md`
## 6. OpenAI email/profile flow
Minimal flow:
```text
fresh OAuth URL / signup page
submit ClawEmail sub-mailbox
submit CUSTOM_PASSWORD
poll ClawEmail inbox/spam for OpenAI code
submit code
fill profile/about-you if shown
continue to phone or OAuth consent
```
If OpenAI returns `account_deactivated`, stop that account immediately and do not buy 5sim numbers.
If login recovery hits `Incorrect email address or password`, `invalid_state`, stale email verification, or tab ambiguity, stop before buying phone numbers; recover account/page first.
## 7. 5sim SMS phone flow
Use 5sim **SMS activation** for product/service `openai`; do not use WhatsApp receive.
Env/API:
```text
PHONE_SMS_PROVIDER=5sim
FIVE_SIM_OPERATOR=any
FIVE_SIM_PRODUCT=openai
FIVE_SIM_SERVICE=openai
BUY: /v1/user/buy/activation/{country}/any/openai
CHECK: /v1/user/check/{activation_id}
FINISH: /v1/user/finish/{activation_id}
CANCEL: /v1/user/cancel/{activation_id}
```
Country precedence for configured runs:
```text
FIVE_SIM_COUNTRY_ORDER > FIVE_SIM_COUNTRY_ID > vietnam fallback only if both empty
```
For free-country exploration, ignore stale configured order if BOSS explicitly says unrestricted. Count only real activations with ids toward the budget. `no free phones`, pre-buy country-gate errors, CDP errors, or OAuth recovery failures are not attempts.
Known mappings:
```text
vietnam -> VN -> 越南 (+84) -> 84
argentina -> AR -> 阿根廷 (+54) -> 54
netherlands -> NL -> 荷兰 (+31) -> 31
indonesia -> ID -> 印度尼西亚 (+62) -> 62
italy -> IT -> 意大利 (+39) -> 39
poland -> PL -> 波兰 (+48) -> 48
spain -> ES -> 西班牙 (+34) -> 34
england -> GB -> 英国 (+44) -> 44
chile -> CL -> 智利 (+56) -> 56
portugal -> PT -> 葡萄牙 (+351) -> 351
germany -> DE -> 德国 (+49) -> 49
romania -> RO -> 罗马尼亚 (+40) -> 40
```
Phone handling:
```text
OpenAI immediate reject → cancel activation, rotate
No immediate reject → poll 5sim
Before resend → probe channel text/value/aria/title
├─ WhatsApp → cancel/rotate (SMS-only)
└─ SMS/unknown → click resend, poll again
SMS received → submit code, finish activation, verify page leaves phone-verification
Interrupted runner → inspect/cancel active RECEIVED activations immediately
```
Known result: free-country run succeeded with Vietnam SMS, activation `1006871765`, status `FINISHED`; OpenAI phone verification passed. See `references/openai-phone-free-country-vietnam-sms-success-codex2api-region-block-2026-05-10.md`.
## 8. CPA / CLI Proxy API — preferred callback target
CPA succeeded where Codex2API failed. Use this when `CPA_VPS_URL` and `CPA_VPS_PASSWORD` are configured.
Derive API origin:
```python
origin = new URL(CPA_VPS_URL).origin
# e.g. http://192.168.2.62:8317/management.html -> http://192.168.2.62:8317
```
Headers, matching original extension:
```text
Authorization: Bearer [CPA_VPS_PASSWORD]
X-Management-Key: [CPA_VPS_PASSWORD]
Accept: application/json
Content-Type: application/json
```
Generate OAuth URL:
```text
GET /v0/management/codex-auth-url
# UI also uses: GET /v0/management/codex-auth-url?is_webui=true
```
Extract URL from `url|auth_url|authUrl|data.*`; extract state from payload or URL.
Submit callback:
```text
POST /v0/management/oauth-callback
{"provider":"codex","redirect_url":"http://localhost:1455/auth/callback?code=[REDACTED]&state=[REDACTED]"}
```
Verify:
```text
GET /v0/management/get-auth-status?state= -> {"status":"ok"}
GET /v0/management/auth-files -> codex--free.json active
```
Do **not** use root `/codex-auth-url` or `/api/auth/url`; they can 404 or return unrelated `amp upstream proxy not available`.
References:
- `references/cpa-original-extension-api-notes-2026-05-10.md`
- `references/cpa-panel-codex-oauth-success-2026-05-10.md`
## 9. Codex2API target
Generate URL:
```text
POST /api/admin/oauth/generate-auth-url
Header: X-Admin-Key: [CODEX2API_ADMIN_KEY]
Body: {}
```
Expected response contains:
```json
{"auth_url":"...","session_id":"..."}
```
Exchange callback:
```text
POST /api/admin/oauth/exchange-code
Header: X-Admin-Key: [CODEX2API_ADMIN_KEY]
{"session_id":"...","code":"[REDACTED]","state":"..."}
```
If callback/token exchange returns `unsupported_country_region_territory`, browser-side OAuth is not the issue. The backend token exchange path needs a supported outbound proxy or use CPA.
## 10. SUB2API target
Use original extension/content-script route for SUB2API panel login, group, proxy, priority, and callback exchange. Do not invent direct API endpoints unless re-confirmed from source/UI.
## 11. Browser/CDP hygiene
Before fresh OAuth recovery:
```text
close stale auth.openai.com / phone-verification / localhost callback tabs
keep only the current intended target tab
```
Use visible Chrome with isolated profile. Chrome stable may ignore `--load-extension`; verify extension card/sidepanel if using the extension. Manual CDP flow is acceptable when BOSS only wants registration/OAuth tested; still follow all gates.
When connecting to Chrome CDP with `websocket-client`, Chrome may reject the WebSocket handshake with `403 Forbidden` unless the client sends an allowed Origin or Chrome was launched with `--remote-allow-origins=*`. Prefer launching automation Chrome with `--remote-allow-origins=*`; for an already-running CDP instance, pass `origin='http://127.0.0.1:'` or a matching allowed origin to `websocket.create_connection(...)` before assuming CDP is down.
## 12. Plus / GoPay
Default ordinary account test:
```text
PLUS_MODE_ENABLED=false
```
If Plus is requested:
```text
PLUS_PAYMENT_METHOD=gopay
GOPAY_OTP_SOURCE=manual
GOPAY_OTP empty by default
```
Stop immediately before paid confirmation and ask BOSS.
## 13. Verification checklist before final report
- [ ] New mailbox external receive enabled and recorded.
- [ ] OpenAI email verification completed or classified.
- [ ] If phone appeared: all active 5sim orders are FINISHED or CANCELED.
- [ ] If SMS succeeded: OpenAI left `phone-verification` page.
- [ ] OAuth callback submitted to chosen target.
- [ ] Target has active account/session/auth file.
- [ ] Final report redacts secrets, callback codes, SMS/email codes, full phone numbers, API keys, passwords, proxy strings.
- [ ] If new learning occurred, update this skill or a reference.
## 14. Evidence and history references
Full pre-rewrite skill was archived at:
```text
references/SKILL-full-before-low-token-rewrite-2026-05-10.md
```
High-value references:
```text
references/env-parsing-and-cdp-origin-pitfalls-2026-05-10.md
references/cpa-original-extension-api-notes-2026-05-10.md
references/cpa-panel-codex-oauth-success-2026-05-10.md
references/openai-phone-free-country-vietnam-sms-success-codex2api-region-block-2026-05-10.md
references/openai-add-phone-strict-country-gate-2026-05-10.md
references/openai-add-phone-free-country-runner-policy-2026-05-10.md
references/openai-login-recovery-gate-before-phone-runs-2026-05-10.md
references/openai-oauth-tab-cleanup-before-recovery-2026-05-10.md
references/openai-phone-country-scheduler-cyclic-chunks-2026-05-10.md
references/clawemail-external-receive-gate-openai-2026-05-10.md
references/openai-add-phone-chile-no-free-phones-2026-05-10.md
references/openai-add-phone-eu4-total20-real-activations-2026-05-10.md
references/official-extension-phone-update-2026-05-10.md
```