mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-09 09:54:03 +00:00
f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
56 lines
4.6 KiB
Markdown
56 lines
4.6 KiB
Markdown
---
|
|
title: "Agent runtime architecture"
|
|
summary: "How OpenClaw structures the built-in agent runtime: code layout, boundaries, resource manifests, and runtime selection."
|
|
---
|
|
|
|
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.
|
|
|
|
`@earendil-works/pi-tui` remains a third-party dependency: a terminal component toolkit used by the local TUI and session tool renderers. Internalizing it would be a separate vendoring effort.
|
|
|
|
## Manifests
|
|
|
|
Resource packages declare OpenClaw resources in `package.json` metadata. Entries are file paths or globs relative to the package root:
|
|
|
|
```json
|
|
{
|
|
"openclaw": {
|
|
"extensions": ["extensions/index.ts"],
|
|
"skills": ["skills/*.md"],
|
|
"prompts": ["prompts/*.md"],
|
|
"themes": ["themes/*.json"]
|
|
}
|
|
}
|
|
```
|
|
|
|
Resource types not listed in a manifest fall back to discovery of conventional `extensions/`, `skills/`, `prompts/`, and `themes/` directories.
|
|
|
|
## 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 provider/model, otherwise the built-in OpenClaw runtime.
|
|
- The `openai` provider on the official API endpoint defaults to the `codex` harness; custom `baseUrl` values keep their configured behavior.
|
|
|
|
## Related
|
|
|
|
- [OpenClaw agent runtime workflow](/openclaw-agent-runtime)
|
|
- [Agent runtimes](/concepts/agent-runtimes)
|