oliver
7253f6795d
本次将握手鉴权、Origin 校验、限流、重连补偿、发送背压与观测字段打通，同时修复 gateway 异常路径与备份清理兼容问题，确保工具历史压缩语义一致并恢复全量测试通过。 Made-with: Cursor
20 KiB
环境变量总览（AIA）
本项目统一使用 AIA_* 前缀环境变量。本文档是唯一维护入口，用于说明变量用途、默认值与生效位置。
发布级变更记录见：oclaw/docs/ENVIRONMENT_VARIABLES_CHANGELOG.md。
维护规则
- 新增环境变量时，必须同步更新本文档。
- 变量命名统一：
AIA_<模块>_<含义>。 - 若变量已可在 Admin 配置，优先使用 Admin，环境变量作为启动默认值/兜底。
- 删除变量时，请同时更新：
- 本文档
README.md的示例- 示例环境文件（如
data/mcp_local.env.example）
核心与调度
-
AIA_ASSISTANT_MODE- 默认：空（代码内决定默认模式）
- 作用：助手模式选择
- 生效：
oclaw/platform/llm/chat_models.py,oclaw/runtime/agents/factory.py
-
AIA_MANAGER_DECISION_MODE- 默认：空
- 作用：Legacy（已断开）：旧 manager 决策模式（如
rule） - 说明：oclaw runtime 默认不再走
CompositeOpsAgent的 manager 决策；该变量仅保留以便后续接回 legacy - 生效：
oclaw/runtime/agents/manager_agent.py（仅 legacy 链路）
-
AIA_TURN_MAX_TOOL_WORKERS- 默认：
8 - 作用：单轮工具并发上限
- 生效：
oclaw/oclaw_runtime/gateway.py,oclaw/oclaw_runtime/direct_loop.py
- 默认：
-
AIA_TURN_MAX_TOOL_ROUNDS- 默认：
8 - 作用：工具循环轮次上限
- 生效：
oclaw/oclaw_runtime/gateway.py,oclaw/oclaw_runtime/direct_loop.py
- 默认：
-
AIA_TURN_MAX_CONTEXT_MESSAGES- 默认：
80 - 作用：上下文消息上限
- 生效：
oclaw/oclaw_runtime/gateway.py,oclaw/oclaw_runtime/direct_loop.py
- 默认：
-
oclaw async queue/worker（
router -> oclaw_task -> worker）- 当前版本无独立环境变量；复用以上
AIA_TURN_MAX_*配置控制 direct loop 执行上限 - 生效：
oclaw/oclaw_runtime/gateway.py,oclaw/oclaw_runtime/worker.py
- 当前版本无独立环境变量；复用以上
-
AIA_PROMPT_FRONTMATTER_STRICT- 默认：
0 - 作用：
1时SKILL.md/oclaw/prompts/*.md的 frontmatter 必须为可解析 YAML；解析失败直接报错（不回落旧版行解析） - 生效：
oclaw/prompts/frontmatter.py,oclaw/prompts/loader.py,oclaw/oclaw_runtime/skills.py
- 默认：
-
AIA_SKILLS_PROMPT_IN_SYSTEM- 默认：
1（开启；仅当技能运行时启用） - 作用：是否在 system prompt 末尾附加 oclaw 风格的
<available_skills>目录块（与原生tools并存） - 说明：设为
0可关闭以降低 token；AdminAIA_SKILL_RUNTIME_ENABLED关闭时本块不生成 - 生效：
oclaw/oclaw_runtime/skills_prompt.py,oclaw/oclaw_runtime/direct_loop.py
- 默认：
-
AIA_SKILLS_PROMPT_MAX_CHARS- 默认：
18000 - 作用：技能目录 XML 块最大字符数（超出则从列表尾部丢弃条目）
- 生效：
oclaw/oclaw_runtime/skills_prompt.py
- 默认：
-
AIA_SKILL_DISABLED_NAMES- 默认：空数组（
[]） - 作用：按技能名禁用模型可见/可执行技能（JSON 数组字符串，例如
["skill_a","skill_b"]） - 说明：禁用后同时影响 manifest/prompt 渲染与 direct loop 工具暴露
- 生效：
oclaw/oclaw_runtime/skills.py,oclaw/oclaw_runtime/skills_prompt.py,oclaw/oclaw_runtime/skill_installer.py
- 默认：空数组（
-
AIA_SKILL_AUTO_INSTALL_ENABLED- 默认：
1 - 作用：是否允许自动安装 skill（admin auto-install / retry-install(auto)）
- 说明：关闭后返回
auto_install_disabled，并标记为不可重试 - 生效：
oclaw/oclaw_runtime/skill_installer.py,oclaw/interfaces/admin/skills_api.py
- 默认：
-
AIA_OCLAW_RETRYABLE_ERROR_CODES- 默认：
provider_timeout,provider_rate_limited,provider_temporary_error,provider_unavailable,context_overflow,tool_execution_failed - 作用：Agent Core run 外环的错误重试白名单（逗号分隔）
- 说明：仅当 attempt 返回
status=retry且error_code命中该白名单时才进入下一次 attempt；未知 code 默认在 Admin 保存时会被过滤并告警 - 补充：
relay_envelope_invalid、relay_envelope_unsupported_version属于输入契约错误，运行时固定按 non-retryable 处理（即使被误加入白名单也不会进入重试链） - 生效：
oclaw/oclaw_runtime/agent_core_run.py
- 默认：
-
AIA_OCLAW_ROUTER_MODE- 默认：
rule - 取值：
rule（启发式）或llm_json（由当前 executor 的model.chat产出{mode,reason}JSON；解析失败则回落rule） - 说明：亦可通过同名环境变量覆盖；提示词见
oclaw/prompts_runtime/router/decide_route.md - 生效：
oclaw/oclaw_runtime/router.py,oclaw/oclaw_runtime/gateway.py
- 默认：
-
oclaw trace 字段与
event_type↔oc_stage对照见oclaw/docs/oclaw-trace-taxonomy.md -
Skill 安装错误码与重试建议、trace 排障路径见
oclaw/docs/oclaw-skill-troubleshooting.md -
Relay 文件指针（含 ACP 父子 run）错误码与排障见
oclaw/docs/oclaw-skill-troubleshooting.md的“Relay 文件指针排障” -
AIA_OCLAW_RETRY_CODES_STRICT_MODE- 默认：
0 - 作用：控制 Admin 保存
AIA_OCLAW_RETRYABLE_ERROR_CODES时的未知 code 行为 - 说明：
0=过滤并告警；1=直接拒绝保存（HTTP 400） - 生效：
oclaw/interfaces/admin/routes.py,oclaw/interfaces/admin/static/app.js
- 默认：
-
AIA_TOOL_ENFORCED_RETRY_MODE- 默认：
first_round_only - 作用：Legacy（已断开）：工具必需场景下的强制重试策略
- 生效：仅 legacy 链路（保留占位，暂不影响 oclaw）
- 默认：
-
AIA_TOOL_LOOP_STATE_MACHINE- 默认：
1 - 作用：Legacy（已断开）：工具循环状态机开关
- 生效：仅 legacy 链路（保留占位，暂不影响 oclaw）
- 默认：
-
AIA_TOOL_SIGNATURE_BUDGET- 默认：
2 - 作用：Legacy（已断开）：同签名工具调用预算
- 生效：仅 legacy 链路（保留占位，暂不影响 oclaw）
- 默认：
-
AIA_OCLAW_ALLOW_LEGACY_FALLBACK- 默认：
0（关闭） - 作用：oclaw 执行失败时，是否允许回退到 legacy
executor.run_turn(...) - 说明：默认 fail-closed（不回退），避免无意中触发旧 manager/runner
- 生效：
oclaw/oclaw_runtime/gateway.py,oclaw/runtime/agents/specialist_agent.py
- 默认：
LLM 传输与 replay（OpenAI 兼容）
思路参考 oclaw（MIT）对 openai-completions 的 transcript 策略：在请求前修复/规范化 tool_calls[].id 与 role=tool 的 tool_call_id，减少网关 400（空 id、断链、非法字符）。
-
AIA_REPLAY_POLICY_ENABLED- 默认：
1（启用） - 作用：是否启用发送前 replay 规范化（修复孤儿 tool 引用 + 重写 tool id）
- 生效：
oclaw/platform/llm/replay_policy.py,oclaw/platform/llm/chat_models.py
- 默认：
-
AIA_REPLAY_REPAIR_TOOL_PAIRING- 默认：
1 - 作用：是否先剥离「assistant 中不存在的 tool_call_id」的 tool 消息上的 id（再执行 id 重写）
- 生效：
oclaw/platform/llm/replay_policy.py
- 默认：
-
AIA_TOOL_CALL_ID_MAX_LEN- 默认：
40 - 作用：重写后的 tool_call_id 最大长度（适配多数 OpenAI 兼容网关）
- 生效：
oclaw/platform/llm/tool_call_id.py
- 默认：
-
AIA_PROMPT_TOOL_FALLBACK- 默认：
1 - 作用：原生 tools 失败并进入 prompt-tool 降级时，是否向 system 注入 tools JSON；设为
0则仅剥离 tool 结构、不注入工具清单 - 生效：
oclaw/platform/llm/chat_models.py
- 默认：
-
AIA_NATIVE_TOOLS_DENYLIST_HOSTS- 默认：空（无静态名单；另有进程内按错误动态记录的
(host, model)缓存） - 作用：可选的 host 子串黑名单，强制走 prompt-tool 模式
- 生效：
oclaw/platform/llm/chat_models.py
- 默认：空（无静态名单；另有进程内按错误动态记录的
工具执行与安全
-
AIA_DISABLE_TOOL_CONFIRM- 默认：
0 - 作用：Legacy（已断开）：是否禁用高风险工具确认
- 说明：oclaw 工具执行已移除执行时确认策略；该变量保留以便后续接回 legacy
- 生效：仅 legacy 链路（保留占位）
- 默认：
-
AIA_ENABLE_MCP_TOOLS- 默认：
1 - 作用：启用 MCP 工具
- 生效：
oclaw/tools/catalog.py
- 默认：
-
AIA_ENABLE_PLUGIN_TOOLS- 默认：
0 - 作用：启用插件工具
- 生效：
oclaw/tools/catalog.py
- 默认：
-
AIA_ENABLE_RUN_COMMAND- 默认：
0 - 作用：允许高风险
run_command工具 - 生效：
oclaw/tools/catalog.py,oclaw/tools/experts/workspace/shell_tools.py
- 默认：
-
AIA_TOOL_LLM_MESSAGE_MAX_CHARS- 默认：
0（不限制） - 作用：工具结果写回 LLM 的消息长度上限
- 说明：
0表示不做限制（不推荐，可能触发部分网关的单条消息上限 400） - 生效：
oclaw/runtime/chat/tool_runtime.py - 观测：管理端聊天流
tool_use_result事件会携带llm_wire.{truncated_for_llm,max_chars,result_bytes,result_for_llm_bytes,truncate_ms}
- 默认：
-
AIA_TOOL_LOG_MAX_CHARS- 默认：
200000 - 作用：
tool_log中 args/result 截断上限 - 生效：
oclaw/platform/persistence/sqlite_store.py
- 默认：
-
AIA_IMAGE_TOOL_RESULT_REPLAY_CAP_CHARS- 默认：
4000 - 作用：限制历史轮次中
query_image_attachment（OCR/描述）结果回放到模型上下文时的text长度上限 - 范围：
600..30000 - 优先级：DB setting（同名） > 环境变量 >
oclaw.json(plugins.entries.memory-wiki.auto.attachments.tabular.image_result_replay_cap_chars) > 默认值 - 生效：
oclaw/runtime/direct_loop.py
- 默认：
-
AIA_VIDEO_TOOL_RESULT_REPLAY_CAP_CHARS- 默认：
4000 - 作用：限制历史轮次中
query_video_attachment（task=transcript）结果回放到模型上下文时的text长度上限 - 范围：
600..30000 - 优先级：DB setting（同名） > 环境变量 >
oclaw.json(plugins.entries.memory-wiki.auto.attachments.tabular.video_result_replay_cap_chars) > 默认值 - 生效：
oclaw/runtime/direct_loop.py
- 默认：
-
video_transcript_chunk_size/video_transcript_chunk_overlap（oclaw.json配置项）- 默认：
1600/200 - 作用：
query_video_attachment(task=transcript)落库转写文本时的默认分块参数（可被工具入参覆盖） - 范围：
size: 1..8000，overlap: 1..4000（实际使用会约束 overlap < size） - 路径：
plugins.entries.memory-wiki.auto.attachments.tabular - 生效：
oclaw/runtime/tools/experts/generalist/video_query.py
- 默认：
-
archive_max_depth/archive_max_file_count/archive_max_entry_bytes/archive_max_total_uncompressed_bytes（oclaw.json配置项）- 默认：
2/200/10485760/52428800 - 作用：统一
archive_processor（zip/tar/tgz/gz）安全预算：限制嵌套深度、文件数量、单文件解压大小、总解压大小 - 路径：
plugins.entries.memory-wiki.auto.attachments.tabular - 生效：
oclaw/platform/files/archive_processor.py,oclaw/platform/files/file_attachments.py - 错误码（工具/上下文可见）：
archive_unsupported_format,archive_path_traversal,archive_max_depth_exceeded,archive_max_file_count_exceeded,archive_max_entry_bytes_exceeded,archive_max_total_uncompressed_bytes_exceeded,archive_link_entry_forbidden,archive_special_entry_forbidden,archive_parse_failed
- 默认：
MCP 与工具线侧
-
AIA_MCP_SPECIALISTS- 默认：
generalist - 作用：允许使用 MCP 的 specialist 列表
- 生效：
oclaw/tools/mcp/adapter.py
- 默认：
-
AIA_MCP_ENV_ALLOWLIST- 默认：内置 allowlist（Brave/Google/GitHub/Context7）
- 作用：MCP 子进程可透传环境变量白名单
- 生效：
oclaw/runtime/operations/mcp_env.py
-
AIA_MCP_FILESYSTEM_EXTRA_ROOTS- 默认：空
- 作用：追加给 filesystem MCP 的根目录
- 生效：
oclaw/tools/mcp/filesystem_argv.py
-
AIA_MCP_WIRE_USAGE_POLICY- 默认：空（按 base_url 继承）
- 作用：是否启用 MCP 工具线侧分层策略
- 生效：
oclaw/platform/llm/tool_wire_policy.py
-
AIA_MCP_WIRE_PENALTY_DISABLE- 默认：
0 - 作用：禁用线侧陈旧惩罚
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
-
AIA_MCP_WIRE_TOP_N_FULL- 默认：
20 - 作用：全量上送工具数量
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
-
AIA_MCP_WIRE_STALE_HOURS- 默认：
3 - 作用：陈旧判定小时阈值
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
-
AIA_MCP_WIRE_PENALTY_MINUTES- 默认：
30 - 作用：惩罚窗口分钟数
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
-
AIA_MCP_WIRE_MEDIUM_RANK_START- 默认：
21 - 作用：中等层起始排名
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
-
AIA_MCP_WIRE_MEDIUM_RANK_END- 默认：
50 - 作用：中等层结束排名
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
-
AIA_MCP_WIRE_MEDIUM_DESC_CHARS- 默认：
520 - 作用：中等层描述截断长度
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
-
AIA_MCP_WIRE_MINIMAL_DESC_CAP- 默认：
80 - 作用：最小层描述长度
- 生效：
oclaw/platform/llm/tool_wire_policy.py
- 默认：
LLM 工具载荷与模型兼容
-
AIA_OPENAI_TOOLS_MAX_JSON_CHARS- 默认：空（按代码内部策略）
- 作用：OpenAI tools payload JSON 上限
- 生效：
oclaw/platform/llm/chat_models.py
-
AIA_SHRINK_OPENAI_TOOLS- 默认：
0 - 作用：强制启用 tools payload 压缩
- 生效：
oclaw/platform/llm/chat_models.py
- 默认：
-
AIA_SHRINK_OPENAI_TOOLS_MAX_JSON- 默认：
28000 - 作用：压缩目标上限
- 生效：
oclaw/platform/llm/chat_models.py
- 默认：
-
AIA_GEMINI_OPENAI_NONSTREAM_TOOLS- 默认：
0 - 作用：Gemini OpenAI 兼容下 tools 非流式开关
- 生效：
oclaw/platform/llm/chat_models.py
- 默认：
图像能力
-
AIA_IMAGE_MODEL- 默认：空（走 profile/模型默认）
- 作用：图像模型
- 生效：
oclaw/platform/llm/image_message_client.py,oclaw/runtime/agents/specialist_agent.py
-
AIA_IMAGE_BASE_URL- 默认：
https://api.openai.com/v1 - 作用：图像服务 base URL
- 生效：
oclaw/platform/llm/image_message_client.py
- 默认：
-
AIA_IMAGE_API_KEY- 默认：空
- 作用：图像 API Key
- 生效：
oclaw/platform/llm/image_message_client.py
-
AIA_IMAGE_CHAT_ENDPOINT- 默认：
/chat/completions - 作用：图像接口 endpoint
- 生效：
oclaw/platform/llm/image_message_client.py
- 默认：
-
AIA_IMAGE_RETRIES- 默认：
3 - 作用：图像请求重试次数
- 生效：
oclaw/platform/llm/image_message_client.py
- 默认：
-
AIA_IMAGE_RETRY_BACKOFF_SEC- 默认：
0.8 - 作用：图像请求重试退避秒数
- 生效：
oclaw/platform/llm/image_message_client.py
- 默认：
-
AIA_IMAGE_STATUS_RETRIES- 默认：
4 - 作用：图像状态轮询重试次数
- 生效：
oclaw/platform/llm/image_message_client.py
- 默认：
-
AIA_IMAGE_STATUS_RETRY_BACKOFF_SEC- 默认：
5.0 - 作用：图像状态轮询退避秒数
- 生效：
oclaw/platform/llm/image_message_client.py
- 默认：
Memory / RAG
-
AIA_RAG_MODE- 默认：
keyword - 作用：RAG 模式（
keyword/vector） - 生效：
oclaw/orchestration/memory.py
- 默认：
-
AIA_RAG_EMBEDDING_MODE- 默认：空（优先 OpenAI，失败回退 hash）
- 作用：embedding 模式（如
hash） - 生效：
oclaw/platform/embeddings/embedding_client.py
-
AIA_MEMORY_EPISODIC_TTL_DAYS- 默认：
90 - 作用：episodic memory 过期天数
- 生效：
oclaw/orchestration/memory.py
- 默认：
工作区路径策略
-
AIA_WORKSPACE_ROOT- 默认：项目根
- 作用：工作区主根路径
- 生效：
oclaw/tools/experts/workspace/workspace_base.py,oclaw/tools/workspace_indexer.py
-
AIA_WORKSPACE_EXTRA_ROOTS- 默认：空
- 作用：额外可访问根路径（
|分隔） - 生效：
oclaw/tools/experts/workspace/workspace_base.py,oclaw/tools/mcp/filesystem_argv.py
-
AIA_WORKSPACE_ALLOW_ANY_PATH- 默认：
0 - 作用：是否放开内置工具路径限制（高风险）
- 生效：
oclaw/tools/experts/workspace/workspace_base.py
- 默认：
网关与运行
-
AIA_ASSISTANT_GATEWAY_HOST- 默认：
0.0.0.0 - 作用：网关监听地址
- 生效：
oclaw/app_server/fastapi_main.py,oclaw/runtime/operations/main.py
- 默认：
-
AIA_ASSISTANT_GATEWAY_PORT- 默认：
8787 - 作用：网关监听端口
- 生效：
oclaw/app_server/fastapi_main.py,oclaw/runtime/operations/main.py
- 默认：
-
AIA_RUNTIME_LOG_DIR- 默认：空（使用内部默认目录）
- 作用：运行日志目录
- 生效：
oclaw/runtime/operations/runtime.py
-
AIA_SSE_QUEUE_MAXSIZE- 默认：
2000 - 作用：SSE 事件队列上限
- 生效：
oclaw/interfaces/admin/chat_api.py
- 默认：
-
OCLAW_WS_REQUIRE_AUTH- 默认：
1 - 作用：WebSocket 握手是否强制鉴权；开启时
connect必须携带并通过 token 校验 - 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_helpers.py
- 默认：
-
OCLAW_WS_ALLOWED_ORIGINS- 默认：空（回落为 same-host 校验）
- 作用：WebSocket 握手 Origin 白名单（逗号分隔）
- 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py
-
OCLAW_WS_RATE_LIMIT_WINDOW_MS- 默认：
60000 - 作用：WebSocket 请求限流窗口（毫秒）
- 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py
- 默认：
-
OCLAW_WS_RATE_LIMIT_CONN_PER_WINDOW- 默认：
120 - 作用：单连接在限流窗口内可处理请求上限
- 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py
- 默认：
-
OCLAW_WS_RATE_LIMIT_IP_PER_WINDOW- 默认：
240 - 作用：单 IP 在限流窗口内可处理请求上限
- 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py
- 默认：
-
OCLAW_WS_RATE_LIMIT_USER_PER_WINDOW- 默认：
360 - 作用：单用户在限流窗口内可处理请求上限
- 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py
- 默认：
-
OCLAW_WS_SEND_QUEUE_MAX_MESSAGES- 默认：
256 - 作用：每连接发送队列最大消息数（背压阈值）
- 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py,oclaw/interfaces/ws/events.py
- 默认：
-
OCLAW_WS_SEND_QUEUE_MAX_BYTES- 默认：
52428800（与MAX_BUFFERED_BYTES一致） - 作用：每连接发送队列最大字节数（背压阈值）
- 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py,oclaw/interfaces/ws/events.py
- 默认：
-
OCLAW_WS_EVENT_REPLAY_MAX- 默认：
256 - 作用：每用户最近事件回放缓冲上限（用于
connect.params.lastSeq断线补偿） - 生效：
oclaw/interfaces/ws/common.py,oclaw/interfaces/ws/runtime_impl.py,oclaw/interfaces/ws/runtime_helpers.py
- 默认：
WeCom 长连接
-
AIA_WECOM_LONGCONN_WORKERS- 默认：
2 - 作用：入站处理 worker 数
- 生效：
oclaw/interfaces/channels/wecom/longconn_runner.py
- 默认：
-
AIA_WECOM_LONGCONN_INBOUND_QUEUE_MAXSIZE- 默认：
200 - 作用：入站队列长度上限
- 生效：
oclaw/interfaces/channels/wecom/longconn_runner.py
- 默认：
安全与密钥
-
AIA_ASSISTANT_PASSWORD- 默认：空（必须配置）
- 作用：管理台管理员密码（bootstrap/login）
- 生效：
oclaw/platform/config/passwords.py,oclaw/interfaces/admin/routes.py
-
AIA_ASSISTANT_MASTER_KEY- 默认：空
- 作用：密钥加密（Fernet）主密钥
- 生效：
oclaw/platform/persistence/sqlite_store.py,oclaw/interfaces/admin/routes.py
存储与迁移
-
AIA_ASSISTANT_DB_PATH- 默认：
data/ai_ops.sqlite - 作用：SQLite 路径
- 生效：
oclaw/platform/config/paths.py
- 默认：
-
AIA_ASSISTANT_PREMERGE_BACKUP_KEEP- 默认：
3 - 作用：预迁移备份保留数量
- 生效：
oclaw/platform/config/paths.py
- 默认：
-
AIA_LEGACY_DB_FORCE_PREMERGE- 默认：
0 - 作用：是否强制 legacy DB 覆盖（谨慎使用）
- 生效：
oclaw/platform/config/paths.py
- 默认：