10. Environment Variable Reference

Almost every aspect of omicos's behavior can be overridden with environment variables. This chapter groups them by purpose and lists them all.

General parsing conventions (apply to every variable):

An empty string or pure whitespace is treated as unset and falls back to the default.

Boolean switches accept only 1 / true / yes / on (case-insensitive); any other value counts as "off".

URL-type variables automatically have a trailing slash / stripped.

10.1 Python / Kernel

Variable	Default	Description
`OMICOS_KERNEL_PYTHON`	none	Explicitly specifies the absolute path to the Python interpreter, highest priority. Detected only at startup; restart required after changing it.
`OMICOS_ENV_DIR`	`~/.omicos/env`	The Python environment directory managed by omicos (it looks for `.venv` underneath).
`OMICOS_ENV_AUTO`	off	When true, bootstraps the environment non-interactively (roughly a 1.5 GB download) without prompting.
`OMICOS_KERNEL_BASE_URL`	none	HTTP address of a remote IPython kernel. When set, skips local environment bootstrap and overrides `--kernel-base-url`.
`PYTHON`	none	One of the fallbacks in the interpreter resolution chain.
`CONDA_PREFIX`	none	The currently activated conda environment; a fallback in the resolution chain.
`VIRTUAL_ENV`	none	The currently activated venv; a fallback in the resolution chain.

For the interpreter resolution priority, see Chapter 4.

10.2 Cloud Addresses

Variable	Default	Description
`OMICOS_CLOUD_BASE`	`https://auth.omicos.cn`	Overrides the auth host (generally only for dev/staging). Must have no trailing slash.
`OMICOS_CLOUD_APP_BASE`	derived from cloud_base	Overrides the app (SPA) host. Rarely used, mostly for staging.
`OMICOS_SERVER_URL`	none	Overrides the server URL (dev/staging); takes precedence over cloud_base and the logged-in value.
`OMICOS_UPSTREAM_BASE_URL`	none	Upstream cloud control plane (sync / relay); equivalent to `--upstream-base-url`.
`OMICOS_LOCAL_HOME`	`~/`	Overrides the local data root (location of credentials and workspace_id).
`OMICOS_RUNTIME_HOME`	none	A secondary home for `auth.json` lookup (after LOCAL_HOME, before HOME).
`OMICOS_WORKSPACE_ROOT`	current directory	The workspace root (where sessions / trajectories are stored). Alias: `OMICLAW_WORKSPACE_ROOT`.

The full priority chain for cloud address resolution: OMICOS_UPSTREAM_BASE_URL > --upstream-base-url > the user.cloud_base from login > the default https://auth.omicos.cn.

10.3 Process Identity

Variable	Default	Description
`OMICOS_PROCESS_ID`	`local-<workspace_id>`	Overrides the cloud process id (cli mode automatically appends a `-cli` suffix).
`OMICOS_PROCESS_NAME`	directory / conda name	Overrides the process display name (cli automatically appends `(cli)`).
`OMICOS_PROCESS_TOKEN`	none (from login)	Overrides the cloud auth token (one-time, not persisted).

10.4 LLM Provider / Model

Variable	Description
`OMICOS_LLM_PROVIDER` (legacy alias `OMICOS_PROVIDER`)	Explicitly specifies the provider id (e.g. `deepseek`, `openai`).
`OMICOS_LLM_MODEL` (legacy alias `OMICOS_MODEL`)	Explicitly specifies the model id (e.g. `deepseek-v4-flash`).
`<PROVIDER>_API_KEY`	API key for each provider, with hyphens in the provider id converted to underscores (e.g. `alibaba-coding-plan` → `ALIBABA_CODING_PLAN_API_KEY`).
`<PROVIDER>_API_BASE`	A custom endpoint for each provider.
`OPENAI_API_KEY` / `DEEPSEEK_API_KEY` / `MINIMAX_API_KEY`	The specific key names for common providers.
`CUSTOM_OPENAI_API_BASE`	Custom OpenAI-compatible endpoint; defaults to `http://127.0.0.1:8000/v1`.
`CUSTOM_OPENAI_API_KEY`	Custom OpenAI key (falls back to `OPENAI_API_KEY`).
`CUSTOM_ANTHROPIC_API_KEY`	Custom Anthropic-compatible key (native anthropic is not implemented, so you must go through custom).
`CODEX_CHATGPT_BASE_URL`	Codex OAuth endpoint; defaults to `https://chatgpt.com/backend-api`.
`GEMINI_CODE_ASSIST_BASE_URL`	Gemini OAuth endpoint; defaults to `https://cloudcode-pa.googleapis.com`.

For the selection logic, see Chapter 12: Provider and Model Configuration.

10.5 Vision (Vision Models)

Variable	Description
`OMICOS_VISION_MODEL`	Vision model id (independent of the main chat model).
`OMICOS_VISION_BASE_URL`	Vision model endpoint.
`OMICOS_VISION_API_KEY`	Vision model API key.

10.6 Cache Directories / Cloud URLs / Local Skills

Variable	Default	Description
`OMICOS_MODELS_CACHE_DIR`	`~/.omicos/cloud-models`	Model catalog cache directory.
`OMICOS_MODELS_CLOUD_URL`	derived from app_base	Address for fetching the model catalog.
`OMICOS_AGENTS_CACHE_DIR`	`~/.omicos/cloud-agents`	Agent cache directory.
`OMICOS_AGENTS_CLOUD_URL`	derived from app_base	Address for fetching agents.
`OMICOS_SKILLS_CACHE_DIR`	`~/.omicos/cloud-skills`	Skill cache directory.
`OMICOS_SKILLS_CLOUD_URL`	derived from app_base	Address for fetching skills.
`OMICOS_SKILL_ROOTS`	none	Additional local skill directories (colon- / semicolon-separated).
`OMICOS_MEMORY_CACHE_DIR`	`~/.omicos/cloud-memory`	Memory cache directory.
`OMICOS_MEMORY_CLOUD_URL`	derived from cloud_base	Memory sync address.
`OMICOS_TEMPLATES_DIR`	built-in	Fallback agent template directory.

10.7 Offline Switches / Sync Control

Variable	Description
`OMICOS_AGENTS_OFFLINE`	Disables agent cloud sync; uses the local cache only.
`OMICOS_SKILLS_OFFLINE`	Disables skill cloud sync.
`OMICOS_MODELS_OFFLINE`	Disables model catalog cloud sync.
`OMICOS_MEMORY_OFFLINE`	Disables memory cloud sync.
`OMICOS_SYNC_DISABLE`	Disables trajectory cloud sync.
`OMICOS_SYNC_LOCAL_ONLY`	Uses a regex to exclude specified sessions from upload (invalid regexes are ignored).
`OMICOS_CATALOG_SYNC_SECS`	Agent/skill/model sync interval; defaults to `600` seconds. Values below 30 are not clamped to 30 but are instead discarded and fall back to the 600 default.
`OMICOS_CONV_SYNC_INTERVAL_SEC`	Session sync interval; defaults to `10` seconds (minimum 1 second; non-numeric values fall back to the default).

10.8 Logging / Theme

Variable	Description
`RUST_LOG`	Standard tracing filter (the fallback when `OMICOS_LOG_FILTER` is unset).
`OMICOS_LOG_FILTER`	Overrides `RUST_LOG` (unavailable in cli mode).
`OMICOS_TUI_THEME` (legacy alias `OPENCLAW_THEME`)	Terminal TUI theme.

10.9 Updates and Miscellaneous

Variable	Default	Description
`OMICOS_UPDATE_FEED_URL`	`https://auth.omicos.cn/admin/api/public/omicos/core/manifest`	Overrides the auto-update manifest address.
`OMICOS_EXA_MCP_URL`	none	Exa MCP endpoint for the web_search tool.
`OMICOS_PLAN_JWKS_URL`	`https://auth.omicos.cn/.well-known/jwks.json`	JWKS address for verifying subscription token signatures.
`OMICOS_PERMISSION_MODE`	none	Trajectory metadata (permission mode).
`OMICOS_ENTRYPOINT`	none	Trajectory metadata (entrypoint identifier).

Platform variables (omicos reads these too): HOME, USERPROFILE (Windows), PATH, SHELL, COMSPEC (Windows), CONDA_DEFAULT_ENV, HOSTNAME, USER.

results matching ""

No results matching ""