10. Environment Variable Reference

Almost every aspect of omicos's behavior can be overridden with environment variables. This chapter groups them by purpose. Baseline version 0.3.29.

General conventions:

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

For boolean switches, 1 is the safest bet. Most also accept true / yes (case-insensitive), and some accept on; any other value is treated as "off".

URL-type variables should not have a trailing slash.

Environment variables are read at process startup. Restart omicos serve / omicos cli after changing one.

10.1 Python / Kernel

Variable	Default	Description
`OMICOS_KERNEL_PYTHON`	none	Explicitly specifies the Python interpreter path. Note it ranks after `.kernel_choice` — see Chapter 4.
`OMICOS_ENV_DIR`	none	Points to a directory that contains a `.venv`, used in interpreter resolution. Doesn't change where `omicos env setup` installs to (always `<global directory>/env`).
`OMICOS_ENV_AUTO`	off	When `1`, bootstraps the environment automatically and non-interactively (about a 1.5 GB download) without prompting.
`OMICOS_KERNEL_BASE_URL`	none	HTTP address of a remote kernel. When set, skips local environment bootstrap. Equivalent to `--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.
`UV_INDEX_URL`	none	uv's package index address; overridden by `omicos env setup --index-url`.

10.2 Directories & Local Storage

Variable	Default	Description
`OMICOS_LOCAL_HOME`	`~/.omicos`	Root of the global directory. Also determines the location of `env/`, `auth.json`, `a2a.json`, and more.
`OMICOS_USER_HOME`	follows `OMICOS_LOCAL_HOME`	The "one per user" global root (auth, subscription tokens, cloud cache, long-term memory). For multi-workspace launchers; behavior is identical to older versions when unset.
`OMICOS_RUNTIME_HOME`	none	A secondary directory for `auth.json` lookup (after `OMICOS_LOCAL_HOME`, before the home directory).
`OMICOS_WORKSPACE_ROOT`	current directory	The workspace root (where sessions / trajectories are stored). Alias `OMICLAW_WORKSPACE_ROOT`.

10.3 Cloud Addresses

Variable	Default	Description
`OMICOS_CLOUD_BASE`	`https://auth.omicos.cn`	Overrides the auth host (generally dev / staging only).
`OMICOS_CLOUD_APP_BASE`	derived from cloud_base	Overrides the web app host. Rarely used.
`OMICOS_SERVER_URL`	none	Overrides the server URL; takes precedence over cloud_base and the value saved at login.
`OMICOS_UPSTREAM_BASE_URL`	none	Fallback target for the local `/api/*` proxy; equivalent to `--upstream-base-url`.
`OMICOS_CATALOG_DOMAIN`	determined by `~/.omicos/active_domain`	Overrides the content domain (e.g. `omics`). Agent / skill catalogs are physically isolated per domain.

10.4 Process Identity

Variable	Default	Description
`OMICOS_PROCESS_ID`	`local-<workspace_id>`	Overrides the cloud process id (cli automatically appends a `-cli` suffix when it starts its own daemon).
`OMICOS_PROCESS_NAME`	directory name / conda env name	Overrides the process display name (cli automatically appends `(cli)`).
`OMICOS_PROCESS_TOKEN`	none (from login)	Supplies the process token directly, bypassing `omicos login`.
`OMICOS_USER_TOKEN`	none (from login)	Supplies the user token directly; also passed to kernel subprocesses.

10.5 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.
`<PROVIDER>_API_KEY`	Each provider's API key, with hyphens in the provider id converted to underscores (e.g. `alibaba-coding-plan` → `ALIBABA_CODING_PLAN_API_KEY`).
`<PROVIDER>_API_BASE`	Each provider's custom endpoint.
`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.
`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 full selection logic, see Chapter 12: Provider & Model Configuration.

10.6 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.7 Cache Directories / Catalog Sources / Local Skills

Variable	Default	Description
`OMICOS_MODELS_CACHE_DIR`	`~/.omicos/cloud-models`	Model catalog cache.
`OMICOS_MODELS_CLOUD_URL`	derived from the web app host	Model catalog fetch address.
`OMICOS_AGENTS_CACHE_DIR`	`~/.omicos/cloud-agents`	Agent cache.
`OMICOS_AGENTS_CLOUD_URL`	`https://app.omicos.cn/admin/api/public/agents`	Agent fetch address.
`OMICOS_SKILLS_CACHE_DIR`	`~/.omicos/cloud-skills`	Skill cache.
`OMICOS_SKILLS_CLOUD_URL`	derived from the web app host	Skill fetch address.
`OMICOS_SKILL_ROOTS`	none	Additional local skill directories (colon- / semicolon-separated), highest priority.
`OMICOS_MEMORY_CACHE_DIR`	`~/.omicos/memory`	Where long-term memory is stored.
`OMICOS_MEMORY_CLOUD_URL`	`https://auth.omicos.cn/api/memory`	Memory sync address.
`OMICOS_MCP_CATALOG_URL`	derived from cloud	Curated MCP server catalog fetch address.
`OMICOS_TEMPLATES_DIR`	none	Agent template directory, takes precedence over the cloud cache.

Note that OMICOS_MEMORY_CACHE_DIR points at the memory files themselves (.md files), not a separate cached copy.

10.8 Offline Switches / Sync Cadence

Variable	Default	Description
`OMICOS_AGENTS_OFFLINE`	off	Disables agent cloud sync; uses the local cache only.
`OMICOS_SKILLS_OFFLINE`	off	Disables skill cloud sync.
`OMICOS_MODELS_OFFLINE`	off	Disables model catalog cloud sync.
`OMICOS_MEMORY_OFFLINE`	off	Disables memory cloud sync.
`OMICOS_MCP_CATALOG_OFFLINE`	off	Disables curated MCP catalog sync.
`OMICOS_SYNC_DISABLE`	off	Disables trajectory cloud sync.
`OMICOS_SYNC_LOCAL_ONLY`	none	A regex; matching session ids are not uploaded (an invalid regex is ignored with a warning).
`OMICOS_CATALOG_SYNC_SECS`	`600`	Sync interval for the agent / skill / model catalog. Values below 30 are not clamped to 30 — they're discarded and fall back to 600.
`OMICOS_MEMORY_SYNC_SECS`	`3600`	Fallback polling interval for memory (memory syncs mainly via cloud push). Values below 60 are likewise discarded and fall back to the default.
`OMICOS_CONV_SYNC_INTERVAL_SEC`	`10`	Session sync interval.

10.9 Logging / UI

Variable	Description
`RUST_LOG`	Standard log filter; the fallback when `OMICOS_LOG_FILTER` and `--log-filter` are unset.
`OMICOS_LOG_FILTER`	Equivalent to `--log-filter` (only `RUST_LOG` works in cli mode).
`OMICOS_TUI_THEME` (legacy alias `OPENCLAW_THEME`)	Terminal UI theme.

An invalid filter expression is silently discarded in favor of the default, with only a single invalid log filter ... line printed to stderr.

10.10 Updates & Other

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 used by 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	Permission-mode marker written into trajectory metadata.
`OMICOS_ENTRYPOINT`	none	Entry-point marker written into trajectory metadata.
`OMICOS_LISTENING_PORT`	—	Not an input — this is a line of output printed by `--report-port`, for scripts to read the actual port.

Platform variables (omicos also reads these): HOME, USERPROFILE / HOMEDRIVE / HOMEPATH (Windows), PATH, SHELL, COMSPEC (Windows), CONDA_DEFAULT_ENV, HOSTNAME, USER, plus the proxy-related http_proxy / https_proxy / all_proxy / no_proxy.

10.11 Confirming a Variable Actually Took Effect

The most common environment-variable problem is "I exported it but it didn't take effect" — either it was written to a shell config file that never gets sourced, or it's being overridden by a higher-priority source. The fastest way to check is to have omicos report what it actually resolved:

export OMICOS_KERNEL_PYTHON=/opt/miniforge3/envs/omicverse/bin/python
omicos env doctor

Expected output:

kernel python : /opt/miniforge3/envs/omicverse/bin/python
omicverse     : present ✓
managed env   : /Users/you/.omicos/env
uv            : /Users/you/.local/bin/uv
package index : pypi (https://pypi.org/simple)

If the kernel python line isn't the value you set, something is overriding it via .kernel_choice (see Chapter 4).

results matching ""

No results matching ""