本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

本地引擎集成（AX Code）

状态：生效范围：当前状态最近审阅：2026-09-19 负责人：ax-code 运行时相关：ax-engine 本地引擎客户端

本地运行时设置

在 /connect 中选择 AX-Engine 运行时，然后选择 选择模型。所选模型被需要时，AX Code 会配置本地运行时并启动它。没有端点 URL 或 API 密钥表单。查看状态、停止本地运行时（运行中时）和禁用用于管理本地进程。

AX Code 使用 边车 HTTP 后端连接 AX Engine。它启动 ax-engine serve，跟踪所拥有的进程，并自动解析回环地址和端口。用户选择模型；AX Code 负责传输配置。

AX Code (TypeScript)
  -> select local model -> ensure/prepare -> spawn ax-engine serve
  -> managed loopback /v1 -> @ai-sdk/openai-compatible language model

显式选择模型会保存托管生命周期，并清除遗留的附着端点与密钥设置。这也会覆盖残留的 AX_ENGINE_HOST 值。较旧的 SDK 客户端仍保留仅回环的旧附着 API 及其凭据校验。该兼容路径不属于提供商菜单。

AX Code 不会在进程内链接 AX Engine SDK。AX Engine 拥有模型执行，AX Code 拥有客户端进程生命周期。主机资格、模型准备和实时工具调用检查仍然适用。

冷启动有 600 秒就绪时限。启动时间取决于模型大小、存储吞吐和可用内存。启动耗尽会带着服务器日志和模型路径停止本轮；AX Code 不会自动重启另一次冷加载，也不会切换提供商。在显式重试之前，先解决所报告的问题。模型设置包络（包括生命周期锁等待和能力发现）限制为 660 秒。到期会取消待处理的设置并停止自动重试。取消请求也会立即停止等待，即使某个设置依赖尚未响应。就绪期限之后到达的健康回复，或所拥有进程已经退出之后到达的回复，不能确立就绪。

就绪之后，引擎在对话轮次之间保持驻留。完成或取消发起该轮，并不会停止已就绪的引擎。启动仍在进行时取消，会终止该次尝试并移除其进程记录。使用 停止本地运行时 显式停止驻留引擎。

AX Code 遵循标准的 Hugging Face 缓存位置，并尊重用户的存储选择，包括本地磁盘、SMB 和 NFS 挂载。缓存解析顺序为 HF_HUB_CACHE，然后 HF_HOME/hub，然后 XDG_CACHE_HOME/huggingface/hub，然后 ~/.cache/huggingface/hub。显式配置或已经准备好的模型路径优先于缓存发现。AX Code 不会根据存储类型搬迁权重，也不会覆盖这些选择。启动诊断会报告实际模型路径，便于用户在所选存储上调查可用性与读取性能。

对于已存在的引擎，AX Code 最多做三次健康探测，每次限制为两秒，间隔 250 毫秒，然后才重启无响应的进程。取消请求会保留现有进程。

为何使用边车

因素	边车选择
宿主语言	带有显式原生进程边界的 Node/Bun agent 运行时
隔离	数 GB 级模型与原生崩溃留在 agent 进程之外
升级	带版本门的捆绑下限，加上可选的托管覆盖层，无需重新构建 ax-code
提供商模型	与其他本地和云提供商相同的 OpenAI 兼容路径
多客户端	一台服务器可通过 `server.json` 做健康检查并停止

生命周期阶段

实现：packages/ax-code/src/provider/ax-engine/lifecycle.ts

阶段	时机（AX Code 映射）
`unavailable`	平台资格检查失败
`missing_dependency`	二进制缺失 / 版本过旧 / 不可执行
`missing_model`	模型路径尚未准备
`starting`	已记录服务器进程，但尚未就绪
`ready`	`server.ready` 且进程健康正常
`degraded`	已就绪，但能力检查表明不支持工具调用
`error`	一次运行中的尝试上存在健康或启动失败阻碍

严重程度顺序与 ax-engine docs/LOCAL-ENGINE-CLIENTS.md 一致。

区域	路径
服务器生成与健康检查	`packages/ax-code/src/provider/ax-engine/server.ts`
提供商加载器（托管与附着）	`packages/ax-code/src/provider/ax-engine/provider-loader.ts`
TUI 本地运行时	`packages/ax-code/src/cli/tui/component/dialog-provider.tsx`
本地操作辅助函数	`packages/ax-code/src/cli/tui/component/dialog-provider-options.ts`
聚合状态	`packages/ax-code/src/provider/ax-engine/status.ts`
阶段映射	`packages/ax-code/src/provider/ax-engine/lifecycle.ts`
模型策略	AX Engine 模型选择

钉住边车的托管供给并不是进程内嵌入。Darwin-arm64 发行版把 engine/<version>/ 放在 CLI 旁边；当发布更新的钉住版本时，ax-code providers ax-engine install 是覆盖层与更新器。

非目标

在 AX Code 中用进程内 SDK 嵌入替换边车
采用 gRPC 作为主要聊天传输
为第一方客户端采用自定义 Unix 套接字或非 OpenAI 的聊天帧
把模型权重烘焙进 AX Code 安装程序

本地引擎集成（AX Code）

本地运行时设置

为何使用边车

生命周期阶段

相关代码

非目标