环境变量

只支持当前代码明确读取的变量。运行时变量优先使用 NEKO_ 前缀；部分网络配置兼容无前缀名称。

端口

变量	默认值	服务
NEKO_MAIN_SERVER_PORT	48911	主 Web/API
NEKO_MEMORY_SERVER_PORT	48912	记忆服务
NEKO_MONITOR_SERVER_PORT	48913	监控服务
NEKO_COMMENTER_SERVER_PORT	48914	评论服务
NEKO_TOOL_SERVER_PORT	48915	Agent/工具服务
NEKO_USER_PLUGIN_SERVER_PORT	48916	用户插件宿主

可选 Monitor 服务

首选变量	默认值	说明
NEKO_MONITOR_HOST	0.0.0.0	Monitor 监听地址（兼容 MONITOR_HOST）。IPv6 带不带方括号均可；:: 只监听 IPv6
NEKO_MONITOR_TOKEN	空	可选的完整权限 token，覆盖除静态模型资源外的所有 Monitor HTTP/WebSocket 路由，包括主服务写入的 /sync*（兼容 MONITOR_TOKEN）
NEKO_MONITOR_VIEWER_TOKEN	空	可选的只读 token，可访问 viewer 页面、接口和 /ws、/subtitle_ws，不能访问 /sync*；仅在设置了 NEKO_MONITOR_TOKEN 时生效（兼容 MONITOR_VIEWER_TOKEN）

token 为空时为兼容旧客户端而保持开放。默认开放监听只应运行在可信局域网；仅本机使用时请将 host 设为 127.0.0.1。不要把 token 写入日志或提交到源码。主服务直接连接 NEKO_MONITOR_HOST（通配地址换成同协议族的回环地址：0.0.0.0 → 127.0.0.1，:: → [::1]），并自动携带 token。

启用 token 后，原生客户端发送 Authorization: Bearer <token>（或 X-Monitor-Token）。浏览器里先用 http://<host>:<port>/<name>?token=<token> 打开一次 viewer：Monitor 会重定向到去掉 token 的地址，并写入 HttpOnly 的 neko_monitor_session_<port> cookie。分享 viewer 链接请用 NEKO_MONITOR_VIEWER_TOKEN：带 NEKO_MONITOR_TOKEN 的链接同时拥有 /sync* 的写权限，拿到链接的人可以向所有观看者注入字幕或聊天内容。

cookie 里是 30 天有效的签名会话而不是 token，只能访问 viewer 路由（不能访问 /sync*）；用它发起的 WebSocket 握手必须来自同一 host 和端口；更换任一 token 后旧会话全部失效。浏览器会把 cookie 发给同一主机的所有端口，所以本机其他服务（主服务、插件宿主）也会收到它，并能在过期前用它读取 Monitor 的 viewer 数据；要立即作废所有会话，请更换 token。TLS 在反向代理终止时，请保留原始 Host 头（nginx：proxy_set_header Host $http_host;，否则实时 WebSocket 会被拒绝），并把代理地址加入 uvicorn 的 FORWARDED_ALLOW_IPS（默认 127.0.0.1），cookie 才会带上 Secure。

Electron 的 port_config.json 位于平台配置目录；显式环境变量优先。

运行时、存储与向量

NEKO_INSTANCE_ID、NEKO_AUTOSTART_CSRF_TOKEN、NEKO_AUTOSTART_ALLOWED_ORIGINS、NEKO_BEHIND_PROXY、NEKO_LOG_LEVEL、NEKO_MERGED 用于运行时。存储根由 launcher 通过 NEKO_STORAGE_SELECTED_ROOT 和 NEKO_STORAGE_ANCHOR_ROOT 传入。

本地向量使用：

• NEKO_VECTORS_ENABLED：默认开启；
• NEKO_VECTORS_QUANTIZATION：auto、int8 或 fp32；

可用内存门槛目前是固定的运行时常量 VECTORS_MIN_RAM_GB = 4.0，没有对应的环境变量覆盖项。

进程模型与单实例

launcher 是前台进程：绝不守护化脱管，属主进程一消失就把整套服务拓扑拆掉；同时用 操作系统文件锁自证唯一，并在锁旁边写出权威运行时记录（pid、实例 ID、协商后的端口）。

变量	默认值	说明
NEKO_OWNER_PID	本进程的父进程	父死守卫要盯的 pid。属主不是直接父进程时才需要设置——例如存储迁移交接产生的下一代 launcher，它的 spawn 者是故意退出的。 若属主打算靠读取 launcher.json 来认领运行时，应当设置本变量：它会成为记录里的 owner_pid，那才是该比对的字段。不要比对 parent_pid——Windows 开发态下 Popen(sys.executable) 启动的是一个再拉起真解释器的壳，parent_pid 指的是那个壳而不是属主（CI 实测；macOS 与 Linux 直接匹配，打包态没有这个壳）。
NEKO_OWNER_RELAUNCH	未设置	1 表示属主会自己负责重启运行时。此时存储迁移重启只干净退出、等待属主拉起，不再自旋出下一代。 Windows 上强烈建议设置：不设时 launcher 会自旋下一代，为了不连带杀死替身必须解除旧 Job 的管理，于是任何活过 cleanup 的进程（插件、MCP、Chromium）都不会被回收。
NEKO_PARENT_DEATH_GUARD	1	设为 0 完全关闭父死守卫。仅用于会重挂父进程的调试器/性能分析工具；关掉之后运行时可能活得比属主久。
NEKO_LAUNCHER_RESTART_HANDOFF	未设置	由上一代 launcher 设在下一代身上，让它等待单实例锁释放，而不是判定"已有实例在跑"。不需要手工设置。
NEKO_RUNTIME_STATE_DIR	按用户的运行时目录	覆盖 launcher.lock 与 launcher.json 的位置。默认 Windows %LOCALAPPDATA%\N.E.K.O.runtime、macOS ~/Library/Application Support/N.E.K.O.runtime、Linux ~/.local/state/N.E.K.O/runtime。Windows 与 macOS 的目录位于 cloudsave 管理的 N.E.K.O 数据根同级，避免原子替换数据根时被仍在持有的单实例锁阻塞，或把该锁对应的 inode 解除链接。Linux 路径刻意不看 XDG_RUNTIME_DIR：该变量在桌面会话里有、在 cron / 裸 SSH / su / system unit / 多数容器里没有，据它推导锁路径会让同一个用户持有两把不同的锁、同时跑起两个运行时。覆盖值会被原样使用、不追加用户后缀，所以必须指向当前用户私有的目录。POSIX 上该目录仍会被校验：属于其他 uid 的目录（或指向它的软链）以 EPERM 拒绝，带 group/world 权限位的目录会被就地 chmod 成 0700；Windows 上两项都不做。被拒绝时按 unknown 处理——launcher 会带告警继续启动，但没有唯一性证明。指到多用户共享目录会破坏单实例证明：Windows 上两个用户会争同一把锁，POSIX 上第二个用户打不开第一个用户的锁文件，会在没有唯一性证明的情况下启动。

运行拓扑

变量	默认值	说明
NEKO_MERGED	源码环境：0；冻结发行包：1	1 让 main、memory、agent 三个 HTTP 服务在同一进程中运行，但保留原有契约；0 保留三个服务进程。不会复用不完整或混合的已有后端；即使原本选择 merged，也会在隔离的回退端口上强制启动三个服务进程。

源码开发、独立服务监管或需要 agent 故障隔离时应使用多进程模式。发行包可通过 NEKO_MERGED=0 立即回退。

通用布尔解析通常接受 1/true/yes/on 与 0/false/no/off；NEKO_MERGED 自身只接受 1/true/yes 与 0/false/no。向量变量也兼容无前缀形式。

插件自启动并发

变量	默认值	说明
NEKO_PLUGIN_AUTOSTART_CONCURRENCY	min(8, max(2, (os.cpu_count() or 4) // 2))	每批自启动中，没有声明依赖的插件的最大并发数。接受 1–64 的整数；设为 1 时串行自启动，每个插件单独获取操作锁。无依赖插件仍先于依赖型插件启动，不恢复旧的全局拓扑及 adapter 优先级顺序。

默认值为 2–8；无法获取逻辑 CPU 数时按 4 个逻辑 CPU 计算，得到并发数 2。 声明了依赖的插件会等独立插件全部启动完成，再按原有拓扑顺序串行启动。 每批并发启动完成后释放操作锁，让排队的插件管理请求可以执行，再进入下一批。 此设置只影响服务启动时的插件自启动，不会为禁用或尚未获批的插件开启自启动， 也不会改变手动启动、停止时保存的偏好。

请在启动 N.E.K.O 前设置变量，修改后重启运行时。无法解析为整数的值使用默认值； 成功解析但超出 1–64 的整数会导致配置校验失败。恢复串行自启动的示例：

$env:NEKO_PLUGIN_AUTOSTART_CONCURRENCY = "1"
uv run python launcher.py

NEKO_PLUGIN_AUTOSTART_CONCURRENCY=1 uv run python launcher.py

仅用于 Docker 初始配置

入口脚本读取 NEKO_CORE_API_KEY、NEKO_CORE_API、NEKO_ASSIST_API，Qwen/OpenAI/GLM/Step/Silicon/Grok/Doubao 的部分 NEKO_ASSIST_API_KEY_*，以及 NEKO_MCP_TOKEN。NEKO_FORCE_ENV_UPDATE 请求重新生成 /app/config/core_config.json。

这些不是源码/桌面运行的通用 API 环境变量。旧 docker/env.template 中未接入入口脚本的模型变量不应依赖。