soia-env-codex-setup-support

Use this skill for Codex environment checks and installation support. By default it is read-only, proceeds in layers, and loads reference files on demand; unless the customer explicitly confirms, do not install, delete, move, clean up, or modify system and application data.

Customer-readable explanation

What this skill can do

Customer wants	Skill will do	Delivery format
Install or verify Codex	Check version, source, desktop host, and CLI	Results table + next steps
Check for Codex updates	Separately identify the version, source, and update entry point of the ChatGPT desktop app and the CLI, without auto-updating	Current version, latest version, and recommendation
Update Codex to the latest	After the customer explicitly requests the latest version, update the desktop app or CLI separately	Intermediate state, login/signature re-verification, and failure rollback boundaries
Codex got slow or stuck	Categorize by resources, logs, network, and workspace	Category table + evidence
Check SSD health	Read SMART and space information read-only	Health table + risk explanation
Check `logs_2.sqlite`	Compare files, WAL, ID rates, and hotspots read-only	Write risk table + handling boundaries

How customers use it

Other recognizable phrasings include "check disk health" and "Codex keeps writing to the SSD"; when only installing or updating the Codex CLI, hand it off to soia-env-codex-install。

Describe the goal directly, for example "check disk health", "Codex got slow", "check logs_2.sqlite". The Agent is read-only by default; when a new version is found, it only reports it. When the customer only says "update Codex", first ask whether to update to the latest version, and only execute after they explicitly choose the latest version. Login, system authorization, installation, and data isolation will still be explained separately and confirmation will be requested.

Dependencies and installation

Dependency	Purpose	Rule
macOS/Windows/Linux	System and architecture identification	Identify first, then choose the platform branch
`smartmontools`	macOS SMART reading	Do not install automatically; customer confirmation required
SQLite CLI	Read-only queries on the log database	If missing, report as not checked; do not create the database
Node/npm, network skills	CLI installation and login	Load only when entering the corresponding branch

Boundary between desktop and CLI

Codex desktop capability is carried by OpenAI's official ChatGPT desktop app; whether a standalone Codex.app exists can no longer be used as the basis for judgment. On macOS, prioritize checking ChatGPT.app 's bundle id com.openai.codex, version, and code signature.
The CLI uses the official @openai/codex or the official standalone installation entry point; the login, version, update, and workspace permissions of the desktop app and CLI must be verified separately.
soia-env-codex-install is retained as the CLI-specific installation skill; this skill handles the orchestration of the desktop app, CLI, and troubleshooting, and does not reinvent the login flow.

Delivery rules

For each check, first give a results table, then give conclusions and next steps. Do not treat command echoes as a report, and do not write unchecked items as normal:

Category	Check item	Result	Evidence	Risk	Update time	Next step
	<specific metric>	<normal/warning/abnormal/not checked>	<brief value or status>	<low/medium/high>		<action or none>

更新时间 is the time when evidence was last obtained for this check item; it can differ between check items, and the skill file modification time must not be used as a substitute.

After the table, keep only three sections:

Conclusion: answer in one sentence whether a problem was found and which category the problem belongs to.
Solution: give executable actions by priority; mark them as "read-only", "needs confirmation", or "not executed".
Residual risk: list evidence not obtained, parts that cannot be attributed, and conditions for rechecking.

When the check results need detailed explanation, first read the corresponding references/ file; do not copy all underlying commands back into this file.

Progressive workflow

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-env@soia

Install only this one skill:

npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-codex-setup-support -y

WorkBuddy 's installation unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, so it needs to be installed separately, see docs/install/workbuddy.md。

Layer 0: Identify the request

Select one or more categories from the user's goal; do not expand all branches at the same time:

Category	Triggering symptom	First-layer evidence	Detailed workflow
A Version and installation	Not installed, cannot open, old version	OS, architecture, desktop/CLI version, official source	Official source and desktop identification script
B Network and login	Download failure, login loop, API unreachable	DNS/HTTPS, browser authorization, organization permissions	`soia-env-network-diagnose`
C Permissions and workspace	Directory cannot be read or written, task cannot start	Directory permissions, Git, project dependencies	Check the workspace last; do not misdiagnose installation failures
D Resources and rendering	High CPU/RSS, long-thread lag, unresponsive interface	Process resources, reproduction time, thread scale	Application/resource branch; check together with E when necessary
E SQLite log write amplification	`logs_2.sqlite`/WAL grows large, high-frequency TRACE, abnormal SSD writes	File snapshot,`MAX(id)` rate, hot target, holding process	sqlite-log-diagnostics.md
F SSD health	SMART warning, high wear, abnormal temperature or errors	Physical device, SMART, space	macos-disk-health.md

For "slowness", check D first by default; enter E only when disk, TRACE, WAL, or write symptoms appear. For "high SSD writes", both E and F must be checked; the log database byte count cannot directly replace the SSD host write volume.

Layer 1: Common baseline

Collect only the following minimum information read-only: operating system and architecture, available space, desktop application version, CLI version, target category. Do not print full usernames, tokens, cookies, API keys, passwords, or full local paths.

Desktop and CLI may share a Codex home; you cannot infer that the desktop app or log database is working just because the CLI runs. macOS desktop identification uses scripts/check_codex_desktop.py, and the output serves only as version/signature evidence.

Installed status and updates

The desktop app and CLI must be judged separately; when an installation is found and usable, prompt "installed, no need to reinstall"; do not treat a reinstall as an update.

For CLI, first run codex --version、codex update --help、codex login status, and record command -v codex along with the installation source.
When the CLI supports codex update , use it only after the customer explicitly requests updating to the latest; when it is managed by npm and does not support built-in updates, use npm install -g @openai/codex@latest; when managed by a standalone installer, follow the update entry point in the official CLI documentation.
The ChatGPT desktop app (Codex host) is updated via the in-app or official desktop app update entry point only after the customer explicitly requests updating the desktop version to the latest; the CLI's codex update cannot be used in place of a desktop app update.
After a macOS update, rerun the desktop identification script to confirm com.openai.codex, version, and code signature; after a CLI update, re-verify version, help, and login status. Updating the version does not mean logging in again; do not force the customer to reauthorize.
Before updating, record the old version, source, and key verification results; if the update fails, keep the existing installation and do not automatically uninstall, clear logs, or delete app data.

An ambiguous "update Codex" completes only the independent version reports for the desktop app and CLI, and the handling result is written as "waiting to confirm whether to update to the latest"; do not run any updater. CLI updates are delegated to soia-env-codex-install; this skill records the complete intermediate state.

Tier 2: Single-issue branch

Load only the references needed for the current branch:

A: Read official-sources.md, and if Node/npm or the CLI is missing, call the corresponding dependency skill.
B/C/D: Run read-only diagnostics first; without evidence, do not modify proxy, DNS, PATH, permissions, or workspace.
E: Read sqlite-log-diagnostics.mdin full, use a read-only SQLite connection, and take two samples.
F: Read macos-disk-health.mdin full, first confirm the physical device, then read SMART; do not automatically install smartmontools。

Tier 3: Advanced handling

Only when Tier 2 evidence reaches high risk should you discuss quitting the app, backup, isolation, or rebuilding the log database. Before any state change, you must show the target, impact, backup location, and rollback method, and obtain customer confirmation. Diagnostic requests end here; do not go ahead and perform repairs.

Solution priority

Priority	Action	Default permission	Applicable conditions
1	Recommend updating the desktop app/CLI, then fully quit and restart and retest	Perform only after explicitly requesting the latest version	Version is old or write amplification appears in branch E
2	Close duplicate processes, reduce the reproduction scope, and resample	Requires customer confirmation	No active tasks and confirmed process ownership relationship
3	After backup, isolate the log database and let the app rebuild it	Requires customer confirmation	Branch E reaches high risk, and no process holds it
4	`VACUUM`, triggers, changing WAL, RAM disk	High risk; do not provide execution commands by default	Only explicitly chosen by advanced maintenance personnel; these are not the preferred fixes
5	SMART/hardware handling	Customer confirmation required	F branch shows error, lifespan, or temperature warning; back up first

VACUUM will rewrite the database and cannot prevent continued writes; macOS's /tmp is usually still on the SSD and cannot be treated as a RAM disk. Switching to the CLI is also not a reliable fix for the E branch.

Usage boundaries of scripts and references

scripts/check_codex_desktop.py: read-only identification of the macOS ChatGPT host, bundle id, version, and code signature.
scripts/check_macos_disk.py: only parses the SMART summary already obtained; does not execute sudo, long tests, or any disk operations.
scripts/record_install_progress.py: appends a private phase record only when this skill directly installs smartmontools, desktop applications, or performs other installation-type changes; CLI updates are recorded by soia-env-codex-install .
references/: stores commands, field explanations, platform differences, thresholds, and advanced handling; loaded only when entering the corresponding branch.
Do not add large blocks of shell, SQL, PowerShell, or raw vendor documentation in SKILL.md ; reusable deterministic logic should preferably go into scripts, and explanatory content should go into reference files.

Private information and intermediate data

Codex/ChatGPT login credentials are managed by the official client, CLI login flow, and system credential store; SOIA configuration stores only non-secret preferences and paths.
Diagnostics by default output only redacted summaries, and do not copy ChatGPT/Codex databases, log bodies, conversation content, or tokens.
Write to the user state directory only when the customer explicitly requests saving a diagnostic receipt; when this skill directly performs installation-type changes, the progress recorder must be used. Rebuildable metadata goes in cache, and short-term copies such as database snapshots may only go in the system temporary directory and must be cleaned up after success or failure.
Receipts retain only categories, values, versions, results, and checked_at, and do not record accounts, query content, or customer-private absolute paths.

Logs and completion receipts

Installation or explicitly authorized latest-version updates must display the following phase table while executing, and synchronously call the progress recorder when each phase actually occurs; historical entries must not be written after the fact, and record times are generated by the recorder. Read-only diagnostics do not create installation records:

Phase	Current status	Update time	Processing result
<check/plan/waiting for confirmation/install or update/verify/complete or failed>	<in progress/waiting/completed/failed/blocked>		<redacted result>

After using the results table, finish with the following minimal format:

结论：<类别>，<正常/预警/异常/未完成>。

解决方案：<已执行的只读检查；需确认的动作；没有执行的状态变更写 none>。

残余风险：<未检查项、不能归因的部分、复查条件>。

Forward testing

Verify the results table with at least four types of samples: SMART normal, SMART warning, SQLite file stable, SQLite MAX(id) advancing but row count remaining stable. Verification must not modify the real database or disk.

Security boundaries

Read-only by default; do not automatically sudo, install packages, modify PATH/profile, proxy/DNS, permissions, databases, or workspaces.
Customers complete login, verification codes, and system authorization only in the official UI; customers are not required to enter secrets in the terminal.
Do not perform deletion, overwriting, formatting, partitioning, firmware upgrades,VACUUM, database checkpoint, triggers, or log cleanup unless the customer separately confirms after seeing an explicit plan.
Real acceptance must not treat npm returning 0 as login completion, nor treat SMART PASSED as absolute overall machine health.