Appendix B: Environment Variables

The complete list of environment variables used by the lab: the name, the purpose, the default, and the component that reads it.

Purpose

This appendix is the canonical reference for the lab's environment variables. Every environment variable used by the lab is documented here. The variables are organized by component.

The environment variables are read at process startup and at every configuration reload. The Coordinator respects environment variables that are set in the shell; the framework's defaults apply otherwise.

Conventions

The variables are POSIX-style: uppercase letters and underscores.
The variables are namespaced by component: variables for the Coordinator start with COORDINATOR_; variables for the Scout start with SCOUT_; and so on.
Variables that contain secrets (API keys, tokens) must be set in a way that does not expose them in process listings or shell history. The recommended approach is a .env file that is not committed to version control.

Framework variables

These variables are read by the framework (the underlying runtime, not the lab's components).

Variable	Default	Purpose
`OPENCLAW_CONFIG`	`{workspace-root}/.openclaw/openclaw.json`	Path to the main configuration file.
`OPENCLAW_LOG_LEVEL`	`INFO`	The framework's log level.
`OPENCLAW_LOG_FORMAT`	`json`	The log format (`json` or `text`).
`OPENCLAW_DISABLE_TELEMETRY`	`false`	Whether to disable telemetry.

Coordinator variables

Variable	Default	Purpose
`COORDINATOR_PORT`	`18789`	The Coordinator's HTTP port.
`COORDINATOR_HOST`	`127.0.0.1`	The interface the Coordinator binds to.
`COORDINATOR_MAX_CONCURRENT`	`1`	The maximum number of concurrent requests.
`COORDINATOR_SESSION_TIMEOUT_S`	`3600`	The idle session timeout in seconds.
`COORDINATOR_MEMORY_ENABLED`	`true`	Whether the memory layer is active.
`COORDINATOR_SKILLS_ENABLED`	`true`	Whether the skill loader is active.
`COORDINATOR_PROMPT_PATH`	`{workspace-root}/prompts/coordinator.md`	Path to the Coordinator's system prompt.
`COORDINATOR_MODEL_PRIMARY`	(from config)	Override for the primary model.

Scout variables

The Scout gateway hosts the Research Worker and the Media Agent.

Variable	Default	Purpose
`SCOUT_PORT`	`18790`	The Scout gateway's HTTP port.
`SCOUT_HOST`	`127.0.0.1`	The interface the Scout binds to.
`SCOUT_LOG_DIR`	`~/.openclaw-scout/logs/`	The Scout's log directory.
`SCOUT_MODEL_PRIMARY`	(from config)	Override for the Scout's primary model.
`SCOUT_PROMPT_PATH`	`{workspace-root-scout}/prompts/scout.md`	Path to the Scout's system prompt.

Research Framework variables

These variables are read by the research framework.

Variable	Default	Purpose
`SCOUTE_RESEARCH_ROOT`	`/tmp/scoute/research`	The root directory for research runs.
`SCOUTE_RUNS_DIR`	`/tmp/scoute/runs`	The directory where mission state and artifacts live.
`SCOUTE_LOG_LEVEL`	`INFO`	The framework's log level.
`SCOUTE_PARALLEL_WORKERS`	`3`	The maximum number of parallel phases.
`SCOUTE_DEFAULT_RETRY`	`2`	The default retry count for phases.
`SCOUTE_MAX_BACKOFF_S`	`30`	The maximum backoff between retries.
`SCOUTE_INITIAL_BACKOFF_S`	`1.0`	The initial backoff between retries.
`SCOUTE_BACKOFF_FACTOR`	`2.0`	The backoff multiplier.
`SCOUTE_JOURNAL_MAX_BYTES`	`52428800`	The maximum size of the request journal before rotation.
`SCOUTE_TOKEN_POOL_PATH`	`{framework-root}/config/token_pool_config.json`	Path to the token pool configuration.
`SCOUTE_TOKEN_POOL_STATE_PATH`	`{framework-root}/runtime/token_pool_state.json`	Path to the token pool state.
`SCOUTE_JOURNAL_PATH`	`{framework-root}/runtime/request_journal.jsonl`	Path to the request journal.
`SCOUTE_RETENTION_DAYS`	`30`	The default retention period in days.
`SCOUTE_FAILED_RETENTION_DAYS`	`90`	The retention period for failed missions.
`SCOUTE_CANCELLED_RETENTION_DAYS`	`7`	The retention period for cancelled missions.

Research adapter variables

These variables are read by the research adapters.

Variable	Default	Purpose
`TAVILY_API_KEY`	(none)	The Tavily API key. Required for Tavily adapter.
`GOOGLE_API_KEY`	(none)	The Google Custom Search API key. Required for Google adapter.
`GOOGLE_SEARCH_CX`	(none)	The Google Custom Search engine ID. Required for Google adapter.
`PERPLEXITY_DEFAULT_MODEL`	(provider default)	The default Perplexity model.
`PERPLEXITY_MAX_RETRIES`	`3`	The maximum number of retries for Perplexity requests.
`ADAPTER_RATE_LIMIT_TAVILY`	`60`	The per-minute rate limit for Tavily.
`ADAPTER_RATE_LIMIT_DUCKDUCKGO`	`30`	The per-minute rate limit for DuckDuckGo.
`ADAPTER_RATE_LIMIT_GOOGLE`	`100`	The per-minute rate limit for Google.
`ADAPTER_RATE_LIMIT_YOUTUBE`	`60`	The per-minute rate limit for YouTube.
`ADAPTER_RATE_LIMIT_YT_DLP`	`20`	The per-minute rate limit for yt-dlp.
`ADAPTER_RATE_LIMIT_PERPLEXITY`	`20`	The per-minute rate limit for Perplexity.

Coding sub-agent variables

These variables are read by the coding sub-agent (Codex, in the lab's case).

Variable	Default	Purpose
`CODEX_HOME`	`~/.codex`	The Codex configuration directory.
`CODEX_CONFIG`	`~/.codex/config.toml`	The Codex configuration file.
`CODEX_SANDBOX_MODE`	`workspace-write`	The default sandbox mode.
`CODEX_TIMEOUT_S`	`180`	The default per-invocation timeout.
`CODEX_MAX_ITERATIONS`	`3`	The default maximum iterations.

Web Agent variables

Variable	Default	Purpose
`WEB_AGENT_BROWSER_PROFILE`	`openclaw`	The browser profile to use.
`WEB_AGENT_HEADLESS`	`false`	Whether the browser is headless.
`WEB_AGENT_CDP_PORT`	`18800`	The CDP port.
`WEB_AGENT_SNAPSHOT_MODE`	`aria`	The default ref mode for snapshots.
`WEB_AGENT_SCREENSHOT_QUALITY`	`80`	The screenshot quality (0-100).

Media Agent variables

Variable	Default	Purpose
`MEDIA_AGENT_CHROMECAST_ENABLED`	`true`	Whether the Chromecast backend is enabled.
`MEDIA_AGENT_VLC_BINARY`	`vlc`	The path to the VLC binary.
`MEDIA_AGENT_VLC_DEFAULT_INTF`	`qt`	The default VLC interface.
`MEDIA_AGENT_SELECTION_DEFAULT`	(from config)	The default backend when the rules do not resolve.
`MEDIA_LAB_PORT`	`8765`	The Media Lab Server's HTTP port.
`MEDIA_LAB_OUTPUT_DIR`	`~/.openclaw/media/outbound/`	The Media Lab Server's output directory.

Operational variables

These variables are read by the operational scripts.

Variable	Default	Purpose
`OPS_BACKUP_DESTINATION`	(none)	The backup destination.
`OPS_AUDIT_REPORT_DIR`	`{workspace-root}/security/audits/`	The audit report directory.
`OPS_HEALTH_CHECK_INTERVAL_S`	`86400`	The health check interval in seconds (default 1 day).
`OPS_RETENTION_CHECK_INTERVAL_S`	`86400`	The retention check interval.
`OPS_LOG_ROTATION_INTERVAL_S`	`86400`	The log rotation interval.

Path variables

These variables are paths used by the lab.

Variable	Default	Purpose
`WORKSPACE_ROOT`	(none, required)	The lab's workspace root.
`RESEARCH_ROOT`	`SCOUTE_RESEARCH_ROOT`	The research framework's run root.
`RUNS_DIR`	`SCOUTE_RUNS_DIR`	The research framework's runs directory.
`FRAMEWORK_ROOT`	(none)	The research framework's source root.
`MEMORY_DIR`	`{workspace-root}/memory/`	The daily log directory.
`SKILLS_DIR`	`{workspace-root}/.agents/skills/`	The skills directory.
`TOOLS_DIR`	`{workspace-root}/devclaw-tools/`	The tools directory.
`SESSIONS_DIR`	`{workspace-root}/sessions/`	The sessions directory.
`AUDIT_DIR`	`{workspace-root}/security/audits/`	The audit reports directory.
`INCIDENTS_DIR`	`{workspace-root}/security/incidents/`	The post-mortems directory.

How variables are loaded

The variables are loaded in the following order:

Defaults. The framework's built-in defaults apply if no other source provides a value.
Configuration files. The framework reads the configuration files and overrides the defaults.
Environment variables. The framework reads the environment variables and overrides the configuration files.
Command-line flags. The framework reads the command-line flags and overrides the environment variables.

The order is: defaults < config files < env vars < CLI flags. The most specific wins.

How variables are documented

The variables are documented in this page. When a new variable is added, this page is updated. When a variable is deprecated, this page is updated with the deprecation notice and the migration path.

Sensitive variables

Variables that contain secrets (API keys, tokens) must be handled with care:

They must not be logged.
They must not be written to the request journal.
They must not be committed to version control.
They must be stored in a .env file with owner-only permissions.

The framework's logging layer redacts known sensitive variables. The redaction is based on the variable name; variables whose name contains KEY, TOKEN, SECRET, or PASSWORD are redacted by default.