提供程序目录

ZeroClaw 附带的每个模型提供商系列。针对每一项：配置结构、关于身份验证和端点行为的说明，以及在 [providers.models.<type>.<alias>] 下使用的槽位键。

有关通用字段（api_key、uri、model 等）及其解析顺序，请参阅配置。

以下示例使用 home 作为别名，以强调别名部分是由操作员自行选择的，可以使用任何合适的名称（work、personal、cn、prod……）。在 agent 中通过 model_provider = "<type>.<alias>" 来引用它。

原生

Anthropic / Claude: slot `anthropic`

支持 claude setup-token 为 Claude Max 生成的 Console API keys 和 tokens。这两种凭据都位于 canonical anthropic slot 的 api_key 字段中；Quickstart 将它们作为 api_key 和 setup_token 选项公开。流式传输、工具调用、视觉和推理均受支持。自定义 endpoints（兼容 Anthropic 的 proxies，例如 Z.AI 的 Anthropic API）也放在这个 slot 上：设置 uri 进行覆盖。

OpenAI：插槽 `openai`

GPT-4o、GPT-5、o-series 推理模型。当推理内容以流式传输时，它会承载在由 TextDelta 包装的 StreamChunk 的可选 reasoning 字段中；请参阅流式传输。

OpenAI Codex：启用 `requires_openai_auth = true` 的 `openai` 槽位

OpenAI Codex 订阅认证位于 openai 槽位中。设置 wire_api = "responses" 可将请求路由至 POST /v1/responses，设置 requires_openai_auth = true 可使用 Codex 订阅登录（来自 Codex CLI 自身的 ~/.codex/auth.json），而非条目中的 api_key 字段。订阅路径不会读取 OPENAI_API_KEY；该变量仅适用于按量计费的 openai API 密钥模式。有关凭据模型，请参阅 Provider Configuration → OAuth and subscription auth。

Ollama：插槽 `ollama`

通过 Ollama 原生 /api/chat 进行本地推理。通过 format 实现基于 Schema 的结构化输出。无需 API 密钥。

Bedrock：插槽 `bedrock`

Gemini：插槽 `gemini`

Google 的 Gemini API。支持视觉和预执行的接地搜索（有关 PreExecutedToolCall 事件，请参阅流式传输）。

Gemini CLI：插槽 `gemini_cli`

通过 shell 调用 gemini CLI；使用该 CLI 现有的身份验证。

Grok Build CLI：槽位 `grok_cli`

通过文档所述的 grok agent stdio ACP 接口调用 Grok Build CLI，并默认使用 CLI 的登录缓存。运行 grok login，或使用下方所示的显式 API 密钥桥接。不会使用类型化别名 api_key；除非该别名选择启用，否则也不会继承环境中的 XAI_API_KEY，因此身份验证仍由 Grok CLI 负责。这是唯一的传输方式：通过以换行分隔的 JSON-RPC，依次执行 initialize → authenticate → session/new → session/prompt。大小提示词都会通过 stdin 传输，绝不会出现在 argv 或提示词文件中。

文档所述的 ACP 集成和默认参数配置已针对 Grok Build CLI 0.2.118（ACP advertise/live 探测）进行了验证，较早的基线版本为 0.2.111。将外部 CLI 的升级视为兼容性变更，并在部署前重新验证 grok agent stdio。

ACP 视觉/图像输入（当前 Grok Build 行为）

Grok Build CLI（已检查至 0.2.118）在 ACP initialize 中仍会声明 promptCapabilities.image = false。这并不是任一方的环境变量覆盖：ZeroClaw 从不会重写 Grok 的声明。ZeroClaw 唯一的控制项是共享的按别名配置字段 vision。

层	`0.2.118` 中的行为
ACP 通告	`promptCapabilities.image = false`
默认 `grok_cli`	`vision` 未设置 → ZeroClaw 将该别名视为非视觉模型；图像标记保留为文本
`vision = true`	ZeroClaw 会在别名上报告视觉能力，并发送 ACP `{type: image, data, mimeType}` 块（不会更改 Grok 的能力声明）
模型识别	实时探测：`session/prompt` 接受图像块（没有协议错误），但代理的回答就像没有收到图像一样

[providers.models.grok_cli.default]
model = "grok-4.5"
working_directory = "/srv/zeroclaw/grok-workspace"
# 仅供可选实验：即使声明 image=false，也发送 ACP 图像块。
# 并不能让 Grok Build 0.2.118 稳定地看到或描述图像。
# vision = true

不要为生产环境的 grok_cli 别名设置 vision。在已部署的 CLI 同时声明 image = true，且实时冒烟测试显示模型正在使用图像内容之前，不要将需要实际图像理解的频道附件路由到 grok_cli。满足这一条件后，移除任何临时的 vision = true 启用项，并重新评估 ZeroClaw 是否应遵循声明位，而不是本地覆盖项（GrokCliModelProvider::acp_prompt_content）。

Ubuntu 24.04：在 `bwrap` 需要用户命名空间时保留 Grok 沙箱

部署 Grok Build 0.2.112 或更高版本时，请验证目标主机上的 ACP 初始化。在设置了 kernel.apparmor_restrict_unprivileged_userns=1 的 Ubuntu 24.04 主机上，Grok 可能会在 ACP 初始化之前退出，并显示 bwrap: setting up uid map: Permission denied。这是主机沙箱设置失败，而不是 ACP、stdout 或身份验证失败。

保留 ZeroClaw 默认的 --sandbox strict（或显式的 workspace 配置文件），并仅授予实际的 Grok 可执行文件创建用户命名空间的权限。这是主机管理员执行的更改；它保留了全局用户命名空间限制，不会关闭 Grok 的沙箱。

readlink -f "$(command -v grok)"

创建 /etc/apparmor.d/grok-build-userns，将占位符替换为该绝对路径：

abi <abi/4.0>,

include <tunables/global>

profile grok-build-userns /absolute/path/to/grok flags=(unconfined) {
  userns,
}

然后加载它并验证配置文件已激活：

sudo apparmor_parser -r /etc/apparmor.d/grok-build-userns
sudo aa-status | grep grok-build-userns

flags=(unconfined) 是 Ubuntu 针对每个可执行文件的 AppArmor 例外机制：它会向指定的 Grok 二进制文件授予 userns，但不会为其添加 AppArmor 文件规则。Grok 自身请求的沙箱仍保持启用状态，主机范围的用户命名空间限制也仍保持启用状态。如果 Grok 还需要 AppArmor 文件限制，请使用完全受限的组织专用配置文件。由于自更新可能会更改下载的可执行文件路径，请在每次 Grok 更新后解析路径并重新加载此配置文件。

不要仅仅为了避免此错误而使用 --sandbox off：这会禁用 Grok 的沙箱。不要在系统范围内禁用 kernel.apparmor_restrict_unprivileged_userns。xAI 的文档说明了 Landlock 用于正常的 Linux 沙箱，并说明 bubblewrap 仅用于自定义的拒绝读取配置文件；如果在没有自定义的非空 deny 列表的情况下发生此问题，请将版本、确切错误、沙箱配置文件以及非机密的主机/AppArmor 诊断信息报告给 xAI。

max_acp_stdout_bytes 限制单次请求期间从 Grok ACP 子进程读取的所有 stdout，包括协议帧和原生工具更新。默认值为 4 MiB；当经过审核的启用工具的工作负载需要更大的有界预算时，可按别名进行设置。

[providers.models.grok_cli.default]
model = "grok-4.5"
working_directory = "/srv/zeroclaw/grok-workspace"
env_passthrough = ["XAI_API_KEY"]
# 可选：默认为 4 MiB；可接受范围为 1-64 MiB。
max_acp_stdout_bytes = 8388608

在启动 ZeroClaw 前，将 XAI_API_KEY 导出到守护进程环境中。ACP 客户端仅在该名称列于 env_passthrough 中，且进程环境在 子进程生成 时存在非空值的情况下，才会选择 xai.api_key（不会将其快照到长期存在的提供程序句柄中）。类型化别名 api_key 仍会被拒绝：这是有意设计的进程环境桥接，而不是第二个 Config 机密字段。值不会写入提供程序 TOML；未来的类型化 Config 桥接可以在配置时加载同一名称，而无需改变操作界面。

必须提供一个已存在的绝对 working_directory。它会被规范化，并同时用作子进程 cwd 和 ACP 会话边界，因此提供程序绝不会回退到守护进程 cwd。可选的 binary_path 用于选择不在 PATH 中的二进制文件。别名 timeout_secs 限制协议读写时长（默认为 600 秒）。

子进程环境会在启动前被清空。内置允许列表中的进程运行时、区域设置、代理和 CA 变量仍然可用；除非提供商别名在 env_passthrough 中列出其他名称，否则这些名称都会被阻止。此字段用于显式的 XAI_API_KEY 身份验证桥接，以及显式启用的 Grok 工具所需的环境变量，例如云 CLI 凭据。值会在启动时从 ZeroClaw 进程环境中读取，不会存储在提供商配置中。默认列表为空。请将列表保持精简，因为其中列出的每个机密都会暴露给 Grok 以及为该别名启用的任何工具。其他提供商所有的 XAI_* 名称和所有 GROK_* 名称都会被拒绝。Grok 发现的用户和项目配置，以及别名的 extra_args，共同决定 Grok 工具策略。

默认 argv 会添加 --no-auto-update、--no-plan、--sandbox strict、--permission-mode dontAsk 和 --tools ""。默认情况下，ACP 客户端会拒绝权限请求。当请求提供 reject_once 选项时，客户端会选择该选项，而不是取消整个代理轮次；否则会取消该请求。请求的工具仍会以拒绝方式失败，而 Grok 可以处理该拒绝并生成最终答案，或使用其策略允许的操作重试。

显式配置了 --always-approve、--dangerously-skip-permissions、--yolo 或 --permission-mode=bypassPermissions 的别名会改变无头 ACP 响应策略：客户端选择请求中的 allow_once 选项。它绝不会替换为 allow_always，并会在请求的 allow_once 选项不存在时取消操作。此批准仅适用于当前权限请求；Grok 的权限规则和当前启用的 OS 沙箱仍可能拒绝或限制该操作。

[providers.models.grok_cli.ops]
working_directory = "/path/to/agents/ops/workspace"
extra_args = [
  "--tools=run_terminal_cmd",
  "--permission-mode=bypassPermissions",
]

将这些绕过标志视为授权，允许 Grok 在该别名上执行所有请求支持的工具，而无需经过人工审批往返。其他权限模式（包括 acceptEdits）不会启用 ACP 自动批准。Grok 会在向 ACP 客户端询问之前，评估 CLI --allow / --deny 规则以及发现的用户/项目权限配置。这些配置层面属于受信任的操作员策略：匹配的 allow 规则可以预先授权某个工具，使 ACP 客户端永远不会看到权限请求；项目 MCP 服务器、插件或钩子也可能添加功能。为频道代理使用专用且经过审核的 working_directory。

当 allow 规则未预先授权该工具时，Grok 仍会发送 session/request_permission，而 ZeroClaw 的默认“拒绝一次”策略会使工具失败并关闭。实际上，这对默认 --sandbox strict 下的 shell/execute 工具很重要：在当前 Grok Build 中，CLI --allow=Bash(...) 规则仍可能将请求升级到 ACP 主机，因此启用工具的 shell 别名应设置显式绕过标志（--always-approve / --permission-mode=bypassPermissions），或将 allow 规则与 Grok 能够在无需主机批准的情况下预授权的 sandbox 配置文件配对（例如 --sandbox=workspace）。使用匹配的 --allow 配置的只读工具授权（例如 --tools=Read,Grep）仍是范围更窄的选择加入方式。

操作员还可以通过别名 extra_args 授予工具访问权限，或放宽沙箱/权限策略；这两种机制都是显式选择启用更宽松子进程边界的方式。transport、prompt、model、session、cwd 和 update 标志仍由提供程序负责，并且在 extra_args 中会被拒绝。位置参数和短参数也会被拒绝。已知的取值选项可接受 ["--flag", "value"] 或 --flag=value 中的任一种；未知选项形式则要求使用内联形式，以免它们消耗末尾的 ACP 命令。

Grok 可能会在计划、工具调用或权限请求之前以 agent_message_chunk 的形式发送进度。服务提供方会在这些 ACP 边界处丢弃前一个消息片段，仅返回最新的回答片段，因此规划或收集工具信息的叙述不会作为频道回复传递。显式指定 --no-plan 还会使默认的一次性频道别名不进入 Grok 的计划模式；工具/MCP 配置仍属于由操作员控制的能力。

ACP stdout 帧、聚合 stdout、助手文本和 stderr 处理在子进程运行期间均有上限。stderr 会被持续读取，但其内容绝不会被存储、记录日志或返回。对外提供的 provider 错误保持稳定，不会回显由子进程控制的协议自由文本。在每次单次请求之后（无论成功、超时、取消还是协议错误），ZeroClaw 会在 Unix 上终止子进程所属的 进程组，或在 Windows 上终止 Job Object，并回收直接子进程。这能处理普通的后代进程；在 Unix 上，创建新会话或新进程组的进程可能绕过进程组终止。Windows Job Object 的覆盖在 CI 中通过编译检查，但并未在每台 Linux 开发主机上完整执行。

推荐模式：默认频道聊天机器人

为消息代理使用一个专用的提供方别名（例如 agents.default）。默认别名不会授予 Grok 任何内置工具。Grok 仍会加载其常规用户和项目配置，因此请使用一个专用工作区，并审查其中的权限规则、MCP 服务器、插件和钩子是否符合该渠道的信任边界。对于经操作员批准的编码/运维代理，请使用单独的别名和工作区。

回复意图预检查（分类器）： ZeroClaw 会在完整代理循环之前执行一次简短的 REPLY / NO_REPLY[*] 分类。对于此预检查，优先使用稳定的聊天补全 API（例如 HTTP/OAuth xai 槽位，或任何其他非 CLI 模型别名），并且仅将 grok_cli 用于 model_provider（完整回答）。CLI 代理后端经常会输出规划性文字，而不是单个哨兵令牌；这些文字可能会作为频道消息发送（“保持沉默”/“不回复 Slack”）。空的 classifier_provider 会复用 model_provider：这对 API 模型没问题，但不适用于 CLI 频道机器人。ACP 频道会完全跳过分类器。

# 完整回答：ACP、严格沙箱、无内置工具、经过审核的 Grok 配置
[providers.models.grok_cli.default]
model = "grok-4.5"
binary_path = "/home/you/.grok/bin/grok"
working_directory = "/path/to/agents/default/workspace"

# REPLY / NO_REPLY 预检查 - API（格式稳定）。如果已有现成的 xAI
# HTTP 别名，请复用；不要将其指向 grok_cli。
[providers.models.xai.default]
model = "grok-4.5"
# uri / auth 按照常规 xAI 提供商设置（OAuth 会话或 api_key）

# 运维/编码代理：明确的策略和工具选择启用
[providers.models.grok_cli.ops]
model = "grok-4.5"
binary_path = "/home/you/.grok/bin/grok"
working_directory = "/path/to/agents/ops/workspace"
env_passthrough = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
# 只读工具：匹配的 --allow 可在无需 ACP 审批的情况下预先授权。
extra_args = ["--tools=Read,Grep", "--allow=Read", "--allow=Grep"]

# 支持 Shell 的运维别名：可以绕过 ACP 审批，或者将 allow 与
# Grok 预授权的沙箱配置搭配使用（workspace 是常见选择）。
[providers.models.grok_cli.ops_shell]
model = "grok-4.5"
binary_path = "/home/you/.grok/bin/grok"
working_directory = "/path/to/agents/ops/workspace"
extra_args = [
  "--tools=run_terminal_cmd",
  "--allow=Bash(printf *)",
  "--sandbox=workspace",
]

[agents.default]
model_provider = "grok_cli.default"
classifier_provider = "xai.default"
channels = ["slack.default"]   # 示例

[agents.dependabot]
model_provider = "grok_cli.ops"

层	在哪里	目的
回复预检查	`classifier_provider` → API 别名（例如 `xai.default`）	仅使用 REPLY / `NO_REPLY[*]`；避免 CLI 将思考文本作为消息正文
完整答案	`model_provider` → `grok_cli.default`	Grok Build ACP；仅通过 stdin 提示
操作系统沙箱	默认使用 `--sandbox strict`（或通过 `extra_args` 覆盖）	读取 CWD + 系统路径；写入 CWD + `~/.grok` + tmp；Linux 上阻止子进程网络访问。内置规则不是永久的凭据边界 - 对机密信息使用自定义 `deny`
应用权限	空的内置工具集 + ACP 默认采用故障关闭模式	显式绕过标志选择 `allow_once`；发现的 Grok 规则也可能预先授权已配置的工具
渠道投递	ZeroClaw `thread_replies` / 频道配置	单一的线程内回复路径
可选门控	Slack `mention_only` + `strict_mention_in_thread`	在代理之前丢弃未提及的群组/线程流量（参见 Slack）；不依赖于分类器

将面向频道的别名保持为默认值，并为其分配专用且经过审核的工作区。Grok 发现的权限规则、MCP 服务器、插件和钩子，以及 extra_args 中的权限/沙箱/工具标志，均属于受信任的操作员策略，并可能扩大子进程边界。

Grok CLI OS 沙箱（如何从 ZeroClaw 使用它）

这是 Grok Build 的进程沙箱（应用于 grok 子进程的 Landlock / Seatbelt / seccomp）。它不是 [risk_profiles.*.sandbox_*] 中的 ZeroClaw 工具沙箱：后者会在原生工具调用之后包装 ZeroClaw 工具。如果操作员将某个提供商别名配置为使用 Grok 工具，那么 Grok 的 --sandbox 就是该工作实际生效的隔离机制。另请参阅沙箱，了解 ZeroClaw 的风险配置文件沙箱。

ZeroClaw 始终提供显式的沙箱标志。默认值为 strict。在该提供商别名的 extra_args 中设置 --sandbox=<profile> 以选择其他配置文件；环境中的 Grok 配置或 GROK_SANDBOX 无法静默放宽提供商控制的默认值。

项目 .grok/config.toml 可包含 MCP / 插件 / [permission]。Grok 将该文件加载为受信任的操作员策略；匹配的允许规则可能会授权工具，而无需 ACP 权限请求。它本身不会选择活动的沙箱配置文件。配置文件名称和自定义配置文件内容可存放在项目 <workspace>/.grok/sandbox.toml 中；通过 extra_args 传递 --sandbox=<name> 以启用该配置文件。

内置配置文件（来自 Grok 的沙盒文档）：

配置文件	文件系统读取	FS 写入	子进程网络（Linux）	典型用法
`off`（默认）	不受限制的	不受限制的	不受限制的	完全访问权限
`workspace`	到处	当前工作目录 + `~/.grok` + 临时目录	允许	日常编码
`只读`	到处	`~/.grok` + 仅 tmp	已阻止	审查何时可以进行广泛读取
`strict`	CWD + 系统路径	当前工作目录 + `~/.grok` + 临时目录	已阻止	默认频道聊天机器人（推荐）
`devbox`	到处	树的大部分	允许	一次性虚拟机

子进程网络阻断仅适用于 Linux 上的 shell 子进程；进程内 Grok 工具（LLM、内置 Web 搜索）仍需要网络。对于消息机器人，优先使用 strict，将默认文件系统写入范围缩小到代理工作区和 Grok 运行时路径。内置配置文件不是永久的凭据边界：xAI 的沙箱文档警告称，诸如 ~/.ssh 之类的路径无法保证受到内置配置文件的保护，并建议为机密使用带有内核强制执行的 deny 列表的自定义配置文件。仅当代理必须读取工作区之外的内容而不写入项目文件时，才使用 read-only。

自定义配置示例（在工作区中定义，从 ZeroClaw 中选择）：

# <agent-workspace>/.grok/sandbox.toml
[profiles.channel-bot]
extends = "strict"
# 可选的内核拒绝路径（非空时在 Linux 上需要 bubblewrap）：
# deny = ["**/.env", "**/*.pem"]

# ZeroClaw config.toml
[providers.models.grok_cli.default]
working_directory = "/path/to/agents/default/workspace"
extra_args = ["--sandbox=channel-bot"]

每个代理的沙箱：使用不同的提供程序别名，并为其指定不同且明确的 extra_args 以及专用工作目录。让通道别名保持严格/无内置工具的默认设置，检查每个工作区中发现的 Grok 配置，并让每个代理指向相匹配的 model_provider 别名。

Azure OpenAI：插槽 `azure`

resource、deployment 和 api_version 存放在此类型化配置中，它们不会从环境变量读取。

Copilot：插槽 `copilot`

使用 GitHub Copilot 订阅进行 agent 推理。身份验证使用从 GitHub 获取的 Copilot OAuth 令牌。

Telnyx：插槽 `telnyx`

面向语音的 AI 端点。与 clawdtalk 通道配对，用于实时 SIP 通话。

KiloCLI：插槽 `kilocli`

通过 KiloCLI 进行本地推理。

Kilo AI Gateway：插槽 `kilo`

[providers.models.kilo.home]
model   = "anthropic/claude-sonnet-4-6"
api_key = "..."
# endpoint = "gateway"  # 默认 → https://api.kilo.ai/api/gateway

通过 Kilo AI Gateway 访问的 Cloud API。采用 Bearer-token 鉴权，提供多个模型层级（free、balanced、pro）。/models 端点是公开的（PUBLIC_MODEL_LISTING），因此无需凭据即可列出模型。由于它是实时查询的，它也是将定价信息带入成本费率编辑器的数据来源。共享的 models.dev 目录（kilo 键）仅在实时端点不可达时作为后备，且不包含定价信息。

命名迁移： kilo 现在指代此网关提供程序。KiloCLI 子进程提供程序保留其 kilocli 槽位（同义词 kilo-cli）。如果你之前在 kilo 简写下配置了 CLI 提供程序，请改用 kilocli。

ZeroRouter：槽位 `zerorouter`

[providers.models.zerorouter.gateway]
model   = "anthropic/claude-sonnet-5"
api_key = "..."   # ZeroRouter 密钥（前缀为 `zcr_`）；或从环境变量注入
# uri = "http://localhost:8080/v1"  # 自托管或本地路由器；托管默认值可省略

OpenAI 兼容的 LLM 网关；使用 Bearer 令牌进行身份验证。ZeroRouter 目前处于测试阶段。该槽位默认指向公共托管部署 https://zerorouter.ai/v1，因此无需任何配置即可进行模型发现。ZeroRouter 也支持自托管（AGPL）；若要连接到你自己的路由器，无论是在本地 http://localhost:8080/v1 还是其他位置，都需要显式设置 uri。在一个路由器上签发的密钥无法在另一个路由器上通过身份验证，因此 api_key 必须来自 uri 所指向的部署。

除了该插槽支持的 chat-completions 协议外，ZeroRouter 还提供 OpenAI Responses API 的入站接口（POST /v1/responses），因此，使用 Responses 协议的客户端（例如配置了 wire_api = "responses" 的 Codex CLI model_provider）可以直接指向同一部署并使用同一密钥。

/v1/models 端点是公开的（PUBLIC_MODEL_LISTING），因此模型列表及其提示词/补全定价会从路由器本身实时获取，无需凭据；由于它是实时查询的，因此定价会通过它传递到成本费率编辑器中（此模型系列没有 models.dev 或 OpenRouter 回退）。推理确实需要密钥：可以直接设置 api_key，也可以像注入其他提供商密钥一样从环境中注入（有关 api_key 的解析顺序，请参阅 Configuration）。

**不提供内置登录。**此预设仅通过标准的类型化 api_key 路径配置提供商；不会添加设备流登录、OAuth 或提供商特定的凭据存储。设置 api_key（或通过环境变量注入该值）即可运行推理。

所有插槽

每个规范槽位、其默认端点、是否在本地运行，以及其完整的配置字段集，均由提供商注册表和配置架构生成。点击槽位可展开其字段；点击字段可查看设置方式。固定条目显示规范默认值。operator required 表示该别名需要端点输入，例如 Azure 资源和部署，或 custom uri。dynamic / resolved at runtime 端点可能取决于凭据、区域、发现过程或运行时状态，因此不一定需要 uri。基于 CLI 的提供商使用其本地命令。

共享字段

每个提供程序槽位都接受这些字段。各提供程序特有的额外字段在下方分别列出。

api_key 🔑 secret · default —

此 model_provider 的密钥 API 令牌。请从 model_provider 的控制台获取（OpenAI platform、Anthropic console、OpenRouter keys 页面等）。尽可能通过操作系统密钥环存储；切勿直接将其提交到 config.toml 中。

将它放置在任何表面上：

Keyboard shortcuts

ZeroClaw Docs