Configuration

Choose a harness id from Supported Harnesses, then configure any authentication or launch settings it needs.

GitHub Copilot

The copilot harness authenticates with a GitHub token that carries Copilot access. Omnigent resolves one from the first source that's set, in this order:

1. A COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN environment variable.
2. A token you stored through omnigent setup → configure harnesses → Copilot.
3. Your GitHub CLI login — if you've run gh auth login, Omnigent asks gh for the token directly (gh auth token), so a logged-in user is ready without pasting anything into setup.

GitHub Enterprise host

Organizations that reach Copilot through a GitHub Enterprise (data-residency) instance need auth and API calls pointed at their own hostname rather than github.com. Set it through omnigent setup → configure harnesses → Copilot → Set GitHub Enterprise host (the same menu lets you change or clear it), or edit ~/.omnigent/config.yaml directly:

copilot:
  github_host: acme.ghe.com

Provide a bare hostname; a pasted https:// scheme or trailing slash is stripped automatically. When set, Omnigent forwards it to the bundled Copilot CLI as the COPILOT_GH_HOST environment variable and fetches your gh token for that host. With no host configured, Copilot uses its default github.com.

Grok Build

Grok Build (xAI's grok CLI) ships as a builtin harness with the id grok (alias grok-build). Under the hood it drives grok agent stdio over the Agent Client Protocol — Omnigent renders its streaming output, reasoning, and tool cards and routes its permission requests through your contextual policies, just like the generic acp harness below. The difference is that it's built in: you select the grok harness id directly instead of registering a launch command.

omni run --harness grok

Like the generic ACP agents, Grok Build brings its own auth and model — Omnigent stores no credential and a /model pick is rejected up front. Install the CLI and log in through xAI first:

curl -fsSL https://x.ai/cli/install.sh | bash
grok login --device-auth   # xAI OAuth (device-code capable); or set XAI_API_KEY

Hermes

Hermes ships as a builtin harness with the id hermes and is offered directly in the web harness picker. Select it like any other builtin — in the picker, via --harness hermes, or in agent YAML:

executor:
  harness: hermes
  model: hermes-4-405b

Like the ACP agents, Hermes brings its own auth — Omnigent stores no credential and injects none. Hermes reads credentials from its own file-based store (auth.json / .env under HERMES_HOME), so log in and pick a model through its own CLI first:

hermes setup    # file-based auth under HERMES_HOME
hermes model    # choose the model Hermes runs

Unlike the generic ACP agents, a /model pick is honored for Hermes: the model you declare in YAML or switch to mid-session threads through to the harness (via HARNESS_HERMES_MODEL). The sandbox and workspace a session selects are threaded through as well, so a sandbox chosen in the web session dialog actually confines the Hermes run.

Kimi Code

Kimi Code (kimi, alias kimi-code) brings its own auth — Omnigent stores no credential. Kimi ships via a curl installer (no npm package), so install the CLI and sign in through it first:

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
kimi login   # Moonshot OAuth, or paste a Moonshot API key

kimi login writes its credential to ~/.kimi-code/credentials/kimi-code.json. omni setup detects that file and shows Kimi as Signed in once a login has completed; while the CLI is installed but no credential is present it shows Not configured with a "Sign in with kimi login" hint.

Kimi has no kimi logout subcommand, so omni setup offers no sign-out row. To sign out, delete the credential file:

rm ~/.kimi-code/credentials/kimi-code.json

Custom ACP agents

Beyond the built-in harnesses, the generic acp harness drives any agent that speaks the Agent Client Protocol — the open, editor-agnostic protocol used by Gemini CLI, Qwen Code, Goose, and in-house agents. You point Omnigent at a launch command and it speaks ACP against whatever that command starts.

Each ACP agent brings its own auth — Omnigent stores no credential, so log into the agent through its own CLI first. Register agents with omnigent setup → configure harnesses → Custom ACP agent → Add, providing a name, a launch command, and an optional model. (To pull agents in from an existing OpenClaw/acpx registry instead of typing each one, see Import agents from OpenClaw below.) Some paste-ready commands:

Each registered agent is stored in a top-level acp: block of ~/.omnigent/config.yaml and gets a stable slug derived from its name. It then surfaces as its own harness id, acp:<slug>, in the web picker and in agent YAML:

acp:
  agents:
    - { name: Gemini CLI, command: gemini --experimental-acp }
    - { name: Goose, command: goose acp, model: gpt-5.3 }

executor:
  harness: acp:gemini-cli

The agent runs its own agent loop, tools, and context window; Omnigent renders its streaming output, reasoning, and tool cards, routes its permission requests through your contextual policies as web elicitation cards, and honors interrupts. Omnigent also exposes its own builtin tools (session, sub-agent, skill, and policy tools) to the agent alongside the agent's native tools; set OMNIGENT_ACP_MCP=0 to disable that bridge for a session.

To disable that MCP relay permanently for a specific agent, set omnigent_mcp: false on its acp: entry. The agent keeps its own native tools; Omnigent simply stops lending its builtin tools to that agent in session/new (the field is still sent as an empty list, which ACP requires). This is required for agents whose ACP server rejects per-session MCP servers — such as the OpenClaw Gateway bridge described below. The value must be a boolean; omnigent setup reports an error if it isn't.

acp:
  agents:
    - name: OpenClaw
      command: openclaw acp --url <gateway-url> --token-file <token-file>
      omnigent_mcp: false

Import agents from OpenClaw

If you already keep an agent registry for OpenClaw or the acpx CLI, Omnigent can import those agents into its acp: block instead of re-adding each one by hand. Run omnigent setup → configure harnesses → Import from OpenClaw. The row shows how many agents were detected automatically. Omnigent looks in two default locations:

Both files are read as JSON5, and you can pick Choose another file… to point at a config elsewhere. Omnigent lists the agents it found, derives a stable slug from each name, and — after you confirm — appends them to the acp: block of ~/.omnigent/config.yaml. From then on they behave exactly like manually added ACP agents.

Import stores only the launch command, not credentials — each agent still authenticates through its own CLI. Re-running the import is safe: agents already present are skipped, and a new agent whose name collides with an existing slug gets a numbered suffix (e.g. gemini-cli-2) so nothing is overwritten. An agent whose binary isn't on your PATH is flagged as a hint, not blocked.

To launch a single OpenClaw/acpx agent once without saving it to your config, use --from-openclaw on omni run:

omni run --from-openclaw "Gemini CLI" -p "review the last commit"

Match the agent by its display name (case-insensitive) or derived slug. This runs the agent through the acp harness for that one session; it can't be combined with an AGENT path or with --harness.

This path drives the selected coding agent directly. It does not bring OpenClaw's Gateway session, routing, memory, or channels into the conversation — for that, register the Gateway bridge (below).

Drive the OpenClaw Gateway

Beyond importing individual coding agents, the openclaw acp command exposes a live OpenClaw Gateway session as an ACP server over stdio, giving Omnigent access to OpenClaw's own routing, memory, and channels. Register it as an acp: agent, disabling Omnigent's MCP relay because the Gateway bridge rejects per-session MCP servers:

acp:
  agents:
    - name: OpenClaw
      command: openclaw acp --url <gateway-url> --token-file <token-file>
      omnigent_mcp: false

Replace <gateway-url> and <token-file> with your running Gateway's connection details, then launch it:

omni run --harness acp:openclaw

Omnigent owns the outer conversation and transcript; OpenClaw owns the Gateway-backed session. OpenClaw's Control UI is a separate Gateway client, so messages entered there while Omnigent is offline are not imported into the Omnigent conversation — use Omnigent as the canonical conversation when you need its transcript and resume behavior. Bidirectional sync with the Control UI and per-session Omnigent MCP are not supported by this integration.

Swap harnesses

Tools, policies, and other config stay the same across harnesses. Just change the harness value in your YAML, or override it at runtime:

omni run agent.yaml --harness codex

See Models & Credentials for how to set up API keys and choose models.

Override the harness binary and launch args

By default each harness launches its vendor CLI from your PATH (e.g. claude, codex). You can point a harness at a specific executable, or prepend base launch args, from your Omnigent config — ~/.omnigent/config.yaml (user) or .omnigent/config.yaml (project, takes precedence). View it with omni config list; set a value with omni config set <key>=<value>.

The top-level harness: config key is polymorphic. The legacy scalar form still works (and auto-migrates to the mapping form the next time the config is written):

# Legacy scalar (deprecated, still honored):
harness: claude-sdk

# Mapping form — a default plus per-harness startup overrides:
harness:
  default: claude-sdk
  codex-native:
    command: /usr/local/bin/codex
    args: [--config, approval_policy=on-request]
  pi-native:
    command: /opt/bin/pi

• default (optional) — the default harness id for omni run.
• command (optional) — overrides the vendor CLI executable for that harness.
• args (optional list) — base launch args; any CLI pass-through args are appended after these.

This top-level harness: config key selects the CLI default and per-binary launch overrides. It's separate from the executor.harness value inside an agent's own YAML, which pins the harness for that one agent.

Binary-path precedence

For a harness's command, the first non-empty source wins:

1. The OMNIGENT_<NAME>_PATH environment variable.
2. The config harness.<id>.command.
3. The harness's built-in default executable.

args follow the same idea: the config args are the base, and CLI pass-through args are appended after them.

<NAME> is the harness's underlying binary, not its id: the -native suffix is stripped, so pi and pi-native share OMNIGENT_PI_PATH, and the Claude harnesses map to OMNIGENT_CLAUDE_PATH (so claude-sdk and claude-native share one var).

To add a runtime that Omnigent does not include, see Community Harnesses.