10. 环境变量完整参考

omicos 的几乎所有行为都可以用环境变量覆盖。本章按用途分组，给出全部环境变量。

通用解析约定（对所有变量生效）：

  • 空字符串或纯空白视为未设置，会回退到默认值。
  • 布尔型开关只接受 1 / true / yes / on（大小写不敏感），其余值当作"关"。
  • URL 类变量会自动去掉结尾的斜杠 /。

10.1 Python / Kernel

变量 默认 说明
OMICOS_KERNEL_PYTHON 无 显式指定 Python 解释器绝对路径，最高优先级。仅启动时检测，改后需重启。
OMICOS_ENV_DIR ~/.omicos/env omicos 管理的 Python 环境目录（其下找 .venv）。
OMICOS_ENV_AUTO 关 设为真则非交互自动引导环境（约 1.5 GB 下载），不再提示。
OMICOS_KERNEL_BASE_URL 无 远程 IPython kernel 的 HTTP 地址。设置后跳过本地环境引导，覆盖 --kernel-base-url。
PYTHON 无 解释器解析链的回退项之一。
CONDA_PREFIX 无 当前激活的 conda 环境，解析链回退项。
VIRTUAL_ENV 无 当前激活的 venv，解析链回退项。

解释器解析优先级见第 4 章。

10.2 云端地址

变量 默认 说明
OMICOS_CLOUD_BASE https://auth.omicos.cn 覆盖 auth 主机（一般只用于 dev/staging）。必须无结尾斜杠。
OMICOS_CLOUD_APP_BASE 由 cloud_base 派生 覆盖 app（SPA）主机。罕用，多为 staging。
OMICOS_SERVER_URL 无 覆盖 server URL（dev/staging），优先于 cloud_base 和登录值。
OMICOS_UPSTREAM_BASE_URL 无 上游云控制面（同步 / 中继），等价于 --upstream-base-url。
OMICOS_LOCAL_HOME ~/ 覆盖本地数据根（凭证、workspace_id 的位置）。
OMICOS_RUNTIME_HOME 无 auth.json 查找的次级 home（在 LOCAL_HOME 之后、HOME 之前）。
OMICOS_WORKSPACE_ROOT 当前目录 工作区根（会话 / 轨迹存储位置）。别名 OMICLAW_WORKSPACE_ROOT。

云端地址解析的完整优先级链：OMICOS_UPSTREAM_BASE_URL > --upstream-base-url > 登录时的 user.cloud_base > 默认 https://auth.omicos.cn。

10.3 进程身份

变量 默认 说明
OMICOS_PROCESS_ID local-<workspace_id> 覆盖云端进程 id（cli 模式自动加 -cli 后缀）。
OMICOS_PROCESS_NAME 取目录 / conda 名 覆盖进程显示名（cli 自动加 (cli)）。
OMICOS_PROCESS_TOKEN 无（来自登录） 覆盖云认证 token（一次性，不持久化）。

10.4 LLM Provider / Model

变量 说明
OMICOS_LLM_PROVIDER（旧别名 OMICOS_PROVIDER） 显式指定 provider id（如 deepseek、openai）。
OMICOS_LLM_MODEL（旧别名 OMICOS_MODEL） 显式指定 model id（如 deepseek-v4-flash）。
<PROVIDER>_API_KEY 各 provider 的 API key，provider id 中的连字符转下划线（如 alibaba-coding-plan → ALIBABA_CODING_PLAN_API_KEY）。
<PROVIDER>_API_BASE 各 provider 的自定义 endpoint。
OPENAI_API_KEY / DEEPSEEK_API_KEY / MINIMAX_API_KEY 常见 provider 的具体 key 名。
CUSTOM_OPENAI_API_BASE 自定义 OpenAI 兼容端点，默认 http://127.0.0.1:8000/v1。
CUSTOM_OPENAI_API_KEY 自定义 OpenAI key（回退 OPENAI_API_KEY）。
CUSTOM_ANTHROPIC_API_KEY 自定义 Anthropic 兼容 key（原生 anthropic 未实现，须走 custom）。
CODEX_CHATGPT_BASE_URL Codex OAuth 端点，默认 https://chatgpt.com/backend-api。
GEMINI_CODE_ASSIST_BASE_URL Gemini OAuth 端点，默认 https://cloudcode-pa.googleapis.com。

选择逻辑详见第 12 章：Provider 与模型配置。

10.5 Vision（视觉模型）

变量 说明
OMICOS_VISION_MODEL 视觉模型 id（独立于主聊天模型）。
OMICOS_VISION_BASE_URL 视觉模型端点。
OMICOS_VISION_API_KEY 视觉模型 API key。

10.6 缓存目录 / 云 URL / 本地 skill

变量 默认 说明
OMICOS_MODELS_CACHE_DIR ~/.omicos/cloud-models 模型 catalog 缓存目录。
OMICOS_MODELS_CLOUD_URL 由 app_base 派生 模型 catalog 拉取地址。
OMICOS_AGENTS_CACHE_DIR ~/.omicos/cloud-agents agent 缓存目录。
OMICOS_AGENTS_CLOUD_URL 由 app_base 派生 agent 拉取地址。
OMICOS_SKILLS_CACHE_DIR ~/.omicos/cloud-skills skill 缓存目录。
OMICOS_SKILLS_CLOUD_URL 由 app_base 派生 skill 拉取地址。
OMICOS_SKILL_ROOTS 无 额外的本地 skill 目录（冒号 / 分号分隔）。
OMICOS_MEMORY_CACHE_DIR ~/.omicos/cloud-memory memory 缓存目录。
OMICOS_MEMORY_CLOUD_URL 由 cloud_base 派生 memory 同步地址。
OMICOS_TEMPLATES_DIR 内置 agent 模板目录回退。

10.7 离线开关 / 同步控制

变量 说明
OMICOS_AGENTS_OFFLINE 关闭 agent 云同步，只用本地缓存。
OMICOS_SKILLS_OFFLINE 关闭 skill 云同步。
OMICOS_MODELS_OFFLINE 关闭 model catalog 云同步。
OMICOS_MEMORY_OFFLINE 关闭 memory 云同步。
OMICOS_SYNC_DISABLE 关闭轨迹（trajectory）云同步。
OMICOS_SYNC_LOCAL_ONLY 用正则排除指定会话不上传（无效正则被忽略）。
OMICOS_CATALOG_SYNC_SECS agent/skill/model 同步间隔，默认 600 秒。小于 30 的值不会被钳制到 30，而是被丢弃并回退到 600 默认值。
OMICOS_CONV_SYNC_INTERVAL_SEC 会话同步间隔，默认 10 秒（最小 1 秒；非数值回退默认）。

10.8 日志 / 主题

变量 说明
RUST_LOG 标准 tracing 过滤器（OMICOS_LOG_FILTER 未设时的回退）。
OMICOS_LOG_FILTER 覆盖 RUST_LOG（cli 模式不可用）。
OMICOS_TUI_THEME（旧别名 OPENCLAW_THEME） 终端 TUI 主题。

10.9 更新与其他

变量 默认 说明
OMICOS_UPDATE_FEED_URL https://auth.omicos.cn/admin/api/public/omicos/core/manifest 覆盖自动更新清单地址。
OMICOS_EXA_MCP_URL 无 web_search 工具的 Exa MCP 端点。
OMICOS_PLAN_JWKS_URL https://auth.omicos.cn/.well-known/jwks.json 订阅 token 验签的 JWKS 地址。
OMICOS_PERMISSION_MODE 无 轨迹元数据（权限模式）。
OMICOS_ENTRYPOINT 无 轨迹元数据（入口标识）。

平台变量（omicos 也会读取）：HOME、USERPROFILE（Windows）、PATH、SHELL、COMSPEC（Windows）、CONDA_DEFAULT_ENV、HOSTNAME、USER。

results matching ""

    No results matching ""