How to Use OpenCodex

What OpenCodex Is (and How It Differs From Codex CLI)

This OpenCodex project is a community fork of an earlier OpenAI Codex CLI codebase. It documents multiple model-provider options, including OpenAI, Gemini, OpenRouter, and Ollama. The current OpenAI Codex CLI is maintained separately and has its own installation, authentication, and release path.

How a Request Moves Through OpenCodex

The provider changes where the model request goes; it does not remove the need to review local file and command access.

Installing OpenCodex on Your Machine

Version 0.1.31 declares Node.js 22 or newer. Install a supported runtime from the Node.js download page, then confirm the versions available in your terminal:

node --version
npm --version

For a repeatable evaluation, pin the documented package version rather than relying on an unspecified future release:

npm install -g [email protected]
open-codex --help

Stop if the help command does not display the expected CLI options. Test the package only in a disposable or version-controlled repository, and do not work around installation errors with an unfamiliar sudo command.

Use npm for the project covered here. Similarly named pip packages are separate projects with different maintainers and behavior.

Connecting a Model — API Key or Local LLM

For a hosted provider, keep its required key in the terminal environment or a secret manager. For example, the project documents OPENAI_API_KEY for its OpenAI provider:

export OPENAI_API_KEY="replace-with-your-key"

Do not paste a real key into a prompt, commit it to Git, or expose it in screenshots. If you use a project .env file, confirm that Git ignores it before adding a credential.

For a local-model path, install and start Ollama, make sure the intended model is available, and save the OpenCodex settings in ~/.codex/config.json:

{
 "provider": "ollama",
 "model": "your-installed-model",
 "approvalMode": "suggest"
}

Then run open-codex from the test repository. If the model cannot be reached, check the provider name, credential or local-service status, and model identifier before changing application code.

Running Your First Command Safely

Begin in a disposable or version-controlled test repository and confirm the working tree:

git status
open-codex --approval-mode suggest "Read README.md. Describe one small improvement. Do not edit files or run commands. List the files and checks a later change would require."

Keep the first task read-only. Review the response, then request one small change only after you understand the files involved. After any accepted edit, inspect the diff and run the narrowest relevant check:

git diff

Do not begin with full-auto in an unfamiliar repository. Keep production credentials outside the working directory, create a Git checkpoint, and ask the tool to report changed files, commands, results, and skipped checks.

How HappySeeds fits this workflow

OpenCodex is a terminal-first implementation tool that assumes you are prepared to manage a repository, credentials, and command approval. HappySeeds serves the earlier product-planning path for non-technical commercial builders: define the intended user, app flow, data, and launch experience before deciding whether repository-level work is necessary.

Use the HappySeeds quick start to shape the first app request, or browse app templates when you need a concrete starting structure. If you are choosing between direct code ownership and a guided app-building workflow, review the Codex and AI app builder comparison.

Start With a Clear Product Boundary

If the product flow is still unsettled, start with the HappySeeds quick start or choose an app template before giving an experimental terminal agent access to a repository.