Do not commit filled env files or secrets. The template is intentionally blank for platform credentials, proxy, password, SMS providers, and payment details.
description: "Use when BOSS asks to register a ChatGPT/Codex OAuth account flow with ClawEmail, optionally open Plus through GoPay/GPC, and authorize the OAuth callback into SUB2API, Codex2API, or CPA using an isolated proxied browser profile."
This skill describes the safe, repeatable workflow for using the local `codex-oauth-automation-extension` project to run a **single user-authorized onboarding flow**:
1. Use **ClawEmail** as the registration mailbox.
2. Register/Login through ChatGPT/OpenAI auth.
3. Optionally open ChatGPT Plus through **GoPay / GPC helper**.
4. Complete OAuth authorization.
5. Submit the localhost OAuth callback to exactly one configured target: **SUB2API**, **Codex2API**, or **CPA**.
6. Run the browser in an isolated profile with a dedicated proxy.
The skill is for BOSS's own infrastructure and accounts only. Do not use it for spam, credential stuffing, rate-limit evasion, CAPTCHA bypass, unauthorized account creation, or bulk registration. If a page asks for CAPTCHA, security challenge, phone ownership proof, payment confirmation, or another user-visible anti-abuse checkpoint, pause and ask BOSS to complete/approve it manually.
Also load `clawemail-operations` before any ClawEmail mailbox work.
## BOSS-specific Operating Defaults
These are confirmed operating rules for BOSS's environment:
- Use **Google Chrome stable** at `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` with a real visible window.
- Do **not** set a default target platform. If `PANEL_MODE` is empty or not one of `cpa|sub2api|codex2api`, stop before launching the run.
- Proxies are supplied as unauthenticated `socks5://host:port` or `http://host:port`; do not expect proxy username/password.
- The new account password is unified through `CUSTOM_PASSWORD`. If it is empty, stop and ask BOSS to fill it, unless BOSS explicitly allows auto-generation for that run.
- ClawEmail creates a fresh mailbox for every run (`CLAWEMAIL_CREATE_PER_RUN=true`). Record every created mailbox locally with outcome classification: pending, success, failed.
- Phone/SMS platform has no default. Keep `PHONE_VERIFICATION_ENABLED=false` and `PHONE_SMS_PROVIDER` empty unless BOSS configures one or approves enabling it after a phone verification appears.
- Plus mode uses `PLUS_PAYMENT_METHOD=gopay`. Any paid GoPay action still requires explicit confirmation immediately before payment/approval.
- GoPay WhatsApp OTP uses **方案 A / manual checkpoint**: set `GOPAY_OTP_SOURCE=manual`. The extension detects OTP input and opens a side-panel prompt (`requestGoPayOtpInput` / “输入 GoPay 验证码”); BOSS pastes the WhatsApp code, then the extension fills OTP, fills `GOPAY_PIN`, and continues.
-`GOPAY_OTP` should normally stay empty before the run. It is only a temporary prefill/cache for the current OTP dialog, not a durable secret.
- Do not implement WhatsApp scraping/API automation unless BOSS explicitly requests it later.
1.**Explicit target**: BOSS must specify exactly one target mode: `sub2api`, `codex2api`, or `cpa`; there is no default target, and an empty `PANEL_MODE` must stop execution.
2.**Single-run default**: default to one account / one OAuth flow unless BOSS explicitly requests a count.
3.**No CAPTCHA bypass**: if Cloudflare/CAPTCHA/security challenge appears, stop and report the required manual action.
4.**Payment checkpoint**: Plus mode is GoPay for BOSS, but before any GoPay payment or paid operation, confirm that BOSS wants to proceed.
5.**No secret leakage**: never print API keys, admin keys, proxy addresses if sensitive, refresh tokens, card keys, or OAuth callback URLs containing `code=` in final summaries. Redact as `[REDACTED]`.
6.**Config export risk**: the extension’s built-in settings export may contain secrets. Treat exported files as sensitive.
7.**Mailbox records**: every freshly-created ClawEmail mailbox must be recorded locally with run id and final status (`pending`, `success`, or `failed`).
Validate tests when modifying or before relying on a changed checkout:
```bash
cd /Users/chick/.Hermes/workspace/research/codex-oauth-automation-extension
node --test tests/*.test.js
```
Observed verification result during initial study: `772` tests passed, `0` failed.
## Configuration File
Create a dedicated env file instead of typing secrets into chat. A fuller template is stored with this skill at `templates/codex_oauth_onboarding.env.example`.
2.**Panel / target mode**: `PANEL_MODE=cpa|sub2api|codex2api` has **no default**; if empty, stop. Fill only the selected target’s auth fields copied from the original side panel (`CPA_VPS_URL`/`CPA_VPS_PASSWORD`, or `SUB2API_*`, or `CODEX2API_*`).
3.**Proxy**: fill `BROWSER_PROXY_SERVER` with BOSS-provided unauthenticated `socks5://host:port` or `http://host:port`; use `IP_PROXY_*` only when using the original extension’s built-in 711proxy/IP proxy panel.
4.**Registration identity and password**: `CLAWEMAIL_CREATE_PER_RUN=true`, `CLAWEMAIL_PREFIX`, `CLAWEMAIL_RECORD_FILE`, `SIGNUP_METHOD=email`, and unified `CUSTOM_PASSWORD`.
5.**Mail provider**: `MAIL_PROVIDER`, `EMAIL_GENERATOR`, and original-provider fields only if not polling ClawEmail from Hermes.
6.**Phone/SMS verification fallback**: no default provider; keep `PHONE_VERIFICATION_ENABLED=false` and `PHONE_SMS_PROVIDER` empty unless configured/approved.
7.**Plus/payment**: `PLUS_MODE_ENABLED=true`, `PLUS_PAYMENT_METHOD=gopay`; paid operations still require explicit confirmation.
- Use `[REDACTED]` in reports for all secret values.
- If multiple target sections are filled, only the section selected by `OAUTH_TARGET_MODE` should be used.
## Browser Isolation and Proxy Strategy
This workflow must use a **real visible Chrome/Chromium browser**. Do not use headless browser mode for registration, payment, OAuth consent, or security-sensitive OpenAI/Auth pages.
Use a **dedicated browser profile** per run or per account. “无痕模式” in Chrome does not normally persist extension state and may not allow side panel/extensions unless explicitly enabled. For this extension, prefer a real visible browser with:
- Dedicated clean `user-data-dir` profile.
- Loaded unpacked extension from `CODEX_OAUTH_EXTENSION_DIR`.
- Proxy applied at browser launch or by a verified local proxy wrapper.
- Human-visible UI for CAPTCHA/security/payment checkpoints.
- Profile cleared after success if BOSS wants no local residue.
If proxy authentication is required and Chrome launch flags do not authenticate reliably, use one of these approaches:
1. Use an upstream proxy URL that embeds auth only in a local proxy wrapper, not in command history.
2. Start a local forwarding proxy that injects upstream credentials.
3. Configure proxy credentials inside the extension only if the extension supports it and the config file is protected.
Do not reuse the normal personal browser profile for this workflow.
## ClawEmail Preparation
Load `clawemail-operations` and verify:
```bash
mail-cli auth test --json
mail-cli clawemail list --json
mail-cli clawemail info --uid "$CLAWEMAIL_UID" --json
```
Registration email choice:
- Default: use `CLAWEMAIL_UID` directly.
- If BOSS wants per-run sub-mailboxes, create them with `mail-cli clawemail create --prefix ...` and set the extension’s registration email to the created UID.
For code retrieval, the extension may interact with mail provider pages or helper logic, but ClawEmail can also be polled by Hermes:
```bash
mail-cli mail list --fid 1 --limit 20 --json
mail-cli read body --id '<message-id>'
```
Always quote message IDs.
## Extension Architecture Reference
The project is a Manifest V3 Chrome extension:
-`manifest.json`: permissions, host permissions, content scripts, side panel.
-`background.js`: service worker and state orchestration.
-`background/message-router.js`: handles sidepanel messages such as `EXECUTE_STEP`, `AUTO_RUN`, `SAVE_SETTING`, `EXPORT_SETTINGS`, `IMPORT_SETTINGS`.
-`data/step-definitions.js`: step list for normal and Plus modes.
-`background/steps/*.js`: one executor per major step.
-`content/signup-page.js`: OpenAI/Auth page DOM automation.
-`content/*mail*.js`: mail provider automation.
-`sidepanel/sidepanel.js`: UI controls and settings collection.
Important permissions include `tabs`, `webNavigation`, `webRequest`, `proxy`, `debugger`, `cookies`, `browsingData`, `storage`, `scripting`, `activeTab`, and `<all_urls>` host access.
## Normal OAuth Flow Steps
Normal mode step definitions:
1.`open-chatgpt` — clear ChatGPT/OpenAI cookies and open ChatGPT.
2.`submit-signup-email` — enter email or phone registration identity.
3.`fill-password` — generate/use password and submit.
4.`fetch-signup-code` — fetch registration verification code from mailbox/SMS.
5.`fill-profile` — generate and submit name + birthday.
6.`wait-registration-success` — wait for registration to stabilize.
7.`oauth-login` — refresh OAuth URL from selected target and log in.
8.`fetch-login-code` — fetch login verification code if needed.
10.`platform-verify` — submit callback/code/state to SUB2API, Codex2API, or CPA.
## Plus Flow Steps
When `PLUS_MODE_ENABLED=true`, the extension switches step definitions.
PayPal Plus path:
1-5. same registration steps.
6.`plus-checkout-create` — create Plus Checkout.
7.`plus-checkout-billing` — fill billing and submit order.
8.`paypal-approve` — PayPal login/approval.
9.`plus-checkout-return` — confirm return.
10.`oauth-login`.
11.`fetch-login-code`.
12.`confirm-oauth`.
13.`platform-verify`.
GoPay/GPC helper paths use similar Plus step positions, with payment-specific logic in `background/steps/create-plus-checkout.js`, `fill-plus-checkout.js`, `gopay-*`, and helper API settings.
## Applying Settings in the Extension
The sidepanel normally sends settings through `SAVE_SETTING`; the background persists keys in `chrome.storage.local` via `PERSISTED_SETTING_KEYS`.
Manual UI route:
1. Open isolated Chrome profile with extension loaded.
2. Open the extension side panel.
3. Set `panelMode` according to `OAUTH_TARGET_MODE`:
-`sub2api` → fill SUB2API URL/email/password/group/proxy/priority.
-`codex2api` → fill Codex2API URL/Admin Key.
-`cpa` → fill CPA URL and management key.
4. Set registration email to ClawEmail mailbox.
5. Enable Plus mode only if requested.
6. Select `gpc-helper` / GoPay settings when using GoPay/GPC.
7. Configure proxy mode if the extension manages proxy; otherwise rely on browser launch proxy.
8. Save settings.
9. Start manual steps or Auto Run with `RUN_COUNT=1`.
Programmatic route, if writing a helper script:
- Prefer controlling the sidepanel UI or sending extension runtime messages from the extension context.
- Do not inject secrets into shell command lines where they will remain in history/process listings.
- Keep settings source in `~/.hermes/env/codex_oauth_onboarding.env`.
## Execution Checklist
1. Load this skill and `clawemail-operations`.
2. Read `~/.hermes/env/codex_oauth_onboarding.env` locally; validate required fields for the selected target.
3. Confirm payment/Plus intent if `PLUS_MODE_ENABLED=true`.
4. Verify ClawEmail auth and selected mailbox.
5. Confirm extension repo exists and tests pass if the checkout changed.
6. Start a dedicated proxied browser profile with the unpacked extension.
7. Open sidepanel and apply settings.
8. Start one run.
9. Monitor logs for:
- registration email submitted
- signup verification code fetched
- profile completed
- Plus checkout/payment status, if enabled
- OAuth URL refreshed
- login code fetched, if required
- localhost callback captured
- platform verification succeeded
10. If security challenge/CAPTCHA/phone/payment confirmation appears, pause and notify BOSS.
11. After success, verify target platform has the new authorized account/session.
12. Redact secrets and callback codes in the final report.
## Storage and Export Risk
The extension stores sensitive configuration in `chrome.storage.local`, including possible:
Runtime state goes mostly to `chrome.storage.session`, including generated email, password, codes, OAuth URL, localhost callback, and target session metadata.
The built-in export function exports `getPersistedSettings()` as JSON; this can include sensitive persistent settings. Treat every export as secret material.
## Troubleshooting
### Extension does not appear
- Confirm Chrome was launched with `--load-extension` and `--disable-extensions-except` pointing to the repo directory.
- Confirm `manifest.json` exists and is Manifest V3.
- Use a non-headless browser. Chrome extension side panels are usually not practical in headless mode.
### Proxy not applied
- Visit an IP-check page in the isolated browser before starting.
- If auth proxy fails, use a local forwarding proxy wrapper.
- Do not put proxy passwords in final answers.
### ClawEmail code not found
- Verify the email address submitted in step 2 matches `CLAWEMAIL_UID` or the created sub-mailbox.
- Use `mail-cli mail list --fid 1 --limit 20 --json` and inspect recent OpenAI messages.
- Check spam/deleted folders if inbox is empty.
### OAuth callback not captured
- Step `confirm-oauth` listens for localhost callback via webNavigation/tabs updates.
- Re-run the OAuth login/confirm steps only, not the full registration, unless the auth session is invalid.
- Verify target mode settings and state value mismatch errors.
### Target verify fails
- For SUB2API, verify URL/email/password/group/priority/proxy fields.
- For Codex2API, verify URL and admin key.
- For CPA, verify management origin/key and callback endpoint support.
- Do not print callback URL with `code=`; redact.
### Plus/GoPay fails
- Confirm Plus mode and payment method are correct.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
