• English

      • Use a ChatGPT subscription

      Authorize Midscene through Sign in with ChatGPT (SIWC) to call GPT models using your ChatGPT subscription. This guide walks you through sign-in, configuration, and connection verification.

      Choose either a ChatGPT subscription or a model API key to connect Midscene. You only need to complete one of these setup guides.

      Sign in

      Run in your terminal:

      pnpm dlx @midscene/cli model siwc login

      Follow the terminal instructions to sign in to ChatGPT in your browser and authorize plan usage. You can choose a name for your Agent during authorization. Once authorized, the Agent appears on your ChatGPT usage page.

      The command prints an access token and its expiration time. Copy the token to use as MIDSCENE_MODEL_API_KEY in the next step.

      Configure the model

      The following example uses gpt-6-sol. Replace <your-access-token> with the token you just obtained:

      🎯 Use as default model
      🧠 Use as Planning model
      🔎 Use as Insight model
      MIDSCENE_MODEL_BASE_URL="https://api.openai.com/v1"
MIDSCENE_MODEL_API_KEY="<your-access-token>"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
MIDSCENE_MODEL_PROTOCOL="openai-responses" # SIWC requires the Responses API
MIDSCENE_MODEL_STREAM_MODE="stream" # SIWC requires streaming

      SIWC requires the Responses API with streaming enabled. Keep the openai-responses and stream settings in the example. Midscene sets store: false by default, as required by this flow. See the official OpenAI documentation.

      Available models depend on your ChatGPT account. For other GPT model names, families, and usage notes, see Use a model API key.

      Load the configuration

      Load the complete configuration above according to how you use Midscene:

      • Playground: Paste the configuration text into the settings page.
      • CLI: Create a .env file in the directory where you run commands and paste the configuration without adding export. The CLI reads this file automatically.
      • JavaScript SDK: Load the configuration into the Node.js process environment. For .env files, follow Load configuration with dotenv.

      The credentials saved by the sign-in command do not automatically populate these model settings. You still need to set MIDSCENE_MODEL_API_KEY manually.

      Verify the connection

      Run this command in the directory containing your .env file:

      pnpm dlx @midscene/cli model verify

      This command uses values from .env to override variables with the same names in the current shell. If your configuration is only saved in Playground, save the same configuration to .env before running the command.

      Once verification succeeds, continue with the tasks in Quick start. For failed checks, see Model debugging and observability.

      Refresh the access token

      Access tokens are valid for one hour. See the OpenAI token reference. Check the expiration time printed by the sign-in command and refresh the token with:

      pnpm dlx @midscene/cli model siwc refresh

      The command updates the local credentials and prints a new access token. Replace MIDSCENE_MODEL_API_KEY in Playground, .env, or your environment variables, then reload the configuration before running another task.

      Usage and credentials

      • SIWC consumes your subscription usage. ChatGPT determines how token consumption translates into plan usage. Midscene reports show token consumption for each task step.
      • Full credentials are saved locally to ~/.midscene/siwc.json for subsequent refreshes. Midscene does not collect your credentials.
      • Follow OpenAI's regional restrictions and terms of use. See the Sign in with ChatGPT Terms.

      Reuse your Codex sign-in (deprecated)

      If you already signed in with Codex Cli (codex login) and want Midscene to use that OAuth session directly, set:

      export MIDSCENE_MODEL_BASE_URL="codex://app-server"
export MIDSCENE_MODEL_NAME="gpt-6-sol" # or another model shown by Codex model/list
export MIDSCENE_MODEL_FAMILY="gpt-6"

      Notes:

      • MIDSCENE_MODEL_API_KEY is not required in this mode.
      • Midscene will call codex app-server through stdio.
      • Make sure codex is available in your PATH and verify auth with codex login status.

      The drawback of this approach is that we have observed longer execution times and higher token consumption than when calling an OpenAI-compatible API directly. For this reason, we do not recommend it.