diff --git a/docs/content/docs/framework/agent/meta.en.json b/docs/content/docs/framework/agent/meta.en.json
index be48b554..cb7bd5bf 100644
--- a/docs/content/docs/framework/agent/meta.en.json
+++ b/docs/content/docs/framework/agent/meta.en.json
@@ -1,4 +1,12 @@
 {
   "title": "Agent",
-  "pages": ["overview", "create", "prompt", "skills", "responses-api", "multi-agent"]
+  "pages": [
+    "overview",
+    "create",
+    "prompt",
+    "skills",
+    "responses-api",
+    "runtime",
+    "multi-agent"
+  ]
 }
diff --git a/docs/content/docs/framework/agent/meta.json b/docs/content/docs/framework/agent/meta.json
index cde1dc91..d61ba06d 100644
--- a/docs/content/docs/framework/agent/meta.json
+++ b/docs/content/docs/framework/agent/meta.json
@@ -1,4 +1,12 @@
 {
   "title": "智能体",
-  "pages": ["overview", "create", "prompt", "skills", "responses-api", "multi-agent"]
+  "pages": [
+    "overview",
+    "create",
+    "prompt",
+    "skills",
+    "responses-api",
+    "runtime",
+    "multi-agent"
+  ]
 }
diff --git a/docs/content/docs/framework/agent/runtime.en.mdx b/docs/content/docs/framework/agent/runtime.en.mdx
new file mode 100644
index 00000000..c31a0436
--- /dev/null
+++ b/docs/content/docs/framework/agent/runtime.en.mdx
@@ -0,0 +1,99 @@
+---
+title: "Runtime"
+description: "Switch the runtime that drives the agent loop via Agent(runtime=...): adk by default, or codex."
+---
+
+VeADK's agent loop is driven by a **pluggable runtime**. `Agent(runtime=...)`
+selects which one executes that loop, while the surrounding
+[`Runner`](/en/docs/framework/runner) always owns session, memory, and tracing —
+switching runtimes does not change those.
+
+| Runtime | Description | Dependencies |
+| :-- | :-- | :-- |
+| `adk` (default) | Google ADK's built-in `BaseLlmFlow`, driven directly by `Agent`; no separate runtime object. | none |
+| `codex` | Uses the OpenAI Codex SDK as the agent harness for the invocation. | optional `openai-codex` extras |
+
+## Switching the runtime
+
+```python
+from veadk import Agent
+
+# Default runtime: adk
+agent = Agent(name="assistant")
+
+# Switch to the codex runtime
+agent = Agent(name="coder", runtime="codex")
+```
+
+The `runtime` field is `Literal["adk", "codex"]`, default `"adk"`.
+
+## adk runtime (default)
+
+The default; no extra configuration or dependencies. The agent loop runs on
+Google ADK's built-in LLM flow — identical to omitting `runtime`.
+
+## codex runtime
+
+Drives the agent loop with the OpenAI Codex SDK as the harness.
+
+### Dependencies
+
+The `codex` runtime needs optional extras (it **fails fast** with an install
+hint when they are missing):
+
+```bash
+pip install openai-codex fastapi uvicorn
+```
+
+`openai-codex` bundles the Codex CLI binary via `openai-codex-cli-bin`.
+
+### Configuration
+
+```python
+agent = Agent(
+    name="coder",
+    runtime="codex",
+    model_name="<your-model>",
+    model_api_base="<chat-endpoint-base-url>",
+    model_api_key="<api-key>",
+)
+```
+
+- **Model**: taken from `Agent(model_name=...)` (first entry if a list), else the
+  `OPENAI_MODEL` env var; fails fast if neither resolves.
+- **Endpoint**: the `codex` runtime requires `model_api_base` and
+  `model_api_key` (or `OPENAI_BASE_URL` / `OPENAI_API_KEY`). Missing either is an
+  error.
+
+### How it works
+
+- Codex speaks only the **Responses API**, whereas the backend is typically a
+  Chat endpoint, so requests are routed through an **in-process Responses→Chat
+  shim** (`veadk.runtime.codex.proxy`).
+- The Codex subprocess is isolated from the host's `~/.codex` via a dedicated
+  `CODEX_HOME` with a generated `config.toml`; the backend credential is injected
+  through the provider's `env_key`.
+- Because Codex has no clean channel to append to its system prompt, the agent's
+  identity/instruction is folded into a leading preamble of the input rather than
+  the transcript.
+- The surrounding `Runner` still owns session, memory, and tracing.
+
+<Callout type="warn">
+  Codex may issue requests for an auxiliary model (e.g. `codex-auto-review`)
+  during a run; if your endpoint/account lacks access to it, those steps fail.
+  Make sure the endpoint can serve the models Codex requires.
+</Callout>
+
+## Using it on the Harness server
+
+The deployed [Harness server](/en/docs/cli/harness-cli) exposes the same switch:
+the harness spec's `runtime` field, and the `--runtime` option on
+`veadk agentkit harness add/invoke` (`adk` or `codex`).
+
+## Adding a custom runtime
+
+Runtimes are resolved via `veadk.runtime.get_runtime(name)` and implement the
+`veadk.runtime.base_runtime.BaseRuntime` abstract base (an async
+`run_async(agent, ctx)` event generator). `adk` is handled inline by `Agent` and
+never goes through the registry; other runtimes (like `codex`) are resolved
+there.
diff --git a/docs/content/docs/framework/agent/runtime.mdx b/docs/content/docs/framework/agent/runtime.mdx
new file mode 100644
index 00000000..819cebdd
--- /dev/null
+++ b/docs/content/docs/framework/agent/runtime.mdx
@@ -0,0 +1,77 @@
+---
+title: "运行时"
+description: "通过 Agent(runtime=...) 切换驱动智能体循环的运行时：默认 adk，或 codex。"
+---
+
+VeADK 的智能体循环由**可插拔运行时（Pluggable Runtime）**驱动。`Agent(runtime=...)` 决定由谁来执行这层循环，而外层的 [`Runner`](/cn/docs/framework/runner) 始终负责会话、记忆与链路追踪 —— 切换运行时不影响这些能力。
+
+| 运行时 | 说明 | 依赖 |
+| :-- | :-- | :-- |
+| `adk`（默认） | Google ADK 内置的 `BaseLlmFlow`，由 `Agent` 直接驱动，无需额外运行时对象。 | 无 |
+| `codex` | 以 OpenAI Codex SDK 作为智能体 harness 来驱动这次调用。 | `openai-codex` 等可选依赖 |
+
+## 切换运行时
+
+```python
+from veadk import Agent
+
+# 默认运行时：adk
+agent = Agent(name="assistant")
+
+# 切换到 codex 运行时
+agent = Agent(name="coder", runtime="codex")
+```
+
+`runtime` 字段类型为 `Literal["adk", "codex"]`，默认 `"adk"`。
+
+## adk 运行时（默认）
+
+默认值，无需任何额外配置或依赖。智能体循环交给 Google ADK 内置的 LLM flow 执行，行为与不传 `runtime` 完全一致。
+
+## codex 运行时
+
+以 OpenAI Codex SDK 作为 harness 来驱动智能体循环。
+
+### 依赖
+
+`codex` 运行时需要额外的可选依赖（缺失时会**快速失败**并给出安装提示）：
+
+```bash
+pip install openai-codex fastapi uvicorn
+```
+
+`openai-codex` 通过 `openai-codex-cli-bin` 自带 Codex CLI 二进制。
+
+### 配置
+
+```python
+agent = Agent(
+    name="coder",
+    runtime="codex",
+    model_name="<your-model>",
+    model_api_base="<chat-endpoint-base-url>",
+    model_api_key="<api-key>",
+)
+```
+
+- **模型**：取 `Agent(model_name=...)`（列表则取第一个），否则回退到环境变量 `OPENAI_MODEL`；都没有则快速失败。
+- **接入点**：`codex` 运行时要求 `model_api_base` 与 `model_api_key`（也可分别由 `OPENAI_BASE_URL` / `OPENAI_API_KEY` 提供）。缺失即报错。
+
+### 工作原理
+
+- Codex 只使用 **Responses API**，而后端通常是 Chat 接口，因此请求会经由一个**进程内的 Responses→Chat 转换层**（`veadk.runtime.codex.proxy`）。
+- Codex 子进程通过独立的 `CODEX_HOME` 与生成的 `config.toml` 与宿主机 `~/.codex` 隔离，后端凭证经由 provider 的 `env_key` 注入。
+- 由于 Codex 没有干净的「追加系统提示」通道，智能体的身份/指令会被折叠进输入的前置区块（labelled preamble），而非写入对话历史。
+- 外层 `Runner` 依旧负责会话、记忆与追踪。
+
+<Callout type="warn">
+  Codex 在运行中可能发起对辅助模型（如 `codex-auto-review`）的请求；若你的接入点/账号没有该模型权限，相应步骤会失败。请确保接入点具备 Codex 所需模型的访问权限。
+</Callout>
+
+## 在 Harness Server 中使用
+
+部署的 [Harness server](/cn/docs/cli/harness-cli) 也暴露了运行时开关：harness 规格的 `runtime` 字段，以及 `veadk agentkit harness add/invoke` 的 `--runtime` 选项（`adk` 或 `codex`）。
+
+## 扩展自定义运行时
+
+运行时通过 `veadk.runtime.get_runtime(name)` 解析，并实现 `veadk.runtime.base_runtime.BaseRuntime` 抽象基类（核心是一个异步的 `run_async(agent, ctx)` 事件生成器）。`adk` 由 `Agent` 内联处理、不经过该注册表；其余运行时（如 `codex`）由此解析。