此为预览文档，正式版本尚未发布。
连接参数
默认配置在
~/.agentscope/runtime-host/config.json。其中 controlPlane、tenant、namespace、pool、capacity、workspaceRoot、stateRoot 与 providers 描述连接；credential 是身份凭据，不复制进公共示例。修改已运行 Host 的设置前先检查活跃工作，更新后重启并再次 probe。
Agent 与 Profile 的分工
Agent 的system 定义职责，model 提供可选模型覆盖。Model 非空时优先于 Profile 的 model；两者都为空时使用 provider 自己的默认配置。
runtimeProfileId 选择 provider 配置，runtimePoolId 选择可承载执行的主机池。通过 runtime-options 选择已发现的 Runtime，管理员再维护 Profile 和池。只增加 Host capacity 不等于增加模型额度或消除 Agent/任务策略限制。
Agent 与运行配置 API
这些接口使用有权管理目标 namespace 的平台账户 Bearer。第一次创建的完整请求见连接并创建 Agent。
创建时
binding.configuration 必须包含同一 scope 中的 runtimeProfileId 和 runtimePoolId，可选 executionOverrides。definition 与 Managed 使用同一格式，常用 name、system、model、tools、mcpServers、skills、workspaceId、workspaceBinding。字段能否作用到原生 provider 由其能力决定。更新定义前先读回完整配置并修改所需部分，避免把 PATCH 理解为任意字段都自动保留的浅合并。
Hosted settings 字段
providerConfiguration 是对象，customArgs 是 argv 字符串数组；参数合法性与保留选项按 provider 检查。不要修改共享 Runtime Profile 来实现某一个 Agent 的专属偏好。
下面只调整并发，AGENT_ID 为已创建的 Agent UUID，SERVICE_URL 和 TOKEN 为管理连接配置：
管理共享 Profile 与 Pool
GET /api/v1/runtime-profiles 和 /runtime-pools 使用 tenant、namespace 查询参数，返回 items。单个资源用 /runtime-profiles/{name} 或 /runtime-pools/{name} 查询，返回 profile 或 pool。
PUT 路径中的
name 决定更新对象。提交完整的期望配置，成功后保存响应中的 UUID 供 Agent binding 引用。主机容量、暂停接收新工作及 enrollment 接口见 Runtime Host API。
Provider 参数
以下是 Runtime Profileconfiguration 中的字段，不是 connect 参数，也不是所有 provider 通用的表单。
provider 的模型名、推理档位和账号可用性以本机安装版本为准。Profile 保存参数并不会替你安装模型、登录账号或授予外部工具权限。
定义与参数冲突
Host 将可移植指令、技能和支持的 MCP/工具定义转换为 provider 配置。若 Workspace 要求 provider 不支持的能力，执行前会拒绝；不要把能力错误当作“可以忽略的提示”。详细差异见支持的 provider。 自定义参数以 argv 项传递；工作目录、模型、输出协议、MCP 配置和权限相关的保留参数不能随意覆盖。配置 Codex 原生工具时使用 Profile sandbox/审批语义，不能直接复用 Managed 内置工具策略。选择运行类型
安装 provider 本体并完成登录后，再连接 Host。以上是 Service 适配范围，不代表 CLI 二进制随 Service 发布包附带。
可移植定义如何生效
“支持”表示适配器有对应集成，仍需要目标 CLI 版本和账户能力。Codex 的原生 Subagent 映射要求 0.153.4+，Qoder 要求 1.0.37+；当前映射要求共享工作区。Codex Subagent 声明不能携带此映射无法执行的
tools 或 maxIters；Qoder 的工具需要能映射为原生工具名。
Codex、Qoder 和 QwenPaw 适配器提供控制面工具确认接入。Claude Code 的权限通过其 CLI 配置控制，不能据此承诺与前述 provider 相同的 Inbox 确认流程。OpenClaw 使用支持 Shell 的任务 CLI 完成协作；它不支持本适配器的 MCP 注入。
从 API 获取当前主机的能力
文中的表格用于理解映射方式，实际可用项以主机上报为准。用平台账户 Bearer 请求：runtimes 中选择 provider；每项提供 provider、version、runtimeProfileId、runtimePoolId、hostCount 和 capabilities。能力对象包含 instructions、workspace、skills、subagents、tools、shell、mcp、model、customArgs、approval 和 resume。除 resume 为布尔值外，能力项通过 supported、mode、target 说明是否支持及如何映射。
可以从 GET /api/v1/runtime-hosts?tenant=...&namespace=... 返回的 items[].capabilities 查看各 Host 的 provider 版本和描述。创建 Agent 时，把选项的 profile/pool UUID 写入 binding；更新 provider 专属参数使用 /api/v1/agents/{agentId}/hosted-settings，字段见配置参考。
这里的 resume 描述 provider 的原生会话恢复，不直接等于应用可以执行的 Turn 恢复命令。应用应读取 Session 和 Turn 的 capabilities，只有 available_commands 明确列出某项操作时才显示对应按钮。