docs: record ClawEmail dashboard full API base

skill/codex-oauth-plus-onboarding/SKILL.md

@@ -31,6 +31,7 @@ Prefer script-driven runs that emit compact JSONL. Only send screenshots or long
 ### 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.
@@ -87,16 +88,18 @@ BOSS preference: per-run ClawEmail prefix is **exactly 8 lowercase letters** wit
 After creation, enable external receive. Observed Dashboard API base:
 
 ```text
-https://claw.163.com/mailserv-claw-dashboard
+https://claw.163.com/mailserv-claw-dashboard/api/v1
 ```
 
+Do not use relative `/api/v1/...` if it returns public ClawEmail HTML. Working sequence: `GET <base>/workspaces` -> `GET <base>/mailboxes?workspaceId=<workspaceId>` -> find the target sub-mailbox id -> `POST <base>/mailboxes/comm-settings?id=<mailboxId>` 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.
+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:
 
@@ -268,6 +271,8 @@ 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:<port>'` or a matching allowed origin to `websocket.create_connection(...)` before assuming CDP is down.
+
 ## 12. Plus / GoPay
 
 Default ordinary account test:
@@ -308,6 +313,7 @@ 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

skill/codex-oauth-plus-onboarding/references/env-parsing-and-cdp-origin-pitfalls-2026-05-10.md

@@ -0,0 +1,64 @@
+# 2026-05-10 run pitfall: env parsing and Chrome CDP Origin
+
+During a follow-up run using the low-token Codex OAuth skill, two reusable pitfalls appeared before the flow reached OpenAI signup:
+
+## 1. Do not blindly `source` the env file
+
+`~/.hermes/env/codex_oauth_onboarding.env` may contain unquoted paths with spaces, e.g. Chrome app paths. Plain shell `source` can fail with an error like:
+
+```text
+...codex_oauth_onboarding.env: line 7: Chrome.app/Contents/MacOS/Google: No such file or directory
+```
+
+For validation/probe scripts, parse `KEY=VALUE` safely in Python instead of shell sourcing, or require quoting before shell use.
+
+Minimal safe parser pattern:
+
+```python
+from pathlib import Path
+import re, shlex
+
+env = {}
+for line in Path.home().joinpath('.hermes/env/codex_oauth_onboarding.env').read_text().splitlines():
+    line = line.strip()
+    if not line or line.startswith('#') or '=' not in line:
+        continue
+    if line.startswith('export '):
+        line = line[7:].strip()
+    k, v = line.split('=', 1)
+    k, v = k.strip(), v.strip()
+    if not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', k):
+        continue
+    try:
+        if v and v[0] in '"\'':
+            v = shlex.split(v)[0]
+    except Exception:
+        pass
+    env[k] = v.strip('"\'')
+```
+
+## 2. Chrome CDP WebSocket Origin rejection
+
+When using Python `websocket-client` against an existing Chrome remote debugging port, Chrome can reject the handshake:
+
+```text
+websocket._exceptions.WebSocketBadStatusException:
+Handshake status 403 Forbidden
+Rejected an incoming WebSocket connection from the http://127.0.0.1:9224 origin.
+Use --remote-allow-origins=http://127.0.0.1:9224 or --remote-allow-origins=*
+```
+
+Preferred prevention: launch automation Chrome with:
+
+```bash
+--remote-allow-origins=*
+```
+
+If the Chrome instance is already running, try a matching Origin when connecting:
+
+```python
+import websocket
+ws = websocket.create_connection(ws_url, timeout=10, origin='http://127.0.0.1:9224')
+```
+
+Do this before concluding Dashboard CDP is unavailable.