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

      Sign in

      The CLI provides a general-purpose way to authorize. 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 and prints an access token and its expiration time. Complete sign-in manually before first use.

      If you use the browser extension, click Use your ChatGPT plan in its model configuration dialog and follow the on-screen instructions to authorize, without running a command. Your credentials will be saved in the extension's local storage.

      Configure the model

      For SIWC authentication, use the following configuration, with gpt-6-sol as an example:

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

      Midscene reads the access token from the saved credentials and uses it as the API Key to call OpenAI models, automatically using the Responses API and streaming as required by OpenAI.

      Paste this configuration into the browser extension's model configuration dialog, or follow the model configuration guide to load it into your runtime.

      Available models depend on your ChatGPT account. GPT model families and usage notes are the same as when using a model API key.

      Configure an access token manually

      If you prefer to manage tokens yourself, use the following configuration. Do not set MIDSCENE_MODEL_AUTH_MODE="siwc" in this case.

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

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

      Verify the connection

      In the browser extension, click Verify in the model configuration dialog to test the connection.

      To verify from the command line, 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.

      Once verification succeeds, continue with the tasks in Try the GUI Agent. For failed checks, see Model advanced configuration and debugging.

      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.

      With MIDSCENE_MODEL_AUTH_MODE="siwc", Midscene manages token refreshing at runtime in both Node.js and the browser extension. If refreshing fails, you need to sign in and authorize again manually.

      If you manage tokens yourself, run the following command to refresh them manually:

      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.

      The browser extension stores credentials separately. Refreshing from the command line does not update the extension’s credentials.

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