Agent runtime architecture

Agent runtime architecture 문서는 OpenClaw 공식 문서(agent-runtime-architecture)를 한국어로 정리한 가이드입니다. How OpenClaw structures the built-in agent runtime: code layout, boundaries, resource manifests, and runtime selection. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How OpenClaw structures the built-in agent runtime: code layout, boundaries, resource manifests, and runtime selection.

한국어 가이드 범위: agent-runtime-architecture 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Runtime Layout
Boundaries
Manifests
Runtime Selection
Model Runtime Generations
관련 문서

상세 내용

본문

OpenClaw owns the built-in agent runtime. Runtime code lives under src/agents/, model/provider transport lives under src/llm/, and plugin-facing contracts are exposed through openclaw/plugin-sdk/* barrels.

Runtime Layout

Path	Owns
`src/agents/embedded-agent-runner/`	Built-in attempt loop (`run.ts`, `run/`), model selection and provider normalization (`model.ts`), per-provider request params (`extra-params.`), compaction, transcript and session wiring.
`src/agents/sessions/`	Session persistence (`session-manager.ts`), resource discovery (`package-manager.ts`, `resource-loader.ts`), in-session `extensions` loading, prompt templates, skills, themes, and TUI-backed tool renderers (`tools/`).
`packages/agent-core/`	Reusable agent core (`@openclaw/agent-core`): agent loop, harness types, messages, compaction helpers, prompt templates, skills, and session storage contracts.
`src/agents/runtime/`	OpenClaw facade that wires `@openclaw/agent-core` to the plugin SDK LLM runtime and re-exports it plus local proxy utilities.
`src/agents/agent-tools*.ts`	OpenClaw-owned tool definitions, parameter schemas, tool policy, before/after tool-call adapters, and host/sandbox edit tools.
`src/agents/agent-hooks/`	Built-in runtime hooks: compaction safeguard, compaction instructions, context pruning.
`src/agents/harness/`	Harness registry, selection policy, and lifecycle for the built-in and plugin-registered harnesses.
`src/llm/`	Model/provider registry, transport helpers, and provider-specific stream implementations (`src/llm/providers/`).

Boundaries

Core calls the built-in runtime through OpenClaw modules and SDK barrels; no external agent framework packages remain. Plugins use documented openclaw/plugin-sdk/* entrypoints and do not import src/** internals.

Manifests

Resource packages declare OpenClaw resources in package.json metadata. Entries are file paths or globs relative to the package root:

{
  "openclaw": {
    "extensions": ["extensions/index.ts"],
    "skills": ["skills/*.md"],
    "prompts": ["prompts/*.md"],
    "themes": ["themes/*.json"]
  }
}

Runtime Selection

주요 항목:

The built-in runtime id is openclaw. The legacy alias pi normalizes to openclaw; codex-app-server normalizes to codex.
Plugin harnesses register additional runtime ids (for example codex).
Runtime policy is model/provider-scoped agentRuntime.id config (model entry wins over provider entry). Unset or default resolves to auto.
auto selects a registered plugin harness that supports the effective provider route, otherwise the built-in OpenClaw runtime. A provider or model prefix alone never selects a harness.
OpenAI may select codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored request override. Completions adapters, custom endpoints, and routes with authored request behavior stay on openclaw; plaintext official HTTP endpoints are rejected. See OpenAI implicit agent runtime.

Model Runtime Generations

Gateway startup and config, plugin, or auth publication build one prepared model runtime generation per configured agent. Each generation owns the discovered auth template, model registry, and projected model catalog as one atomic snapshot. Agent runs fork mutable auth and registry stores from that snapshot; browse, status, cron, doctor, TUI, PDF, and image paths read the published catalog instead of repeating filesystem discovery.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/agent-runtime-architecture
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  "openclaw": {
    "extensions": ["extensions/index.ts"],
    "skills": ["skills/*.md"],
    "prompts": ["prompts/*.md"],
    "themes": ["themes/*.json"]
  }
}

Agent runtime architecture

핵심 요약

How OpenClaw structures the built-in agent runtime: code layout, boundaries, resource manifests, and runtime selection.

한국어 가이드 범위: agent-runtime-architecture 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Runtime Layout
Boundaries
Manifests
Runtime Selection
Model Runtime Generations
관련 문서

상세 내용

본문

Runtime Layout

Path	Owns
`src/agents/embedded-agent-runner/`	Built-in attempt loop (`run.ts`, `run/`), model selection and provider normalization (`model.ts`), per-provider request params (`extra-params.`), compaction, transcript and session wiring.
`src/agents/sessions/`	Session persistence (`session-manager.ts`), resource discovery (`package-manager.ts`, `resource-loader.ts`), in-session `extensions` loading, prompt templates, skills, themes, and TUI-backed tool renderers (`tools/`).
`packages/agent-core/`	Reusable agent core (`@openclaw/agent-core`): agent loop, harness types, messages, compaction helpers, prompt templates, skills, and session storage contracts.
`src/agents/runtime/`	OpenClaw facade that wires `@openclaw/agent-core` to the plugin SDK LLM runtime and re-exports it plus local proxy utilities.
`src/agents/agent-tools*.ts`	OpenClaw-owned tool definitions, parameter schemas, tool policy, before/after tool-call adapters, and host/sandbox edit tools.
`src/agents/agent-hooks/`	Built-in runtime hooks: compaction safeguard, compaction instructions, context pruning.
`src/agents/harness/`	Harness registry, selection policy, and lifecycle for the built-in and plugin-registered harnesses.
`src/llm/`	Model/provider registry, transport helpers, and provider-specific stream implementations (`src/llm/providers/`).

Boundaries

Manifests

Resource packages declare OpenClaw resources in package.json metadata. Entries are file paths or globs relative to the package root:

{
  "openclaw": {
    "extensions": ["extensions/index.ts"],
    "skills": ["skills/*.md"],
    "prompts": ["prompts/*.md"],
    "themes": ["themes/*.json"]
  }
}

Runtime Selection

주요 항목:

The built-in runtime id is openclaw. The legacy alias pi normalizes to openclaw; codex-app-server normalizes to codex.
Plugin harnesses register additional runtime ids (for example codex).
Runtime policy is model/provider-scoped agentRuntime.id config (model entry wins over provider entry). Unset or default resolves to auto.
auto selects a registered plugin harness that supports the effective provider route, otherwise the built-in OpenClaw runtime. A provider or model prefix alone never selects a harness.
OpenAI may select codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored request override. Completions adapters, custom endpoints, and routes with authored request behavior stay on openclaw; plaintext official HTTP endpoints are rejected. See OpenAI implicit agent runtime.

Model Runtime Generations

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/agent-runtime-architecture
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  "openclaw": {
    "extensions": ["extensions/index.ts"],
    "skills": ["skills/*.md"],
    "prompts": ["prompts/*.md"],
    "themes": ["themes/*.json"]
  }
}

Agent runtime architecture

핵심 요약

문서 구성

상세 내용

본문

Runtime Layout

Boundaries

Manifests

Runtime Selection

Model Runtime Generations

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Agent runtime architecture

핵심 요약

문서 구성

상세 내용

본문

Runtime Layout

Boundaries

Manifests

Runtime Selection

Model Runtime Generations

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드