🏗️ 12-Factor Agents：生产级 LLM 应用的十二信条

12-Factor生产部署LLM ⭐ 21,545 stars

人类写给 AI 应用的「摩西十诫」——只不过它真的有 12 条。

12-Factor Agents（humanlayer/12-factor-agents）是 2026 年 GitHub 上的现象级开源项目。它问了一个直击灵魂的问题：构建 LLM 驱动的软件时，遵循什么原则才能真正达到生产级别？

十二因子详解

I 代码库（Codebase）

一份代码库，多环境部署。Agent 逻辑和配置严格分离。

# OpenClaw 中的多环境配置
environments:
  dev:
    model: gpt-4o-mini
    max_tokens: 4096
  staging:
    model: gpt-4o
    max_tokens: 8192
  production:
    model: claude-sonnet-4
    max_tokens: 16384
    fallback: gpt-4o

II 依赖（Dependencies）

显式声明所有 Agent 依赖。Tool、Skill、Provider 必须锁定版本。

# OpenClaw skills.yaml
skills:
  - name: web-scraper
    version: 1.2.0
    checksum: sha256:abc123...
  - name: code-reviewer
    version: 2.0.1

III 配置（Config）

环境变量存储配置，绝不硬编码。API Keys、模型选择、超时时间通过环境注入。

export OPENCLAW_MODEL=claude-sonnet-4
export OPENCLAW_MAX_RETRIES=3
export OPENCLAW_MEMORY_BACKEND=redis

IV 后端服务（Backing Services）

数据库、缓存、向量存储都是可挂载的资源，Agent 通过统一接口访问。

V 构建、发布、运行（Build, Release, Run）

Agent 部署三阶段严格分离：Skill 构建 → 发布包 → 生产运行，支持回滚。

VI 进程（Processes）

Agent 为无状态进程，所有持久化委托给外部服务。Session 状态存储在 Redis 或向量数据库。

VII 端口绑定（Port Binding）

Agent 通过 MCP Server 暴露服务接口，每个 Skill 绑定独立端口。

VIII 并发（Concurrency）

通过子 Agent（Sub-Agent）模式横向扩展。每个任务独立沙箱执行。

// OpenClaw 并发 Agent 配置
agent:
  concurrency:
    max_sub_agents: 10
    isolation: sandbox
    queue: redis-bull

IX 可处置性（Disposability）

Agent 可随时停止和启动。快速启动（< 100ms）且优雅关闭（保存 checkpoint）。

X 开发-生产环境一致性（Dev/Prod Parity）

本地开发用的 Agent 和线上用的是同一份代码、同一个配置体系。

XI 日志（Logs）

Agent 行为作为事件流输出，不关心存储和路由。由日志聚合系统处理。

XII 管理进程（Admin Processes）

一次性管理任务（数据迁移、模型评估）在隔离环境中运行。

OpenClaw 中的完整实践

📋 清单：在 OpenClaw 中部署生产级 Agent 时，逐条检查 12-Factor 合规性。 
# 一键验证 12-Factor 合规
openclaw audit twelve-factor --config ./production.yaml

# 输出
✅ I. Codebase - 通过
✅ II. Dependencies - 通过
❌ III. Config - 失败: OPENCLAW_MAX_RETRIES 未配置
✅ IV. Backing Services - 通过
...

🔗 相关阅读