第2章 Omnigent 配置指南：Copilot 认证与 GitHub Enterprise 设置

配置 从受支持的 Harness 列表中选择一个 harness id， 然后配置其所需的任何认证或启动设置。 GitHub Copilot Copilot harness 通过 Copilot SDK（需安装 copilot 扩展）运行 GitHub Copilot。你可以使用 omni copilot 简写启动，或在 omni run 中明确指定 harness： omni copilot # 下方命令的简写 omni run --harness copilot

omni copilot 会原样转发所有 omni run 选项，因此像 -p "review the last commit" 或 --model 这样的参数与 omni run 中的行为一致。 由于该简写始终使用 Copilot harness，向它传递 --harness 会导致使用错误——若要 选择其他 harness，请使用 omni run --harness 。以这种方式启动的会话的 恢复提示会打印标准的 omni run --harness copilot 形式。omni --help 仅在 安装了 Copilot SDK 时才会在 Harnesses 下显示 copilot，这与 cursor 行跟随其 SDK 扩展的方式相同。 Authentication Copilot harness 使用具有 Copilot 访问权限的 GitHub token 进行认证。Omnigent 按以下顺序解析第一个已设置的来源：

COPILOT_GITHUB_TOKEN、GH_TOKEN 或 GITHUB_TOKEN 环境变量。 你通过 omnigent setup → configure harnesses → Copilot 存储的 token。 你的 GitHub CLI 登录——如果你已运行 gh auth login，Omnigent 会直接向 gh 请求 token（gh auth token），因此已登录用户无需在 setup 中粘贴任何东西即可就绪。

注意：gh 回退机制运行 gh auth token，因为 Copilot CLI 仅通过从 ~/.config/gh/hosts.yml 读取 oauth_token 来获取 gh 登录信息——但当 gh 将 token 存储在操作系统密钥链中时（macOS 上的默认行为）， 该文件不存在。直接询问 gh 在所有平台上都有效。 GitHub Enterprise 主机 通过 GitHub Enterprise（数据驻留） 实例访问 Copilot 的组织需要将认证和 API 调用指向其自身的主机名，而非 github.com。通过 omnigent setup → configure harnesses → Copilot → Set GitHub Enterprise host 设置（同一菜单允许你修改或 清除该设置），或直接编辑 ~/.omnigent/config.yaml： copilot: github_host: acme.ghe.com 提供纯主机名；粘贴的 https:// 协议或尾随斜杠会自动 去除。设置后，Omnigent 会将其作为 COPILOT_GH_HOST 环境变量转发给 捆绑的 Copilot CLI，并获取该主机对应的 gh token。 未设置主机时，Copilot 使用默认的 github.com。 Grok Build Grok Build（xAI 的 grok CLI）作为内置 harness 提供，id 为 grok （别名 grok-build）。底层它通过 Agent Client Protocol 驱动 grok agent stdio — Omnigent 渲染其 流式输出、推理和工具卡片，并将其权限请求通过你的上下文策略路由， 类似于 下方的通用 acp harness。区别在于它是内置的：你直接选择 grok harness id，而不是注册一个启动命令。 omni run --harness grok

与通用 ACP agents 类似，Grok Build 自带其自身的认证和模型 — Omnigent 不存储凭据，并且 /model 选择会被提前拒绝 （而不是静默丢弃），因此它始终运行其账户默认模型。若要固定某个模型， 请配置一个 acp: agent，其命令传递 grok CLI 自身的 model 参数。先安装 CLI 并通过 xAI 登录： curl -fsSL https://x.ai/cli/install.sh | bash grok login --device-auth # xAI OAuth（支持设备代码）

使用供应商登录而非 API key。内置 grok 行没有 env_passthrough，且 XAI_API_KEY 不在 host-to-runner 凭据允许列表中，因此在 shell 中导出它无法到达 agent。若需要 key 路径，请显式传递 OMNIGENT_RUNNER_ENV_PASSTHROUGH=XAI_API_KEY，或配置一个 声明该透传的 acp: agent。 Devin Devin（Cognition）作为内置原生 TUI harness 提供，id 为 devin-native。omni devin 在 runner 拥有的面板中启动常驻 Devin CLI， 并将其镜像到 Omnigent 对话中，因此你在原生 体验之上获得了上下文策略、审批卡片、恢复、成本 跟踪，以及 Devin 的 sub-agents 作为子会话。 curl -fsSL https://cli.devin.ai/install.sh | bash devin auth login omni devin

Devin 自带其自身的认证 — Omnigent 不存储凭据。CLI 写入其 自身的凭据文件并在启动时读回，且 devin auth status 是 实时探测，因此 omni setup 报告真实的登录状态。 审批以两种方式呈现：Omnigent 策略对每个请求、工具调用和 工具结果进行门控，且 Devin 自身的同意提示会重新发布为 Chat 审批 卡片（可在 web UI 或嵌入式终端中回答）。 Model and effort Devin 将推理努力编码为 model id 的后缀。Omnigent 将 model 和 effort 作为独立轴保留，并在启动时重新组合它们。传递 devin models list 中的 model 系列 slug 或别名，以及可选的 effort 档位： omni devin --model opus --effort xhigh omni devin --model gemini --effort max

--effort 接受 low、medium、high、xhigh 或 max；若系列没有 匹配档位则回退到其默认变体，因此不匹配的对仅消耗 努力，而非会话。你也可以在会话中使用 /model 切换模型。 Launch options

--permission-mode — normal（默认）、accept-edits、smart、 dangerous 或 bypass 之一。 --sandbox — 为 Devin 的 exec 工具启用操作系统级进程沙箱。 -p, --prompt — 在 TUI 启动时发送初始聊天输入。 --resume [CONVERSATION] — 恢复先前的 Omnigent 对话；无值时 它打开一个限定于 devin-native 会话的挑选器。

Devin 自身的 --resume/-c/--config/--export 标志保留给 Omnigent，它拥有恢复和 hook 接线；请改用 omni devin --resume。 devin 和 native-devin 拼写均解析为 devin-native。 前内置 ACP 行 devin-acp 已在 0.14 中移除，其 id 现在 别名到 native wrap，因此现有会话和脚本仍保持解析。 用户配置的 acp: agent 不受影响。 Jcode Jcode（jcode.sh）作为内置 harness 提供，id 为 jcode。与 Grok Build 类似，它通过 stdio 上的 Agent Client Protocol 驱动其供应商 CLI（jcode acp）— Omnigent 渲染其流式输出、推理和工具卡片，并将其 权限请求通过你的上下文策略路由。 它是内置的，因此你直接选择 jcode harness id，而不是 注册一个启动命令。 omni run --harness jcode

Jcode 自带其自身的认证和模型 — Omnigent 不存储凭据。Jcode 通过 curl 安装程序分发（无 npm 包），并在 ~/.jcode/config.toml 中拥有其 provider 和 model 选择，因此先安装 CLI 并在那里配置一个 provider： curl -fsSL https://jcode.sh/install | bash

注意：与大多数内置 ACP harness 不同，Jcode 的 ACP server 不 支持会话范围的 MCP — 它忽略 session/new 中发送的 mcpServers。 因此，Omnigent 不向 Jcode 通告其内置 MCP 工具（session、sub-agent、 skill 和 policy 工具）。应在 Jcode 自身的 ~/.jcode/mcp.json 中配置任何 Jcode 应使用的 MCP server。 Hermes Hermes 作为内置 harness 提供，id 为 hermes，并直接在 web harness 挑选器中提供。像其他内置项一样选择它 — 在挑选器中、通过 --harness hermes，或在 agent YAML 中： executor: harness: hermes model: hermes-4-405b

与 ACP agents 类似，Hermes 自带其自身的认证 — Omnigent 不存储 凭据也不注入。Hermes 从其自身的文件 存储（HERMES_HOME 下的 auth.json / .env）读取凭据，因此先通过其自身的 CLI 登录并选择模型： hermes setup # HERMES_HOME 下的基于文件的认证 hermes model # 选择 Hermes 运行的模型

与通用 ACP agents 不同，Hermes 会遵循 /model 选择： 你在 YAML 中声明或会话中途切换的模型会传递到 harness（通过 HARNESS_HERMES_MODEL）。会话选择的沙箱和工作区 也会传递，因此 web 会话对话框中选择的沙箱确实 限制了 Hermes 运行。 Kimi Code Kimi Code（kimi，别名 kimi-code）自带其自身的认证 — Omnigent 不存储凭据。Kimi 通过 curl 安装程序分发（无 npm 包），因此先 安装 CLI 并通过它登录： curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash kimi login # Moonshot OAuth，或粘贴 Moonshot API key

kimi login 将其凭据写入 ~/.kimi-code/credentials/kimi-code.json。 omni setup 检测该文件，一旦登录完成即显示 Kimi 为 Signed in； CLI 已安装但不存在凭据时显示 Not configured，并带有“Sign in with kimi login”提示。 Kimi 没有 kimi logout 子命令，因此 omni setup 不提供退出登录 行。要退出登录，请删除凭据文件： rm ~/.kimi-code/credentials/kimi-code.json

OpenCode 原生 OpenCode harness（opencode-native，别名 opencode）自带 其自身的 provider 认证 — Omnigent 不存储 OpenCode 凭据。OpenCode 通过三种路径中的 任何一种到达 provider，omni setup 读取每一个（不触碰 秘密）以报告 OpenCode 可以到达哪些 providers：

存储的登录 — 运行 opencode auth login；凭据落在 ~/.local/share/opencode/auth.json 中，按 provider id 索引。 Provider API key 变量 — 在 omnigent host 运行的环境中设置的通用 provider key，如 OPENAI_API_KEY、ANTHROPIC_API_KEY、XAI_API_KEY、MISTRAL_API_KEY 或 DEEPSEEK_API_KEY。 Amazon Bedrock — 见下文。

若所有这些都不存在，opencode-native 显示为 needs-auth host，web 挑选器禁用其行；omni setup 提供运行 OpenCode 原生登录的选项。 Amazon Bedrock Bedrock 是 API key 模式的例外：OpenCode 从 AWS 凭据链加载它，AWS SDK 在运行时进行认证，因此没有 auth.json 条目或 provider key 可检测。Omnigent 在以下任一条件成立时认为 OpenCode 就绪 以用于 Bedrock：

设置了这些 AWS 凭据链变量中的任何一个（任何非空值）： AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_PROFILE、AWS_REGION、 AWS_BEARER_TOKEN_BEDROCK、AWS_WEB_IDENTITY_TOKEN_FILE、 AWS_CONTAINER_CREDENTIALS_FULL_URI 或 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI。omni setup 将此列为 env: Amazon Bedrock。 你的 OpenCode 配置（~/.config/opencode/opencode.json 或 .jsonc） 声明了 provider.amazon-bedrock 块 — 即使是空的 {} 也足够。omni setup 将此列为 config: amazon-bedrock。

{ "$schema": "https://opencode.ai/config.json", "provider": { "amazon-bedrock": { "options": { "profile": "work" } } }, "model": "amazon-bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0" } 仅凭两件事不算：一个列出 amazon-bedrock 的 enabled_providers 列表（它仅过滤 OpenCode 显示哪些 providers），以及 OpenCode 的 Bedrock 加载器忽略的 AWS 变量 — AWS_SESSION_TOKEN、 AWS_DEFAULT_REGION 和 AWS_SHARED_CREDENTIALS_FILE。格式错误的配置 文件不赋予任何信用。 注意：就绪探测仅检查 Bedrock 是否已声明 — 它从不 联系 AWS。host 可能读取为就绪，但 AWS 随后拒绝该 profile 或 key； 故障在 OpenCode 进行首次 model 调用时浮现。 Antigravity 原生 Antigravity harness（antigravity-native）封装了 Google 的 agy CLI。 它需要 agy 1.1.13 或更新版本，并接受以下两种凭据之一：

Gemini API key — 在环境中设置非空的 GEMINI_API_KEY。 Omnigent 为你选择 agy 的直接 Gemini provider（在会话的隔离 agy settings 中为 modelProvider: "gemini"）。当设置了 GEMINI_API_KEY 时 它优先于任何已保存的 OAuth 登录；清除它以回退到 OAuth。 Google OAuth 登录 — 运行一次 agy 并完成浏览器登录。 agy CLI 没有 agy login / agy auth status 子命令： token 在其首次交互式运行时写入。Omnigent 在 ~/.gemini/oauth_creds.json（macOS）、~/.gemini/antigravity-cli/antigravity-oauth-token （Linux）或 macOS 密钥链（agy 1.1.7+）处识别它。

先安装 CLI，然后提供上述凭据之一： curl -fsSL https://antigravity.google/cli/install.sh | bash

一旦 agy 二进制文件存在且检测到 API key 或 OAuth 登录，omni setup 显示该 harness 为已配置。 注意：进程内的 antigravity SDK harness 是另一种 集成，它在运行时解析其自身的 Gemini API key。 上述 GEMINI_API_KEY 行为适用于封装 agy 的原生 antigravity-native harness。 Codex 原生 Codex harness（codex-native，由 omni codex 启动）在启动 Codex CLI 之前决定会话如何认证。大致按此顺序， 第一个适用的来源胜出：

为 codex harness 配置的 provider — 启动自定义 agent 时 agent 规范的 executor.auth，否则通过 omni setup 设置的 provider（API key、gateway 或 Databricks）。 当尚未配置任何内容时，Omnigent 在该机器上自动检测的 provider。 由你自己的 Codex config.toml（~/.codex/config.toml）选择的自足内置 Codex provider。Codex 自行认证这些 provider，因此不需要 Omnigent provider 也不需要 Codex 登录。 Codex CLI 自身的登录（codex login）。

使用你的 Codex config.toml provider 如果 ~/.codex/config.toml 选择了自带凭据的内置 provider，使得普通 codex 已在你的机器上运行，omni codex 以相同方式路由，而不是在第一轮失败并显示“Codex is not signed in and no Omnigent provider routes the codex harness”。除 openai 外的每个内置 Codex provider 均符合资格 — Amazon Bedrock（amazon-bedrock、amazon-bedrock-runtime）、Ollama （ollama）和 LM Studio（lmstudio）。显式的 model_provider = "openai" 仍 延迟到 Codex 自身的登录。 # ~/.codex/config.toml model = "openai.gpt-5.6-terra" model_provider = "amazon-bedrock" [model_providers.amazon-bedrock.aws] region = "us-east-1" 使用此文件且未配置 Omnigent provider 时，omni codex 启动并 设置 model_provider="amazon-bedrock"，Codex 自行解析 AWS 凭据链。 会话的 provider 摘要命名该内置 provider，以便你 看到采用了哪条路径。通过 omni setup 配置的 provider（上述第一级） 仍优先于环境 config.toml 选择。 当 Omnigent 写入会话私有 config.toml 时，也会原样保留诸如 [model_providers.amazon-bedrock] 等内置 provider 表；仅自定义的 [model_providers.] 表接收 Omnigent 的 重试设置（request_max_retries 及类似项），因为当内置表携带 Codex 不识别的字段时， Codex 会丢弃整个配置。 通过 --profile 选择 Codex profile 环境配置通过你传递给 Codex 的 --profile（或 -p）读取，无论是作为 CLI 透传 参数还是通过 harness.codex-native.args。 Omnigent 像 Codex 启动时那样将所选 profile 叠加到 ~/.codex/config.toml 之上：

若 ~/.codex/.config.toml 文件 profile 存在，则叠加它 — 无论是否有基础 config.toml。 否则使用 config.toml 中的传统内联 [profiles.] 表 （0.134 之前的 Codex 版本将 profile 保持内联）。

因此，omni codex --profile bedrock 在该 profile 设置 model_provider = "amazon-bedrock" 时通过 Bedrock 路由，即使基础配置未设置； 且在 Bedrock 基础上 --profile openai 保持 Codex 自身的登录。 无处存在的 profile 不会触及此层（启动回退到 Codex 登录）， 且格式错误的选择器 — 缺失值、重复的 --profile 或 无效的 profile 名 — 在会话启动时由启动参数验证报告，而非在路由期间。 Pi 原生 Pi harness（pi，别名 pi-native）运行 Pi CLI 并 对照你通过 omni setup 配置的 provider，写入受管的 models.json 和 每会话的 Pi 设置，使 Pi 使用 provider 的 key 而非其自身的凭据 环境变量进行认证。 精选 /model 短名单 Gateway provider 系列可以声明一个命名的层级 models: 映射。当该 映射包含多个不同的 model id 时，Omnigent 将每个层级 注册到 Pi，并将 Pi 的 /model 挑选器限定于恰好该集合，列在 omnigent provider 之下： # ~/.omnigent/config.yaml providers: bifrost: kind: gateway default: true openai: base_url: http://bifrost.example.com/v1 api_key: wire_api: chat models: default: GLM-5.3-Flash opus: GLM-5.3 pro: deepseek-v4-pro 使用此配置，Pi 会话中的 /model 显示 GLM-5.3-Flash、GLM-5.3 和 deepseek-v4-pro（各一次 — 解析到相同 id 的层级 合并为单个行）并隐藏 Pi 的内置 provider 目录。该范围是 写入会话受管 Pi settings 的 enabledModels 挑选器偏好， 因此你仍可从 Pi 内部将挑选器切换回所有模型。 关于层级值如何解析的两个细节：

别名。层级值可命名另一个层级 — 例如 default: deepseek-pro 与 deepseek-pro: deepseek-v4-pro 并列。Omnigent 遵循别名到具体 id，因此会话以 deepseek-v4-pro 启动，别名本身不作为挑选器行出现。 括号后缀。层级值上的 [...] 后缀（例如 GLM-5.3[16m]） 在 id 到达 gateway 或挑选器之前被去除，这与 启动模型的处理方式一致。

短名单仅来自配置的 models: 映射。没有映射的系列、 解析到单个 id 的映射，或仅默认设置上的 --model 覆盖 都不会限定挑选器，且从 端点实时发现的目录也从不这样做 — 在这些情况下，你已在 自身 Pi 设置中保留的任何 enabledModels 偏好都保持原样。 将其他 harness 的凭据排除在 Pi 之外 Pi 仅在其环境中看到某 provider 的凭据变量时，即激活该内置 provider 的整个目录 — 无论值是什么。导出占位 token 用于其他 harness 的部署（例如 ANTHROPIC_AUTH_TOKEN 使 claude-code 可与 gateway 通信）将 看到 Pi 的挑选器被绕过受管 provider 的内置条目淹没。 Pi 自身的认证依赖受管的 models.json key， 不需要那些 变量，因此你可以使用 OMNIGENT_PI_ENV_UNSET 从 Pi 终端环境中命名 要去除的变量，这是一个逗号分隔的变量名列表： OMNIGENT_PI_ENV_UNSET=ANTHROPIC_AUTH_TOKEN,OPENAI_API_KEY

名称会被修剪并去重；当变量未设置或为空白时，什么也不 去除。在 omnigent host 运行的环境中设置它 — 该变量仅携带名称，因此它通过 host 守护进程和 派生的 runner 转发而不转发所命名的秘密本身，Pi 终端在启动 pi 之前去除这些变量。同一部署中的其他 harness 不受影响。 Custom ACP agents 除内置 harness 外，通用 acp harness 驱动任何 说 Agent Client Protocol 的 agent — 这是开放的、 编辑器无关的协议，被 Gemini CLI、Qwen Code、Goose 和内部 agents 使用。你将 Omnigent 指向一个启动命令，它 即与该系统启动的任何目标说 ACP。 每个 ACP agent 自带其自身的认证 — Omnigent 不存储凭据， 因此先通过 agent 自身的 CLI 登录。通过 omnigent setup → configure harnesses → Custom ACP agent → Add 注册 agent，提供名称、启动命令和可选模型。（若要 从现有 OpenClaw/acpx 注册表导入 agents 而非逐一输入，参见 下方 从 OpenClaw 导入 agents。）一些 可粘贴的命令： AgentCommandGemini CLIgemini --experimental-acpQwen Codeqwen --acpGoosegoose acp 每个注册的 agent 存储在 ~/.omnigent/config.yaml 的顶层 acp: 块中，并获得从其 名称派生的稳定 slug。然后它在 web 挑选器和 agent YAML 中作为其自身的 harness id 出现，acp:： acp: agents: - { name: Gemini CLI, command: gemini --experimental-acp } - { name: Goose, command: goose acp, model: gpt-5.3 } executor: harness: acp:gemini-cli 该 agent 运行其自身的 agent 循环、工具和上下文窗口；Omnigent 渲染 其流式输出、推理和工具卡片，将其权限请求通过你的上下文策略作为 web 发起 卡片路由，并尊重中断。Omnigent 还将 其自身的内置工具（session、sub-agent、skill 和 policy 工具）暴露给 agent， 与 agent 的原生工具并列；设置 OMNIGENT_ACP_MCP=0 可禁用 该会话的桥接。 若要永久禁用特定 agent 的该 MCP relay，在其 acp: 条目上设置 omnigent_mcp: false。该 agent 保留其自身的原生工具； Omnigent 只是在 session/new 中停止向其借用内置工具 （该字段仍作为空列表发送，这是 ACP 要求的）。这对于 拒绝每会话 MCP server 的 agents 是必需的 — 例如 下方描述的 OpenClaw Gateway 桥接。该值必须是布尔值； 若不是，omnigent setup 报告错误。 acp: agents: - name: OpenClaw command: openclaw acp --url --token-file omnigent_mcp: false 注意：通用 ACP harness 没有固定的二进制文件 — 每个 agent 拥有其自身的安装和登录，因此缺失二进制文件只是提示，而非硬性 门控。沙箱化的通用 ACP agent 获得对其二进制文件目录、cwd 的读访问 权，以及对 /tmp 的写访问权；需要写入自身配置目录的 agent 目前需要 sandbox: none（默认值）。 Import agents from OpenClaw 如果你已为 OpenClaw 或 acpx CLI 维护 agent 注册表，Omnigent 可以将这些 agents 导入其 acp: 块，而非手动逐一重新 添加。运行 omnigent setup → configure harnesses → Import from OpenClaw。 该行显示自动检测到的 agents 数量。Omnigent 查找两个 默认位置： SourcePathacpx~/.acpx/config.jsonOpenClaw~/.openclaw/openclaw.json 两个文件均按 JSON5 读取，你可以选择 Choose another file… 指向其他位置的配置。Omnigent 列出它找到的 agents，从 每个名称派生稳定 slug，并 — 在你确认后 — 将它们追加到 ~/.omnigent/config.yaml 的 acp: 块。从此以后，它们的行为与手动 添加的 ACP agents 完全相同。 导入仅存储启动命令，不存储凭据 — 每个 agent 仍通过其自身的 CLI 认证。重新运行导入是安全的：已存在的 agents 被跳过，而名称与现有 slug 冲突的新 agent 获得数字后缀（例如 gemini-cli-2），因此不会覆盖。 其二进制文件不在 PATH 上的 agent 被标记为提示，而非阻止。 若要一次性启动单个 OpenClaw/acpx agent 而不保存到配置中， 在 omni run 上使用 --from-openclaw： omni run --from-openclaw "Gemini CLI" -p "review the last commit"

通过其显示名称（不区分大小写）或派生 slug 匹配该 agent。 这通过 acp harness 运行该 agent 一次该会话；不能 与 AGENT 路径或 --harness 组合。 此路径直接驱动所选的 coding agent。它不会 将 OpenClaw 的 Gateway 会话、路由、记忆或通道带入对话 — 为此，请注册 Gateway 桥接（下文）。 Drive the OpenClaw Gateway 除导入单个 coding agents 外，openclaw acp 命令将 实时 OpenClaw Gateway 会话暴露为 stdio 上的 ACP server，使 Omnigent 能够访问 OpenClaw 自身的路由、记忆和通道。将其注册为 acp: agent，并禁用 Omnigent 的 MCP relay，因为 Gateway 桥接拒绝 每会话的 MCP server： acp: agents: - name: OpenClaw command: openclaw acp --url --token-file omnigent_mcp: false 将 和 替换为你的运行中 Gateway 的连接细节，然后启动它： omni run --harness acp:openclaw

警告：优先使用 --token-file，以便 Gateway token 不存储在 启动命令中。不要提交或共享 ~/.omnigent/config.yaml，并使用 OpenClaw 支持的最小权限 token。 Omnigent 拥有外层对话和转录；OpenClaw 拥有 Gateway 支持的会话。OpenClaw 的 Control UI 是另一个 Gateway 客户端， 因此 Omnigent 离线时在那里输入的消息不会 导入 Omnigent 对话 — 若需要其转录和恢复行为，请 使用 Omnigent 作为权威对话。此集成不支持与 Control UI 的双向同步 以及每会话的 Omnigent MCP。 Swap harnesses 工具、策略和其他配置在不同 harness 间保持不变。只需 更改 YAML 中的 harness 值，或在运行时覆盖它： omni run agent.yaml --harness codex

参见 Models & Credentials 了解如何设置 API key 并选择 model。 Override the harness binary and launch args 默认情况下，每个 harness 从你的 PATH 启动其供应商 CLI（例如 claude、 codex）。你可以从你的 Omnigent 配置 — ~/.omnigent/config.yaml（用户）或 .omnigent/config.yaml（项目，优先）指向特定可执行文件，或前缀 基础启动参数。使用 omni config list 查看；使用 omni config set = 设置值。 顶层 harness: 配置键是多态的。旧标量形式仍然 有效（并在下次写入配置时自动迁移到映射形式）： # Legacy scalar（已弃用，仍被遵循）： harness: claude-sdk # 映射形式 — 默认值加上每 harness 的启动覆盖： harness: default: claude-sdk codex-native: command: /usr/local/bin/codex args: [--config, approval_policy=on-request] pi-native: command: /opt/bin/pi

default（可选）— omni run 的默认 harness id。 command（可选）— 覆盖该 harness 的供应商 CLI 可执行文件。 args（可选列表）— 基础启动参数；任何 CLI 透传 参数追加在这些之后。

此顶层 harness: 配置键选择 CLI 默认值和每二进制 启动覆盖。它与 agent 自身 YAML 中的 executor.harness 值分开，后者 固定该 agent 的 harness。 注意：项目的每 harness 覆盖会深度合并到你的 全局设置 — .omnigent/config.yaml 条目增强（而非替换） 匹配的 ~/.omnigent/config.yaml 条目，项目字段胜出。 Binary-path precedence 对于 harness 的 command，第一个非空来源胜出：

OMNIGENT__PATH 环境变量。 配置中的 harness..command。 harness 的内置默认可执行文件。

args 遵循相同思路：配置中的 args 是基础，CLI 透传 参数追加在其后。 是 harness 的底层二进制文件，而非其 id： -native 后缀被去除，因此 pi 和 pi-native 共享 OMNIGENT_PI_PATH，且 Claude harnesses 映射到 OMNIGENT_CLAUDE_PATH（因此 claude-sdk 和 claude-native 共享一个变量）。 已弃用：较旧的 HARNESS__PATH 环境变量（用于 codex、pi、 kimi、goose、qwen 和 hermes）仍作为回退读取，但记录 警告并将在 v0.8.0 中移除 — 请改用 OMNIGENT__PATH。 omni claude 的 --command 标志同样已弃用（设置 OMNIGENT_CLAUDE_PATH 或 harness.claude-native.command 代替），并将在 未来版本中移除。没有其他原生命令有 --command 标志。 若要添加 Omnigent 未包含的运行时，参见 Community Harnesses。