oclaw/_local/system.env.example

# =============================================================================
# 【仓库约定 — 必读】
#
# 1) 新增「进程环境变量」（代码里新出现 os.getenv / 读取 os.environ）时：
#    - 必须在本文件登记：变量名、含义、典型取值、与前端/管理后台是否有关联。
#    - 提交代码评审时一并更新本模板（复制为 _local/system.env 后本地填写真实值；system.env 勿提交）。
#
# 2) 加载时机：网关入口 modules/http/fastapi_app.py 会调用 load_system_env()，
#    仅加载「_local/system.env」单一路径（platform/config/bootstrap_env.py）。
#    已在操作系统 / 启动脚本里 export 的变量优先级更高（不会被文件覆盖）。
#
# 3) 与 SQLite app_setting / 管理后台的关系：
#    - 多数运行参数可在「管理后台」写入数据库；具体优先级以代码为准（常见：后台优先，
#      仅部分开关保留「环境变量优先」）。
#    - 本节标注「仅存数据库」的项不要指望写在本 env 文件生效（除非代码明确读取 getenv）。
#
# 4) 布尔值约定：未特殊说明时，1/true/yes/on 表示开启；0/false/no/off 表示关闭。
#
# 用法：复制本文件为同目录 system.env，按需取消注释并填写。
#     copy _local\system.env.example _local\system.env
# =============================================================================

# -----------------------------------------------------------------------------
# 一、HTTP 网关监听（uvicorn / FastAPI）
# -----------------------------------------------------------------------------
# AIA_ASSISTANT_GATEWAY_HOST    监听地址，默认 0.0.0.0。
# AIA_ASSISTANT_GATEWAY_PORT    监听端口，默认 8787。
# 【前端】无专门开关；由部署/启动脚本决定。
AIA_ASSISTANT_GATEWAY_HOST=0.0.0.0
AIA_ASSISTANT_GATEWAY_PORT=8787

# AIA_PREWARM_INTERVAL_SECONDS    后台预热任务周期（秒），默认 600，合法范围代码内 clamp。
# 【前端】无。
AIA_PREWARM_INTERVAL_SECONDS=600

# -----------------------------------------------------------------------------
# 二、数据目录、SQLite、密钥与语言（进程级）
# -----------------------------------------------------------------------------
# AIA_ASSISTANT_DB_PATH / OPS_ASSISTANT_DB_PATH    SQLite 库路径（二选一即可），相对路径相对仓库根。
# 【前端】无直接开关；决定连接哪份数据库文件。
AIA_ASSISTANT_DB_PATH=
OPS_ASSISTANT_DB_PATH=

# AIA_ASSISTANT_MASTER_KEY    用于加密迁移密钥等；不设则部分迁移不可用。
# 【前端】管理后台「密钥迁移」相关界面会检测是否配置（提示文案）。
AIA_ASSISTANT_MASTER_KEY=

# AIA_ASSISTANT_PASSWORD / OPS_ASSISTANT_PASSWORD    管理后台登录密码（旧名 OPS_* 兼容）。
# 【前端】登录表单；环境变量常用于自动化部署注入初始密码。
AIA_ASSISTANT_PASSWORD=
OPS_ASSISTANT_PASSWORD=

# AIA_ASSISTANT_LANG    全局默认语言倾向（如 zh），具体会话可被覆盖。
# 【前端】聊天语言一般由会话/UI 控制。
AIA_ASSISTANT_LANG=

# AIA_ASSISTANT_PREMERGE_BACKUP_KEEP / OPS_*    数据库预合并备份保留策略相关。
# AIA_LEGACY_DB_FORCE_PREMERGE / OPS_*    是否强制走遗留库合并逻辑。
AIA_ASSISTANT_PREMERGE_BACKUP_KEEP=
OPS_ASSISTANT_PREMERGE_BACKUP_KEEP=
AIA_LEGACY_DB_FORCE_PREMERGE=
OPS_LEGACY_DB_FORCE_PREMERGE=

# -----------------------------------------------------------------------------
# 三、主配置文件路径（oclaw.json 与别名）
# -----------------------------------------------------------------------------
# AIA_OCLAW_CONFIG_PATH    主配置 JSON（agents、工作区等）；多处 gateway/direct_loop 读取。
# OCLAW_CONFIG_PATH        别名，hooks_runtime / user_config_hooks / gateway server_methods 等。
# 【前端】无单一开关；配置内容决定模型与工作区。
AIA_OCLAW_CONFIG_PATH=
OCLAW_CONFIG_PATH=

# OCLAW_RUNTIME_CONFIG_JSON    内联 JSON 配置片段（调试/容器注入）。
OCLAW_RUNTIME_CONFIG_JSON=

# -----------------------------------------------------------------------------
# 四、工作区与路径守护（工具可读目录）
# -----------------------------------------------------------------------------
# OCLAW_WORKSPACE    逻辑工作区根路径；多处注入 prompt / hooks。
# OCLAW_STATE_DIR    Agent 状态目录，默认 .oclaw。
# OCLAW_SHELL        子进程 shell 覆盖。
# OCLAW_HOME         boot-md / command-logger 等与 OCLAW_STATE_DIR 二选一的别名路径。
OCLAW_WORKSPACE=
OCLAW_STATE_DIR=.oclaw
OCLAW_SHELL=
OCLAW_HOME=

# AIA_WORKSPACE_ROOT / OPS_WORKSPACE_ROOT    路径守护主根覆盖。
# AIA_WORKSPACE_EXTRA_ROOTS / OPS_*    额外允许访问的根，竖线或分隔符依代码。
# 【前端】Admin「用户/会话」里「额外根路径」等与上述 env 合并（见 app.js 文案）。
AIA_WORKSPACE_ROOT=
OPS_WORKSPACE_ROOT=
AIA_WORKSPACE_EXTRA_ROOTS=
OPS_WORKSPACE_EXTRA_ROOTS=

# AIA_MCP_FILESYSTEM_EXTRA_ROOTS / OPS_*    MCP 官方 filesystem 进程额外根路径。
# 【前端】管理后台「网关/MCP」设置项可写库；与此 env 合并。
AIA_MCP_FILESYSTEM_EXTRA_ROOTS=
OPS_MCP_FILESYSTEM_EXTRA_ROOTS=

# -----------------------------------------------------------------------------
# 五、Expert Plan / Agent v2（专家模式计划态）
# -----------------------------------------------------------------------------
# AIA_EXPERT_PLAN_AGENT_V2_ENABLED    是否启用 expert 下的 plan_agent_v2 网关分支。
#    取值 1/true/on：启用；留空或 0/false：否。
#    优先级：SQLite app_setting 非空则优先于 env（见 runtime/plan_agent_v2/switch.py）。
# 【前端】聊天 ⋯ 菜单里「Plan / Agent 版本」选 v2/v1 会通过 /admin/api/chat/user-mode 写入同一键（v2→1，v1→0）。
#    首次在未写入库前仅 env 生效；一旦在菜单里保存过，以库为准。
AIA_EXPERT_PLAN_AGENT_V2_ENABLED=0

# 【仅存数据库 · 写在此处无效】AIA_EXPERT_PLAN_CONFIRM_STRATEGY（strict/auto/off）
#    计划确认策略；由 Admin chat API 写入库；前端 chat.js「确认策略」菜单与会话同步。
# 【仅存数据库 · 写在此处无效】AIA_EXPERT_PLAN_FILE_DIR    计划文件目录。
# 【仅存数据库】会话级 execution_mode / confirm_strategy 走接口元数据与 chat_api，不靠 getenv。

# -----------------------------------------------------------------------------
# 六、LLM 提供商密钥与默认模型（环境兜底；正式账号多在 DB llm_profile）
# -----------------------------------------------------------------------------
OPENAI_API_KEY=
OPENAI_BASE_URL=
OPENAI_MODEL=
OPENAI_EMBEDDING_MODEL=

ANTHROPIC_API_KEY=
ANTHROPIC_BASE_URL=
ANTHROPIC_MODEL=

GOOGLE_API_KEY=
GEMINI_API_KEY=

OLLAMA_BASE_URL=
OPENAI_BASE_URL_OLLAMA=
OLLAMA_MODEL=

DASHSCOPE_API_KEY=
DASHSCOPE_BASE_HTTP_API_URL=

# AIA_ASSISTANT_MODE    全局助手模式字符串（与 chat_models 等协调）；测试里可用 OPS_ASSISTANT_MODE。
AIA_ASSISTANT_MODE=

# --- OpenAI 兼容「思考」字段 --- 
AIA_LLM_THINKING_FORCE_DISABLED=
AIA_LLM_THINKING_FORCE_ENABLED=
AIA_LLM_THINKING_DISABLED=

# --- Gemini SSE ---
AIA_GEMINI_THINKING=
AIA_GEMINI_THINKING_LEVEL=
AIA_GEMINI_THINKING_BUDGET=

# -----------------------------------------------------------------------------
# 七、直连循环（direct_loop）：空回复、工具结果长度、trace
# -----------------------------------------------------------------------------
AIA_IMAGE_TOOL_RESULT_REPLAY_CAP_CHARS=
AIA_VIDEO_TOOL_RESULT_REPLAY_CAP_CHARS=
AIA_TOOL_WIRE_FROZEN_ON_STARTUP=
AIA_TRACE_TOOL_EXPOSURE_PLAN=

AIA_EMPTY_ASSISTANT_RETRY_MAX=
AIA_EMPTY_ASSISTANT_RETRY_DELAY_MS=
AIA_EMPTY_ASSISTANT_RETRY_TOTAL_TIMEOUT_MS=

# 【管理后台】部分同名项可在运维设置里配置（如 AIA_SSE_QUEUE_MAXSIZE）；chat_api 读 env 作兜底。
AIA_SSE_QUEUE_MAXSIZE=

# -----------------------------------------------------------------------------
# 八、工具清单 / MCP / 插件 / 高风险工具可见性
# -----------------------------------------------------------------------------
AIA_SKILL_TOOLCALL_ENABLED=
AIA_PUBLIC_TOOLS_ALLOW_HIGH=
AIA_ENABLE_MCP_TOOLS=1
OPS_ENABLE_MCP_TOOLS=
AIA_PLUGIN_TOOLS_ENABLED=1
AIA_PLUGIN_TOOL_IDS=
AIA_ENABLE_RUN_COMMAND=
AIA_LOCAL_ADAPTER_STARTUP_SELF_CHECK=1

# AIA_MCP_SPECIALISTS    允许使用 MCP 的专家角色列表，逗号分隔。
AIA_MCP_SPECIALISTS=generalist,manager

# AIA_MCP_ENV_ALLOWLIST    允许注入 MCP 子进程的环境变量名列表。
# 【前端】管理后台可维护同名设置。
AIA_MCP_ENV_ALLOWLIST=

# AIA_MCP_SQLITE_COMMAND    表格附件走 MCP 时的 sqlite 命令路径覆盖。
AIA_TABULAR_USE_MCP=
AIA_TABULAR_SQL_TIMEOUT_MS=

# -----------------------------------------------------------------------------
# 九、工具运行时：上下文长度、日志、历史摘要
# -----------------------------------------------------------------------------
AIA_TOOL_LLM_MESSAGE_MAX_CHARS=
AIA_TOOL_HISTORY_SUMMARY_AFTER_CALLS=
AIA_TOOL_LOG_MAX_CHARS=

# -----------------------------------------------------------------------------
# 十、Skills 根目录与注入
# -----------------------------------------------------------------------------
AIA_SKILLS_ROOT=
AIA_DISABLE_LEGACY_SKILLS_FALLBACK=
AIA_SKILLS_PROMPT_IN_SYSTEM=
AIA_SKILLS_PROMPT_MAX_CHARS=18000

# AIA_SKILL_ROLE_BINDING_ENABLED / AIA_SKILL_ROLE_BINDING_MANAGER_INHERIT
#    技能与角色绑定；env 优先于 store（见 runtime/skill_role_binding.py）。
# 【前端】高级设置里可操作同名开关（app.js 文案引用）。
AIA_SKILL_ROLE_BINDING_ENABLED=
AIA_SKILL_ROLE_BINDING_MANAGER_INHERIT=

# --- ClawHub ---
AIA_CLAWHUB_SITE=
AIA_CLAWHUB_REGISTRY=
AIA_CLAWHUB_TOKEN=
AIA_CLAWHUB_API_BASE=
CLAWHUB_SITE=
CLAWHUB_REGISTRY=
CLAWHUB_TOKEN=

# --- Cocoloop ---
AIA_COCOLOOP_API_BASE=
COCOLOOP_API_BASE=

# -----------------------------------------------------------------------------
# 十一、附件 ACL、体积上限
# -----------------------------------------------------------------------------
AIA_ATTACHMENT_ACL_STRICT=
AIA_MAX_ATTACHMENT_BYTES=

# -----------------------------------------------------------------------------
# 十二、路由与运行时日志
# -----------------------------------------------------------------------------
AIA_OCLAW_ROUTER_MODE=
AIA_RUNTIME_LOG_DIR=

# -----------------------------------------------------------------------------
# 十三、RAG / 记忆
# -----------------------------------------------------------------------------
AIA_RAG_MODE=
AIA_RAG_EMBEDDING_MODE=
AIA_MEMORY_EPISODIC_TTL_DAYS=
MEMORY_EPISODIC_TTL_DAYS=

# -----------------------------------------------------------------------------
# 十四、WebSocket（/ws）
# -----------------------------------------------------------------------------
OCLAW_WS_REQUIRE_AUTH=1
OCLAW_WS_ALLOWED_ORIGINS=
OCLAW_WS_RATE_LIMIT_WINDOW_MS=60000
OCLAW_WS_RATE_LIMIT_CONN_PER_WINDOW=120
OCLAW_WS_RATE_LIMIT_IP_PER_WINDOW=240
OCLAW_WS_RATE_LIMIT_USER_PER_WINDOW=360
OCLAW_WS_SEND_QUEUE_MAX_MESSAGES=256
OCLAW_WS_SEND_QUEUE_MAX_BYTES=
OCLAW_WS_EVENT_REPLAY_MAX=256

# -----------------------------------------------------------------------------
# 十五、模型请求：工具 JSON、Replay 策略、Agent 消息回放
# -----------------------------------------------------------------------------
AIA_OPENAI_TOOLS_MAX_JSON_CHARS=
AIA_SHRINK_OPENAI_TOOLS=
AIA_SHRINK_OPENAI_TOOLS_MAX_JSON=

AIA_REPLAY_POLICY_ENABLED=
AIA_REPLAY_REPAIR_TOOL_PAIRING=
AIA_TOOL_CALL_ID_MAX_LEN=

AIA_REPLAY_TOOL_FULL_ROUNDS=
AIA_REPLAY_REASONING_SIGNATURE_POLICY=

# -----------------------------------------------------------------------------
# 十六、图片 / 音视频工具（OpenAI、DashScope）
# -----------------------------------------------------------------------------
OPENAI_IMAGE_MODEL=
OPENAI_AUDIO_TRANSCRIPTION_MODEL=

AIA_IMAGE_MODEL=
AIA_IMAGE_BASE_URL=
AIA_IMAGE_API_KEY=
AIA_IMAGE_CHAT_ENDPOINT=

DASHSCOPE_IMAGE_N=
DASHSCOPE_IMAGE_WATERMARK=
DASHSCOPE_IMAGE_NEGATIVE_PROMPT=
DASHSCOPE_IMAGE_PROMPT_EXTEND=
DASHSCOPE_IMAGE_SIZE=
DASHSCOPE_IMAGE_MODEL=

AIA_IMAGE_RETRIES=
AIA_IMAGE_RETRY_BACKOFF_SEC=
AIA_IMAGE_STATUS_RETRIES=
AIA_IMAGE_STATUS_RETRY_BACKOFF_SEC=

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=

# -----------------------------------------------------------------------------
# 十七、Web 搜索（official Bing/Google HTTP API）
# -----------------------------------------------------------------------------
OCLAW_WEB_SEARCH_OFFICIAL_API_KEY=
OCLAW_WEB_SEARCH_OFFICIAL_API_ENDPOINT=
OCLAW_WEB_SEARCH_BING_API_KEY=
OCLAW_WEB_SEARCH_BING_API_ENDPOINT=
OCLAW_WEB_SEARCH_GOOGLE_API_KEY=
OCLAW_WEB_SEARCH_GOOGLE_CSE_ID=
OCLAW_WEB_SEARCH_GOOGLE_API_ENDPOINT=

# -----------------------------------------------------------------------------
# 十八、微信 / 企业微信 长连接 Runner（interfaces/channels/wecom）
# -----------------------------------------------------------------------------
WECOM_LONGCONN_MODE=
WECOM_LONGCONN_INTERVAL_SEC=
WECOM_LONGCONN_WS_URL=
WECOM_LONGCONN_PULL_URL=
WECOM_LONGCONN_SEND_RETRY=
WECOM_LONGCONN_MOCK_TEXT=
WECOM_LONGCONN_DELIVER_OUTBOUND=
WECOM_LONGCONN_USE_RESPONSE_URL=
AIA_WECOM_LONGCONN_WORKERS=
WECOM_LONGCONN_WORKERS=
AIA_WECOM_LONGCONN_INBOUND_QUEUE_MAXSIZE=
WECOM_LONGCONN_INBOUND_QUEUE_MAXSIZE=

# -----------------------------------------------------------------------------
# 十九、Wiki Worker、杂项、对外版本号
# -----------------------------------------------------------------------------
AIA_WIKI_WORKER_POLL_SECONDS=4
AIA_WIKI_WORKER_ID=wiki-worker-main

AIA_ILINK_BOT_TOKEN=

OCLAW_VERSION=0.1

# runtime/operations/main.py 启动时可写入：
# AIA_ASSISTANT_GATEWAY_HOST / PORT（已由第一节覆盖）

# -----------------------------------------------------------------------------
# 二十、Skill 内第三方（示例：Tavily）
# -----------------------------------------------------------------------------
TAVILY_API_KEY=

# -----------------------------------------------------------------------------
# 二十一、下列 keys 常在「管理后台 → 网关/运维」中配置（SQLite），与 env 二选一或叠加
#    若代码未 getenv，请使用后台保存；不要仅写在本文件。
# -----------------------------------------------------------------------------
# AIA_TURN_MAX_CONTEXT_MESSAGES / AIA_TURN_MAX_TOOL_ROUNDS / AIA_TURN_MAX_TOOL_WORKERS
# AIA_OCLAW_MAX_ATTEMPTS
# AIA_ENABLE_PLUGIN_TOOLS（注意与 AIA_PLUGIN_TOOLS_ENABLED 命名区分，以后台为准）
# AIA_TOOL_CONTEXT_TRUNCATE_ENABLED
# AIA_CHAT_SHOW_TTFT_DEBUG
# AIA_SKILL_RUNTIME_ENABLED / AIA_SKILL_AUTO_INSTALL_ENABLED
# AIA_OCLAW_RETRYABLE_ERROR_CODES / AIA_OCLAW_RETRY_CODES_STRICT_MODE
# rag_mode、embedding 相关部分亦在后台 memory/RAG 页
# 【前端】多数上述项在 Admin 设置表单中有对应勾选或输入框。