10. 环境变量完整参考

环境变量可覆盖 omicos 的绝大多数行为。按用途分组列出。基线版本 0.3.29。

通用约定：

空字符串或纯空白视为未设置，回退到默认值。

布尔型开关统一写 1 最稳。多数开关同时接受 true / yes（大小写不敏感），部分还接受 on；其余值一律当作「关」。

URL 类变量结尾不要带斜杠。

环境变量在进程启动时读取。改完要重启 omicos serve / omicos cli 才生效。

10.1 Python / Kernel

变量	默认	说明
`OMICOS_KERNEL_PYTHON`	无	显式指定 Python 解释器路径。注意它排在 `.kernel_choice` 之后，见第 4 章。
`OMICOS_ENV_DIR`	无	指向一个包含 `.venv` 的目录，参与解释器解析。它不改变 `omicos env setup` 的安装位置（那永远是 `<全局目录>/env`）。
`OMICOS_ENV_AUTO`	关	设为 `1` 则自动、非交互地引导环境（约 1.5 GB 下载），不再提示。
`OMICOS_KERNEL_BASE_URL`	无	远程 kernel 的 HTTP 地址。设置后不在本地准备 Python 环境。等价于 `--kernel-base-url`。
`PYTHON`	无	解释器解析链的回退项之一。
`CONDA_PREFIX`	无	当前激活的 conda 环境，解析链回退项。
`VIRTUAL_ENV`	无	当前激活的 venv，解析链回退项。
`UV_INDEX_URL`	无	uv 的包索引地址；被 `omicos env setup --index-url` 覆盖。

10.2 目录与本地存储

变量	默认	说明
`OMICOS_LOCAL_HOME`	`~/.omicos`	全局目录根。同时也决定 `env/`、`auth.json`、`a2a.json` 等的位置。
`OMICOS_USER_HOME`	跟随 `OMICOS_LOCAL_HOME`	「每用户一份」的全局根（认证、订阅令牌、云缓存、长期记忆）。给多工作区启动器用；不设时行为与旧版完全一致。
`OMICOS_RUNTIME_HOME`	无	查找 `auth.json` 时的次级目录（排在 `OMICOS_LOCAL_HOME` 之后、用户主目录之前）。
`OMICOS_WORKSPACE_ROOT`	当前目录	工作区根（会话 / 轨迹的存放位置）。别名 `OMICLAW_WORKSPACE_ROOT`。

10.3 云端地址

变量	默认	说明
`OMICOS_CLOUD_BASE`	`https://auth.omicos.cn`	覆盖认证主机（一般只用于开发 / 预发布）。
`OMICOS_CLOUD_APP_BASE`	由 cloud_base 派生	覆盖网页端主机。罕用。
`OMICOS_SERVER_URL`	无	覆盖服务端 URL，优先于 cloud_base 和登录时保存的值。
`OMICOS_UPSTREAM_BASE_URL`	无	本地 `/api/*` 代理的回退目标，等价于 `--upstream-base-url`。
`OMICOS_CATALOG_DOMAIN`	由 `~/.omicos/active_domain` 决定	覆盖内容域（如 `omics`）。不同域的智能体 / 技能目录物理隔离。

10.4 进程身份

变量	默认	说明
`OMICOS_PROCESS_ID`	`local-<workspace_id>`	覆盖云端进程 id（cli 自起守护进程时自动加 `-cli` 后缀）。
`OMICOS_PROCESS_NAME`	取目录名 / conda 环境名	覆盖进程显示名（cli 自动加 `(cli)`）。
`OMICOS_PROCESS_TOKEN`	无（来自登录）	直接提供进程令牌，跳过 `omicos login`。
`OMICOS_USER_TOKEN`	无（来自登录）	直接提供用户令牌，同样会传给 kernel 子进程。

10.5 LLM Provider / Model

变量	说明
`OMICOS_LLM_PROVIDER`（旧别名 `OMICOS_PROVIDER`）	显式指定 provider id（如 `deepseek`、`openai`）。
`OMICOS_LLM_MODEL`（旧别名 `OMICOS_MODEL`）	显式指定 model id。
`<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。
`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.6 Vision（视觉模型）

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

10.7 缓存目录 / 目录源 / 本地 skill

变量	默认	说明
`OMICOS_MODELS_CACHE_DIR`	`~/.omicos/cloud-models`	模型目录缓存。
`OMICOS_MODELS_CLOUD_URL`	由网页端主机派生	模型目录拉取地址。
`OMICOS_AGENTS_CACHE_DIR`	`~/.omicos/cloud-agents`	智能体缓存。
`OMICOS_AGENTS_CLOUD_URL`	`https://app.omicos.cn/admin/api/public/agents`	智能体拉取地址。
`OMICOS_SKILLS_CACHE_DIR`	`~/.omicos/cloud-skills`	技能缓存。
`OMICOS_SKILLS_CLOUD_URL`	由网页端主机派生	技能拉取地址。
`OMICOS_SKILL_ROOTS`	无	额外的本地 skill 目录（冒号 / 分号分隔），优先级最高。
`OMICOS_MEMORY_CACHE_DIR`	`~/.omicos/memory`	长期记忆的存放目录。
`OMICOS_MEMORY_CLOUD_URL`	`https://auth.omicos.cn/api/memory`	记忆同步地址。
`OMICOS_MCP_CATALOG_URL`	由云端派生	精选 MCP 服务器目录的拉取地址。
`OMICOS_TEMPLATES_DIR`	无	智能体模板目录，优先于云缓存。

注意 OMICOS_MEMORY_CACHE_DIR 指的就是记忆本体（.md 文件）所在的目录，不是另一份缓存副本。

10.8 离线开关 / 同步节奏

变量	默认	说明
`OMICOS_AGENTS_OFFLINE`	关	关闭智能体云同步，只用本地缓存。
`OMICOS_SKILLS_OFFLINE`	关	关闭技能云同步。
`OMICOS_MODELS_OFFLINE`	关	关闭模型目录云同步。
`OMICOS_MEMORY_OFFLINE`	关	关闭记忆云同步。
`OMICOS_MCP_CATALOG_OFFLINE`	关	关闭精选 MCP 目录同步。
`OMICOS_SYNC_DISABLE`	关	关闭轨迹云同步。
`OMICOS_SYNC_LOCAL_ONLY`	无	一个正则，会话 id 命中就不上传（无效正则会被忽略并给出告警）。
`OMICOS_CATALOG_SYNC_SECS`	`600`	智能体 / 技能 / 模型目录的同步间隔。小于 30 的值不会被钳到 30，而是被丢弃并回退到 600。
`OMICOS_MEMORY_SYNC_SECS`	`3600`	记忆的兜底轮询间隔（记忆平时靠云端推送触发同步）。小于 60 的值同样被丢弃回退默认。
`OMICOS_CONV_SYNC_INTERVAL_SEC`	`10`	会话同步间隔。

10.9 日志 / 界面

变量	说明
`RUST_LOG`	标准日志过滤器；`OMICOS_LOG_FILTER` 和 `--log-filter` 未设时的回退。
`OMICOS_LOG_FILTER`	等价于 `--log-filter`（cli 模式下只能用 `RUST_LOG`）。
`OMICOS_TUI_THEME`（旧别名 `OPENCLAW_THEME`）	终端界面主题。

无效的过滤表达式会被静默回退到默认值，只在 stderr 打一行 invalid log filter ...。

10.10 更新与其他

变量	默认	说明
`OMICOS_UPDATE_FEED_URL`	`https://auth.omicos.cn/admin/api/public/omicos/core/manifest`	覆盖自动更新清单地址。
`OMICOS_EXA_MCP_URL`	无	联网搜索工具使用的 Exa MCP 端点。
`OMICOS_PLAN_JWKS_URL`	`https://auth.omicos.cn/.well-known/jwks.json`	订阅令牌验签的 JWKS 地址。
`OMICOS_PERMISSION_MODE`	无	写进轨迹元数据的权限模式标记。
`OMICOS_ENTRYPOINT`	无	写进轨迹元数据的入口标记。
`OMICOS_LISTENING_PORT`	—	这个不是输入，而是 `--report-port` 打印出来的一行输出，供脚本读取实际端口。

平台变量（omicos 也会读取）：HOME、USERPROFILE / HOMEDRIVE / HOMEPATH（Windows）、PATH、SHELL、COMSPEC（Windows）、CONDA_DEFAULT_ENV、HOSTNAME、USER，以及代理相关的 http_proxy / https_proxy / all_proxy / no_proxy。

10.11 怎么确认变量真的生效了

环境变量最常见的问题是「导出了但没生效」。要么写在不被读取的 shell 配置里，要么被更高优先级来源压过。最快验证方式：让 omicos 报告解析结果。

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

预期输出：

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)

如果 kernel python 那行不是你设的值，说明有 .kernel_choice 压在它前面（见第 4 章）。

results matching ""

No results matching ""