oclaw/docs/ENVIRONMENT_VARIABLES_CHANGELOG.md

环境变量变更台账（AIA）

用于记录每次版本发布中的环境变量变更，便于升级与回滚评估。

使用规则

• 每次发布前后都要补一条记录（即使“无变更”也要写）。
• 记录粒度：
  • 新增变量
  • 删除变量
  • 重命名（含兼容窗口）
  • 默认值变化
  • 语义变化（同名但行为变了）
• 变更后必须同步：
  • oclaw/docs/ENVIRONMENT_VARIABLES.md
  • README.md 示例
  • 示例 env 文件（如 data/mcp_local.env.example）

---

模板

## YYYY-MM-DD / vX.Y.Z

### Added
- `AIA_XXX`
  - 默认值：
  - 用途：
  - 影响模块：

### Changed
- `AIA_YYY`
  - 变更前：
  - 变更后：
  - 影响：
  - 是否需要重启：是/否

### Deprecated
- `AIA_ZZZ`
  - 弃用原因：
  - 兼容截止版本：
  - 替代变量：

### Removed
- `AIA_OLD`
  - 删除原因：
  - 升级动作：

### Migration Checklist
- [ ] 已更新 `oclaw/docs/ENVIRONMENT_VARIABLES.md`
- [ ] 已更新 `README.md`
- [ ] 已更新示例 env 文件
- [ ] 已验证 Admin 配置页（如适用）
- [ ] 已执行编译/测试回归

---

2026-04-21 / Unreleased

Added

• AIA_PROMPT_FRONTMATTER_STRICT（默认 0）：强制 YAML frontmatter。
• AIA_SKILLS_PROMPT_IN_SYSTEM（默认 1）：oclaw 风格 <available_skills> 注入 system prompt。
• AIA_SKILLS_PROMPT_MAX_CHARS（默认 18000）：技能目录块字符预算。
• 依赖：PyYAML（requirements.txt）。

Changed

• oclaw/prompts/loader.py 与 oclaw/oclaw_runtime/skills.py 统一使用 YAML 解析 frontmatter（失败时默认回落旧行解析，除非开启 STRICT）。

---

2026-04-19 / Unreleased

Added

• oclaw/docs/ENVIRONMENT_VARIABLES.md（变量总览基线文档）
• oclaw/docs/ENVIRONMENT_VARIABLES_CHANGELOG.md（本台账）
• OpenAI 兼容 replay 相关（见 oclaw/docs/ENVIRONMENT_VARIABLES.md「LLM 传输与 replay」）：
  • AIA_REPLAY_POLICY_ENABLED（默认 1）
  • AIA_REPLAY_REPAIR_TOOL_PAIRING（默认 1）
  • AIA_TOOL_CALL_ID_MAX_LEN（默认 40）
  • AIA_PROMPT_TOOL_FALLBACK（默认 1）
  • oclaw/platform/llm/OCLAW_MIT_LICENSE.txt（oclaw 启发实现之 MIT 署名）

Changed

• 变量前缀统一为 AIA_*，项目内不再使用 OPS_* / AI_OPS_*。
• README.md 与 data/mcp_local.env.example 示例变量已同步为 AIA_*。
• 环境变量维护流程已文档化：后续变量改动需同时更新
  • oclaw/docs/ENVIRONMENT_VARIABLES.md（当前生效基线）
  • oclaw/docs/ENVIRONMENT_VARIABLES_CHANGELOG.md（版本变更历史）
  • README.md / 示例 env（用户可见配置入口）

Removed

• 代码中的 OPS_* / AI_OPS_* 引用（已清理完成）。

Migration Checklist

• 已更新 oclaw/docs/ENVIRONMENT_VARIABLES.md
• 已更新 README.md
• 已更新示例 env 文件
• 已验证 Admin 配置页（如适用）
• 已执行编译/测试回归

---

2026-04-20 / Unreleased

Added

• AIA_OCLAW_ALLOW_LEGACY_FALLBACK
  • 默认值：0
  • 用途：oclaw runtime 失败时是否允许回退到 legacy run_turn
  • 影响模块：oclaw/oclaw_runtime/gateway.py, oclaw/runtime/agents/specialist_agent.py

Changed

• AIA_TURN_MAX_*（tool workers/rounds/context）
  • 变更前：由 legacy turn runner 读取（历史文件名可能为 agent_core.py）
  • 变更后：由 oclaw runtime 读取并生效（oclaw/oclaw_runtime/gateway.py）
  • 是否需要重启：是（读取自 settings/db/env 的时机取决于运行方式）

Deprecated

• AIA_MANAGER_DECISION_MODE, AIA_TOOL_ENFORCED_RETRY_MODE, AIA_TOOL_LOOP_STATE_MACHINE, AIA_TOOL_SIGNATURE_BUDGET, AIA_DISABLE_TOOL_CONFIRM
  • 弃用原因：oclaw runtime 已断开 legacy manager/runner/tool-policy 链路（代码保留，默认不生效）
  • 兼容截止版本：待定
  • 替代变量：无（后续如需恢复 legacy 将重新定义接入点）

Migration Checklist

• 已更新 oclaw/docs/ENVIRONMENT_VARIABLES.md
• 已更新 README.md
• 已更新示例 env 文件
• 已验证 Admin 配置页（如适用）
• 已执行编译/测试回归

---

2026-04-20 / Unreleased (oclaw MVP 补齐)

Changed

• 无新增环境变量；oclaw runtime 在现有变量下补齐了 memory stage、router sync/async 分流、sqlite task queue、worker 执行链路。
  • 影响模块：oclaw/oclaw_runtime/gateway.py, oclaw/oclaw_runtime/direct_loop.py, oclaw/oclaw_runtime/router.py, oclaw/oclaw_runtime/worker.py, oclaw/platform/persistence/sqlite_store.py
  • 是否需要重启：是（升级代码后建议重启进程以启动 worker 与新路由逻辑）

Migration Checklist

• 已更新 oclaw/docs/ENVIRONMENT_VARIABLES.md
• 已更新 README.md
• 已更新示例 env 文件
• 已验证 Admin 配置页（如适用）
• 已执行编译/测试回归

---

2026-04-20 / Unreleased (AgentCore Retry Matrix)

Added

• AIA_OCLAW_RETRYABLE_ERROR_CODES
  • 默认值：provider_timeout,provider_rate_limited,provider_temporary_error,provider_unavailable,context_overflow,tool_execution_failed
  • 用途：控制 Agent Core run 外环可重试错误白名单
  • 影响模块：oclaw/oclaw_runtime/agent_core_run.py, oclaw/interfaces/admin/routes.py, oclaw/interfaces/admin/static/app.js

Changed

• Agent Core 重试策略从“status=retry 即重试”升级为“retry + error_code 命中白名单才重试”。
  • 是否需要重启：是（新策略读取设置后在进程内生效）

Migration Checklist

• 已更新 oclaw/docs/ENVIRONMENT_VARIABLES.md
• 已更新 README.md
• 已更新示例 env 文件
• 已验证 Admin 配置页（如适用）
• 已执行编译/测试回归

Changed

• AIA_OCLAW_RETRYABLE_ERROR_CODES 已接入 Admin「Tool Policy」页读写链路。
  • 影响模块：oclaw/interfaces/admin/routes.py, oclaw/interfaces/admin/static/app.js
• AIA_OCLAW_RETRYABLE_ERROR_CODES 保存时增加未知 code 过滤与告警返回（unknown_retryable_error_codes）。
  • 影响模块：oclaw/interfaces/admin/routes.py, oclaw/interfaces/admin/static/app.js, oclaw/oclaw_runtime/agent_core_run.py
• AIA_OCLAW_RETRYABLE_ERROR_CODES 新增严格模式：可配置为未知 code 直接拒绝保存（400）。
  • 影响模块：oclaw/interfaces/admin/routes.py, oclaw/interfaces/admin/static/app.js

Added

• AIA_OCLAW_RETRY_CODES_STRICT_MODE
  • 默认值：0
  • 用途：控制 Admin 保存 retry code 时对未知值的处理（过滤告警 / 拒绝）
  • 影响模块：oclaw/interfaces/admin/routes.py, oclaw/interfaces/admin/static/app.js