mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-09 04:40:45 +08:00
oliver
7253f6795d
本次将握手鉴权、Origin 校验、限流、重连补偿、发送背压与观测字段打通，同时修复 gateway 异常路径与备份清理兼容问题，确保工具历史压缩语义一致并恢复全量测试通过。 Made-with: Cursor
478 lines
20 KiB
Markdown
478 lines
20 KiB
Markdown
# 环境变量总览（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；Admin `AIA_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`
|