Chatgpt2cli

README

# ChatGPT Web CLI

[中文](README.zh-CN.md) | English

ChatGPT Web CLI is a local browser automation tool and OpenClaw native plugin
that lets agents submit work to ChatGPT Web through a logged-in Chrome session.

It is not the official OpenAI API. It drives the ChatGPT Web UI through Chrome
CDP, so it should be treated as a local automation bridge that depends on the
current ChatGPT web experience, account limits, and an authenticated browser
profile.

## What It Provides

- Non-blocking ChatGPT Web jobs for OpenClaw.
- Automatic JSON callback delivery back to the originating OpenClaw session.
- File upload review via `askWithFiles`.
- Image generation via ChatGPT Web.
- A packaged workflow skeleton, including `reviewSource`.
- Windows/WSL Chrome bridging through `chatgpt-win.sh`.
- A hard global cap of 3 simultaneous browser reply runs.
- Structured async errors for rate limits, quota exhaustion, delivery unknown,
  Chrome/CDP configuration problems, and unavailable reasoning effort.

## Project Status

The project is ready for GitHub publication as a beta/canary-grade OpenClaw
plugin. The current code has automated unit checks, release checks, package
checks, wrapper smoke tests, SDK compile smoke, and real Chrome smoke coverage
for core paths.

Recommended positioning:

- Good for trusted local use and OpenClaw plugin canary installs.
- Good for source review and early adopters who understand browser automation.
- Not a replacement for the official OpenAI API.
- Not guaranteed against future ChatGPT Web UI changes.

## Quick Start

From the plugin directory:

```bash
npm ci
npm run build
npm run health-check
./chatgpt-win.sh ensureChrome
```

Log in to ChatGPT in the opened Chrome profile if needed. Do not put ChatGPT
credentials into scripts or environment variables.

Manual smoke:

```bash
./chatgpt-win.sh ask "Reply with OK only."
./chatgpt-win.sh askWithFiles "Summarize the attached file." "/absolute/path/file.md"
./chatgpt-win.sh generate --json "A simple white-background line diagram."
```

## OpenClaw Plugin Use

When installed as an OpenClaw native plugin, prefer native tools instead of
shell commands:

- `chatgpt_ensure_chrome`
- `chatgpt_submit`
- `chatgpt_status`
- `chatgpt_result`
- `chatgpt_ack`
- `chatgpt_next_event`
- `chatgpt_workflow_run`
- `chatgpt_workflow_status`
- `chatgpt_workflow_resume`
- `chatgpt_workflow_artifact`

Normal flow:

1. Call `chatgpt_submit`.
2. Wait for the automatic JSON callback envelope with
   `schema="chatgpt-web-cli.async.delivery"`.
3. Deduplicate by `idempotencyKey` or `deliveryId`.
4. Call `chatgpt_ack` after durably accepting the callback.

Use `chatgpt_status`, `chatgpt_result`, or `chatgpt_next_event` only for
diagnostics or recovery when the callback did not arrive.

The store-safe `chatgpt_submit` surface supports:

- `ask`
- `askWithFiles`
- `generate`

Standalone trusted CLI still supports `conversation` and
`conversationWithFiles`, but those are not exposed through the native OpenClaw
plugin until multi-agent conversation isolation is proven.

## Windows/WSL Notes

From WSL, use the repository wrapper:

```bash
./chatgpt-win.sh ...
```

Do not bypass it with custom `powershell.exe` commands. The wrapper handles WSL
path conversion, selected Windows Chrome profile routing, CDP startup, stdin
protection, environment forwarding, temporary prompt files, downloads, locks,
and runtime state paths.

To reuse an existing Chrome login, configure both values and close normal
Chrome before `ensureChrome`:

```bash
CHATGPT_WINDOWS_CHROME_USER_DATA_DIR="/mnt/c/Users/<WindowsUser>/AppData/Local/Google/Chrome/User Data"
CHATGPT_WINDOWS_CHROME_PROFILE_DIRECTORY="Default"
```

`CHATGPT_WINDOWS_CHROME_USER_DATA_DIR` must be the Chrome `User Data` root, not
`.../User Data/Default`.

## Reasoning Effort

Default OpenClaw plugin effort is `very-high`.

Supported values:

- `low`
- `medium`
- `high`
- `very-high`
- `pro`

Use `pro` only when the current ChatGPT composer exposes and confirms Pro. If
Pro quota is exhausted, ChatGPT may hide it; use `very-high`.

Legacy `--thinking` and `--instant` flags are ignored unless
`CHATGPT_ENABLE_LEGACY_MODEL_MODE=1`.

## Workflows

The built-in workflow is `reviewSource`:

```bash
./chatgpt-win.sh workflow validate reviewSource
./chatgpt-win.sh workflow run reviewSource --set archivePath=/absolute/path/source.zip
./chatgpt-win.sh workflow status <runId>
./chatgpt-win.sh workflow artifact <runId> web_audit_result
```

For OpenClaw, use:

- `chatgpt_workflow_run`
- `chatgpt_workflow_status`
- `chatgpt_workflow_artifact`

## Agent Guidance

This package includes plugin-local instructions for agents:

- `skills/chatgpt-web-cli/SKILL.md`
- `docs/OPENCLAW-AI.md`
- `docs/AGENTS.md`

Do not copy these into a user's personal `TOOLS.md`. Keeping the guidance
inside the plugin lets each OpenClaw install use the instructions that match
the installed version.

## Verification

Useful checks before publishing or canary installs:

```bash
npm run build
npm run test:unit
npm run release-check
npm run health-check
npm run package:source
npm run test:wrapper-args
npm run test:chrome-start-lock
npm run test:openclaw-sdk-compile
```

Real browser tests require a trusted machine with a logged-in ChatGPT Chrome
profile:

```bash
RUN_REAL_CHATGPT_CLI_TESTS=1 npm run test:real-cli
npm run test:openclaw-nonblock
```

## More Documentation

- `docs/QUICKSTART.md`
- `docs/README.md`
- `docs/OPENCLAW-AI.md`

## License

No license has been selected yet. Add a `LICENSE` file before presenting this as
an open-source project that others may copy, modify, or redistribute.