• 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.

      A ChatGPT subscription and a model API key are two ways to connect Midscene. You can choose either based on your model payment plan.

      Quick start

      Choose the section for your environment. Both paths use MIDSCENE_MODEL_AUTH_MODE="siwc", so Midscene reads the saved credentials and refreshes access tokens automatically.

      Available models depend on your ChatGPT account. The examples below use gpt-6-sol. GPT model families and usage notes are the same as when using a model API key.

      Browser extension

      1. In the extension's model configuration dialog, click Use your ChatGPT plan and follow the on-screen instructions to sign in and authorize plan usage.
      2. Paste the following configuration into the same dialog:
      MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
      1. Click Verify to test the connection. For failed checks, see Model advanced configuration and debugging.

      CLI / SDK

      First, run the following command 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 saves credentials to ~/.midscene/siwc.json. Complete this sign-in manually before first use.

      Next, add the following configuration to your .env file. See the model configuration guide for how to load it into your runtime.

      MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"

      Finally, 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. For failed checks, see Model advanced configuration and debugging.

      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.
      • CLI credentials are saved to ~/.midscene/siwc.json; extension credentials are saved in the extension's local storage. Midscene does not collect your credentials.
      • With MIDSCENE_MODEL_AUTH_MODE="siwc", Midscene automatically refreshes access tokens at runtime, so you do not need to manage them manually. This is supported in both Node.js and the browser extension. If refreshing fails, authorize again.
      • The CLI and browser extension store credentials independently. Refreshing tokens from the command line does not update the browser extension's credentials.
      • Follow OpenAI's regional restrictions and terms of use. See the Sign in with ChatGPT Terms.

      Advanced: manage access tokens manually

      Use this path if you prefer to manage tokens yourself. Do not set MIDSCENE_MODEL_AUTH_MODE="siwc" in this case.

      Get and configure an access token

      Run the login command and complete authorization in your browser:

      pnpm dlx @midscene/cli model siwc login

      The command saves credentials to ~/.midscene/siwc.json and prints an access token and its expiration time. Replace <your-access-token> below with that token:

      🤖 Use as default model
      🎯 Use as Locate 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 handles these settings automatically when using SIWC authentication in the quick start.

      Load this configuration into your runtime following the model configuration guide, or paste it into the extension's model configuration dialog. Verify the connection with pnpm dlx @midscene/cli model verify from the directory containing your .env file, or click Verify in the extension.

      Refresh the access token

      According to OpenAI's documentation, access tokens expire after one hour. A refresh token is needed to obtain a new access token. See the OpenAI token reference.

      Run the following command to refresh the token:

      pnpm dlx @midscene/cli model siwc refresh

      The command updates the local credentials and prints a new access token. Replace MIDSCENE_MODEL_API_KEY with the new token and reload the configuration. If you pasted the token into the extension, update its configuration too.

      Legacy: reuse your Codex sign-in

      This approach is deprecated. Use the SIWC quick start above for new setups.

      Existing Codex sign-in configuration

      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.