Open Agent API

模型提供方与 oaa connect <预设>

内置智能体(网关自己的智能体循环,engine = kernel)是能力最全的一类:调用方工具桥接、结构化输出修复轮、图片输入都以它为准。它需要一个模型提供方。一条命令就能配好并发布一个可用的智能体:

oaa connect ollama                                   # 本地模型,不需要密钥
oaa connect deepseek --key-file ~/.config/deepseek.key
oaa connect openai --key-env OPENAI_API_KEY --model <模型名>

完成后你会得到 agent/assistant——一个带工作区文件工具(list_files、read_file、write_file)的通用助手,以及一条可以直接粘贴运行的 curl。不带目标运行 oaa connect,会列出本机检测到的外部智能体和全部模型预设。

oaa connect <预设> 做了什么

  1. 模型。 本地服务(回环地址):向它请求模型列表(GET <baseUrl>/models,只发往 127.0.0.1),只有一个模型就用它,否则用 --model 指定的那个。没有响应时用中英双语说明:服务没在运行或端口不同,以及怎样用 --base-url 指定。云端服务:模型取自 --model(或预设里唯一的建议值),不会向它发任何请求。
  2. 提供方。 把 localWorker.providers.<名字> 写进 .oaa/config.json(名字为预设名,或 --name)。已有完全相同的条目则跳过;同名但设置不同则拒绝(provider_conflict),绝不覆盖。配置里只存密钥的引用。
  3. 网关。 提供方在网关启动时读取,所以新增提供方需要重启网关。网关是从这个数据目录启动的(oaa quickstart、oaa serve --detach)就由 connect 重启;没有网关在运行就启动一个;端口被别的程序占用(例如桌面应用)则不去动它,提示你自己重启。
  4. 智能体。 发布 examples/assistant.oaa,把线路指向这个提供方和模型(--agent 改名字,--definition FILE.oaa 发布你自己的文件,其中的 default/"configure-your-model" 线路同样会被改写)。同名智能体已是别的引擎或提供方则拒绝(agent_conflict)。
  5. 密钥与调用。 确认 quickstart 的调用方密钥能调用它(否则单独建一把只能调用它的密钥),打印 model 名、Base URL 和一条 curl。

重复运行不会改变任何东西,并沿用同一把密钥。它从不调用模型——云端调用会花钱。加 --test 会经网关发一次最小请求,且只在端点是回环地址时才发。

密钥

密钥绝不通过命令行参数或交互输入传递(会进 shell 历史):

  • --key-env 变量名:配置里只存环境变量的名字。网关进程启动时读取它,所以必须在启动网关的那个环境里设置。 connect 或 oaa serve 从你这个终端启动的网关会继承终端的变量;桌面应用、服务管理器或别人启动的网关不会。变量改了要重启网关。
  • --key-file 文件:配置里存文件的绝对路径(apiKeyFile)。connect 会检查它是普通文件(不接受目录、链接或设备)、不超过 8 KiB、只有一行,且在 macOS 与 Linux 上只有你能读(chmod 600)。网关每次调用时读取,换密钥不需要重启。文件内容从不打印、不写日志、不复制进配置;错误信息里只出现路径。
  • 本地预设默认不使用密钥(noApiKey: true,不发认证头);本地服务启用认证时,须显式指定密钥引用。

本地运行器识别

「本地互联」页面也会识别 Ollama、LM Studio / llmster、llama.cpp、Jan、GPT4All、LocalAI 和 vLLM 的可执行文件与应用包。安装识别不会启动程序、读取聊天或凭据,也不代表模型服务已经运行。已配置的端点标为「已接入」,不冒充安装证据。

点击运行器卡片,在弹窗里检查本机 /v1 地址、选择模型,再「接入并发布」。提供方和 kernel 智能体原子写入 OAA 自身数据库,无需重启即可使用,重启后保留;不改运行器的设置,也不自动创建调用方密钥。新智能体不携带宿主工具,调用与客户端工具仍受原有 API Key 权限约束。同名但不同设置的提供方或智能体直接拒绝,不覆盖。需要认证的服务只保存环境变量名,不保存明文密钥。

POST /v1/local/model-runtimes/probe 接受 runtime、可选 base_url 和 key_env;/v1/local/model-runtimes/connect 还需要 model,可传 provider_name 与 agent。两者均限本机回环直连的宿主级所有者管理员。模型列表检查有大小及超时限制,不发生成请求,区分离线、空列表与需要认证。列表成功只证明协议可达,不等于推理成功或模型能力验证。弹窗提供官方下载和服务设置链接,不会静默安装或启动第三方软件。

命令行同样支持 oaa connect llamacpp、jan、gpt4all、localai、vllm;非默认端口用 --base-url。LocalAI 与 llama.cpp 默认都用 8080,同时运行时须设不同端口。

2026-11-17,官方 Ollama 0.40.16 与 llama.cpp b12475 包已在隔离 macOS 目录解包,均通过 OAA 完成真实 Chat Completions 和 Responses 调用,网关重启后接入配置保留。烟测使用 ggml-org/models 的 26 万参数测试模型,不是指令能力或质量评测;达到小输出上限时 Responses 如实返回 incomplete。scripts/live-local-models.mjs 可对显式指定的端点重复验证,不负责安装或启动运行器。其余本地运行器有协议替身测试,不代表同等真实推理验证。

预设表

下面每一条的端点与差异都对照了该服务的官方文档(2026 年 11 月)。地址写死在代码里,不从网络获取。模型名经常变,预设最多保留一个建议值,--model 永远优先。

预设服务协议Base URL密钥变量预设里写好的已知差异建议模型
ollamaOllama(本地)openai-chathttp://127.0.0.1:11434/v1不需要max_tokens;图片内联(base64)取本地列表
lmstudioLM Studio(本地)openai-chathttp://127.0.0.1:1234/v1不需要max_tokens;不传图片取本地列表
llamacppllama.cppopenai-chathttp://127.0.0.1:8080/v1可选max_tokens;默认关闭图片取本地列表
janJanopenai-chathttp://127.0.0.1:1337/v1可选max_tokens;不发送流式用量;关闭图片取本地列表
gpt4allGPT4Allopenai-chathttp://127.0.0.1:4891/v1可选max_tokens;不发送流式用量;关闭图片取本地列表
localaiLocalAIopenai-chathttp://127.0.0.1:8080/v1可选max_tokens;默认关闭图片取本地列表
vllmvLLMopenai-chathttp://127.0.0.1:8000/v1可选max_tokens;默认关闭图片取本地列表
openai-compatible任意 OpenAI 兼容地址openai-chat--base-url--key-env/--key-file,否则无密钥max_tokens;不要流式用量;不传图片--model
openaiOpenAIopenai-responseshttps://api.openai.com/v1OPENAI_API_KEY无--model
anthropicAnthropicanthropic-messageshttps://api.anthropic.comANTHROPIC_API_KEYanthropic-version: 2023-06-01claude-sonnet-5-5
gemini-apiGoogle Gemini APIgemini-generatehttps://generativelanguage.googleapis.com/v1betaGEMINI_API_KEYx-goog-api-key 请求头--model
openrouterOpenRouteropenai-chathttps://openrouter.ai/api/v1OPENROUTER_API_KEYmax_tokens--model
deepseekDeepSeekopenai-chathttps://api.deepseek.comDEEPSEEK_API_KEYmax_tokensdeepseek-flash
moonshotMoonshot(Kimi)openai-chathttps://api.moonshot.cn/v1MOONSHOT_API_KEYmax_tokens;不要流式用量;不传图片--model
zhipu智谱(BigModel)openai-chathttps://open.bigmodel.cn/api/paas/v4ZHIPU_API_KEYmax_tokens;不要流式用量;不传图片glm-5.3
siliconflow硅基流动openai-chathttps://api.siliconflow.cn/v1SILICONFLOW_API_KEYmax_tokens;不要流式用量;不传图片--model
groqGroqopenai-chathttps://api.groq.com/openai/v1GROQ_API_KEYmax_completion_tokens(它那里 max_tokens 已弃用);不要流式用量--model
togetherTogether AIopenai-chathttps://api.together.ai/v1TOGETHER_API_KEYmax_tokens;不要流式用量--model
mistralMistral AIopenai-chathttps://api.mistral.ai/v1MISTRAL_API_KEYmax_tokens;不要流式用量;不传图片--model

「不要流式用量」指文档没有承诺 stream_options.include_usage,预设就不发它(streamUsage: false);运行照常,只是不报告 token 数。「不传图片」指预设关掉图片(imageInput: "none")。本地运行器是否支持图片取决于模型与后端;验证视觉模型后再显式设置 imageInput。

预设名不会与外部智能体重名:gemini 仍是 Gemini CLI(ACP),kimi、qwen、glm 仍是这些工具的 ACP 预设,所以这里用 gemini-api、moonshot、zhipu。

未收录: 阿里云百炼(通义千问)。它现行文档给出的端点带有你自己的业务空间 ID (https://{WorkspaceId}.<地域>.maas.aliyuncs.com/compatible-mode/v1),没有固定地址可写进预设;而且文档说明工具调用暂时不能与 stream=true 同时使用,内置智能体总是流式调用。如果你的模型支持流式工具调用,可以用 openai-compatible --base-url … 填你的业务空间地址。

提供方配置项

localWorker.providers.<名字>(以及执行节点的 providers)接受:

字段含义
kindopenai-chat、openai-responses、anthropic-messages、gemini-generate
baseUrl端点;非回环地址必须是 https
apiKeyEnv存放密钥的环境变量(缺省 OPENAI_API_KEY)
apiKeyFile新增。存放密钥的文件;每次调用时读取;优先于 apiKeyEnv
noApiKey新增。true:端点不需要密钥,不发认证头
maxTokensFieldmax_completion_tokens(缺省)或 max_tokens
streamUsage新增。false:不发 stream_options.include_usage
imageInputnone、inline 或 url(见 images.md)
preset新增。条目来自哪个预设(仅作说明)
byok、timeoutMs、anthropicVersion不变

oaa models

oaa models [--dir .oaa] [--check] [--json]

列出已配置的提供方:协议、端点、密钥从哪里来以及能否解析(有网关在运行时按网关进程的视角,否则按当前终端)、端点是否响应、有哪些模型、哪些智能体在用它。回环地址自动探测;云端端点只在加 --check 时才联系,而且只请求模型列表接口(不生成内容,不产生 token 费用)。

运行失败时

错误信息会点名提供方、它的端点以及该改什么:

错误码原因怎么改
model_not_configured网关进程里密钥引用解析不了设置变量后重启,或修好密钥文件
upstream_auth_failedHTTP 401/403密钥不对、地域不对或缺权限
upstream_model_not_foundHTTP 404 或「模型不存在」改正模型名(oaa models --check)或 baseUrl
upstream_incompatibleHTTP 400/422 且点名某个字段信息里会写明要改的配置:maxTokensField、streamUsage、imageInput,或换支持工具的模型
upstream_rate_limitedHTTP 429稍后重试或检查额度

上游的响应内容只用来判断失败类型,从不复制进调用方看到的错误信息。

智能体模型目录与编排

新增的同 Agent 编排、仅规划模式、动态评测和 EverythingACP 导入见智能 Agent API。

GET /v1/agents/models?agent=<id> 与 MCP oaa_list_models 提供有大小上限的运行时目录。后续 offset 分页必须携带 revision。它与按版本固定的静态声明线路分开。密钥可用 connection.audience:"external" 标记不可信调用者,不能授予宿主执行、所有者全量数据、管理权限或私有智能体执行权限;控制台将它与本人可信密钥区分。

外部智能体不需要再提供一把模型服务密钥。OAA 查询智能体自己的程序接口:Antigravity models、Codex app-server model/list、Claude Agent SDK supportedModels() 与 ACP 会话的模型配置。不拦截上游流量,也不提取智能体的登录凭据。DSH 的显式映射标为已配置,不是账号模型发现;不支持的适配器明确返回不支持。

所有者管理员使用 GET /v1/local/backends/{engine}/models(adapter/name 需要 URL 编码),加 ?refresh=true 主动刷新。目录默认缓存五分钟,单次发现限时十五秒;私有磁盘缓存重启后作为过期证据保留。刷新失败保留上次真实列表,不用内置模型名补齐。ready 只表示发现成功,不代表每个模型的额度或真实任务都验证过。

POST /v1/agents/publish-native 接受下面的可选字段(智能体包定义里使用 modelPolicy 而非 model_policy):

{
  "id": "agent/my-native",
  "engine": "antigravity",
  "models": ["default"],
  "model_policy": {"mode": "discover"},
  "access": {"modes": ["managed", "hybrid"], "defaultMode": "managed", "approval": "owner", "trust": "private"},
  "orchestration": {"enabled": true, "helpers": []}
}
  • 自动跟随智能体目录,allow 可限制开放范围;声明的默认模型与线路也必须在该范围内。没有这些字段的存量发布保留原行为。
  • 标准模型列表提供 agent/name、agent/name@<线路 ID> 和 @fast、@best、@eco。使用列表返回的标识,不猜账号模型名称。明确选择具体模型时不启动编排,也不暗中替换模型。
  • 创建密钥支持 connection: {toolMode, allowedModes, models}。models 按智能体 ID 指定默认选择,是偏好而不是模型权限限制,客户端显式选择优先。工具权限仍是上限;hybrid 授权也允许任一更窄的执行位置。
  • 编排决策、分析与复核都通过已接入智能体完成。系统固定本次准入模型池、校验计划的智能体和模型授权,最多并行两个独立分析,主执行串行,并进行有上限的复核与修正。帮手必须同时得到发布者和调用密钥授权,不要求组合发布产品。
  • 规划、分析和复核使用限制工具的推理路径,请求中带上完整输出 schema,证据以有大小上限的文本片段传入,不授予这些阶段任意文件访问能力。目前支持内核智能体、Antigravity 的单次会话拒绝规则和 Claude SDK 的空工具模式;其他原生/适配器入口在实现可执行的限制前不提供多模型规划。这不等于给外部进程加上 OS 沙箱。
  • 默认上限:智能八阶段/十五分钟,速度三阶段/五分钟,质量十二阶段/三十分钟,经济四阶段/十分钟。发布的 maxStages、timeoutMs 可覆盖;简单任务可以只用一个模型。这是外层执行上限,不是上游 token 或金额的硬保证。
  • 选路使用观测数据和明确声明的 costTier、speedTier、qualityTier,不再用模型名字里的片段猜测价格与质量。没有证据就保持未知;oaa.review_source: "agent" 区分智能体复核与独立验证。
  • 计划、子运行引用、确认结果与用量进入检查点,结果未知的外部写入不自动重放。断线不取消已接受任务。新发布切换模型时传递可迁移历史和文件,不冒充共享原生隐藏状态;没有会话标识的客户端使用其提供的历史,不猜测合并会话。

OAA-Lang 会保留 model_policy = {...}、access = {...}、orchestration = {...} 与线路 quality=...。节点新增字段按 model-catalog-v1、agent-policy-v1 协商;不能执行这些策略的旧节点不会被选中。

控制台

发布智能体 → OAA-Lang 2.0 里有「模型提供方」下拉框,列出已配置的提供方;选中后会改写源码里每条 route 的提供方。内置智能体的卡片会显示它用的提供方;网关进程读不到密钥时以需要处理的颜色标出。

安全

  • --base-url 只接受 http 与 https,不能带用户名密码、查询串或 #;非回环地址必须 https。不提供放宽开关:网关的模型驱动本来就拒绝明文 http 的远程端点。
  • 预设里的地址是代码的一部分,不从网络下载。
  • security.profile: public 时行为不变:提供方仍是管理员配置。

这些预设对照官方文档核实,只在假服务上实际跑过。真实服务可能变化;某个服务失效时,oaa models --check 和上面的错误码会告诉你该改哪一项。

本页内容