Skip to content

Latest commit

 

History

History
641 lines (493 loc) · 35.6 KB

providers.md

File metadata and controls

641 lines (493 loc) · 35.6 KB

Providers

OMK supports subscription-based providers via OAuth and API key providers via environment variables or auth file. For each provider, omk knows all available models. The list is updated with every omk release.

Table of Contents

Subscriptions

Use /login in interactive mode, then select a provider:

  • ChatGPT Plus/Pro (Codex)
  • Claude Pro/Max
  • GitHub Copilot
  • xAI Grok subscription OAuth
  • Devin CLI subscription (SWE-2)

Run /login and choose a configured subscription provider to open its account picker. Select an existing account by its ChatGPT, Claude, or Google email when available, or choose Add another account to sign in with a new one. OMK keeps and refreshes each account independently, pins the provider to the account you select, and does not silently fail over to another subscription. /model remains dedicated to model selection.

Use /logout to clear all stored accounts for a provider. Tokens are stored in ~/.omk/agent/auth.json and auto-refresh when expired.

When the status sidebar is pinned, its USAGE section lists every configured subscription provider, with the active provider first. OMK reads quota windows from fixed provider endpoints for Codex, Claude, Kimi Code, GLM/ZAI Coding Plan, native xAI SuperGrok, Devin CLI, Command Code, and OpenCode Go, caches the result, and displays each percentage and reset countdown separately. OpenCode Go shows the three plan meters the console shows — 5-hour rolling from first use, the UTC calendar week, and the paid period — read from the fixed Console status endpoint with the stored OAuth user token. API-key-only OpenCode credentials have no verified quota endpoint and are not polled. Kimi Code reads GET https://api.kimi.com/coding/v1/usages with the stored OAuth token or kimi-coding key and identifies itself as User-Agent: omk, not as Kimi CLI. Claude also passively merges the official anthropic-ratelimit-unified-* response headers used by Claude Code. If Anthropic's usage endpoint is rate limited and no complete recent snapshot exists, OMK mirrors Claude Code's own startup quota check with one fixed-endpoint Haiku request capped at one output token, no more than once per OAuth credential per hour. This fallback consumes a small amount of Claude plan quota.

Codex streaming passively merges x-codex-primary-*, x-codex-secondary-*, and codex.rate_limits signals through the non-blocking StreamOptions.onRateLimit observer. These signals supplement missing polling windows only when the Codex service returns them; OMK does not infer a missing 5-hour value from a 7-day value.

Alibaba Model Studio Token Plan is recognized as QWEN TOKEN PLAN and reads its 7-day window through the official QwenCloud management CLI: when qwencloud is installed and logged in (npm i -g @qwencloud/qwencloud-cli && qwencloud auth login), OMK runs qwencloud usage summary --format json (override the binary with QWENCLOUD_CLI) and shows token_plan.usedPct plus the reset countdown. The CLI holds its own OAuth management credential; OMK never sends the plan's sk-* inference key anywhere for quota. Without the CLI the entry shows a connect: hint instead — the console usage page requires an Alibaba Cloud console session that OMK deliberately does not scrape, and OMK still never copies browser cookies or estimates quota from token counts. Qwen OAuth remains explicit quota API unavailable.

With a Meta (meta) OAuth login, the rail shows META usage from the official Muse Code CLI. Every 5 minutes at most, OMK starts muse serve --provider meta --disable-write --disable-shell --no-session-log, completes the MSP initialize handshake, asks usage/read, and closes stdin so the host exits; no prompt is submitted and no model is called. The CLI holds its own account credential and receives only a fixed non-secret environment (PATH, HOME, locale and temp/config directories); OMK sends it no key. The current window (usually 5H) and the weekly window show with reset countdowns. A host that has not yet observed a window shows no observed usage yet (with the plan tier when reported), not 0%. Without the CLI the entry shows a connect: hint; a failed or timed-out probe (15 s) shows usage unavailable.

With a stored native xai OAuth credential, OMK reads GET https://cli-chat-proxy.grok.com/v1/billing?format=credits and shows the weekly SuperGrok pool from config.creditUsagePercent plus its reset from config.currentPeriod.end. XAI_API_KEY is a separate API-billing credential and does not authorize this subscription endpoint.

With a configured commandcode API key (models.json or auth storage), OMK reads GET https://api.commandcode.ai/alpha/whoami, then /alpha/billing/credits, /alpha/billing/subscriptions, and /alpha/usage/summary on that same origin. The rail shows the 5-hour and weekly credit windows plus the monthly pool (spent / remaining+spent) and the plan name. OMK never sends the key anywhere except api.commandcode.ai, never reads browser cookies, and does not scrape Studio.

Google browser callback login

Gemini CLI and Antigravity show the authorization URL only after their loopback callback listener is ready. The browser callback must be a GET to the exact callback path with the login's matching state; an unrelated or mismatched callback does not consume the pending login. If the preferred port is occupied, OMK uses an ephemeral loopback port and includes that port in the authorization and token-exchange redirect URI.

The browser wait ends after five minutes, cancellation, approval, or denial. OMK closes the callback listener on every exit, including a failed browser hook. Token exchange and refresh are restricted to https://oauth2.googleapis.com/token. These bounds cover the callback wait, not subsequent Google project provisioning.

Model Studio DeepSeek V4

Model Studio uses enable_thinking, including for DeepSeek. OMK's Chat Completions adapter recognizes official HTTPS DashScope and *.maas.aliyuncs.com hosts, defaults to max_tokens and the system role, and omits unsupported OpenAI store/long-cache fields. Legacy thinkingFormat: "deepseek" on these hosts is translated to the enable_thinking format. Native DeepSeek endpoints keep their native format.

DeepSeek V4 sends the selected reasoning_effort when compatibility settings permit it. Without a model-specific mapping, minimal maps to the supported low value. An explicit supportsReasoningEffort: false still suppresses that field; remove that override or enable it for the model if you intend to send high, xhigh, or max. With thinking off, OMK sends enable_thinking: false rather than relying on the server default. See custom model configuration.

Keep the key paired with its purchased product and region. These are distinct billing paths, not interchangeable aliases:

Product Example OpenAI-compatible base URL
Token Plan, Singapore https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Coding Plan, China https://coding.dashscope.aliyuncs.com/v1
Pay-as-you-go https://dashscope.aliyuncs.com/compatible-mode/v1

Protocol detection never changes the URL, credentials, model ID, or subscription. For a comparison run, pin the exact Flash snapshot offered by that endpoint in both arms; deepseek-v4-flash-0731 and an unversioned alias are not automatically the same experimental condition. Apply a model contract, and verify the installed adapter and final request before starting a benchmark.

Sources: Alibaba's DeepSeek API and plan endpoint separation, consulted 2026-09-08. The local tests exercise serialization, not account availability, provider compliance, billing, or benchmark performance.

Devin CLI

Run /login devin, select devin/swe-2, and use /think medium, /think high, or /think max. For a new session after login:

omk --provider devin --model swe-2 --thinking max

The default is medium. Thinking-off and other levels are unsupported. max is a reasoning level, not a requirement to buy the Devin Max subscription tier. Your account's model access and quota still apply. For presets, effort guidance, the 1M-token context budget, and the devin-harness loadout, see the Devin SWE-2 harness.

The devin catalog also carries every other lane GetCliModelConfigs advertises — each wire UID is its own logical model (claude-opus-5-high, gpt-5-6-sol-xhigh, gemini-3-8-flash-medium, kimi-k3-max, glm-5-3-high, grok-4-6-xhigh, deepseek-v4-pro-max, swe-1-7, inkling-max, …). Flat models pin their declared effort lane, so /think is fixed per model; entries whose lane is a no-thinking variant report reasoning: false. Availability is account- and plan-dependent: a lane absent from your catalog fails loudly instead of being remapped. Image input is still text-only at the adapter.

omk --provider devin --model claude-opus-5-high

Authentication. OMK uses the CLI's PKCE flow at app.devin.ai/auth/cli/continue and api.devin.ai/auth/cli/token. Its callback binds only to 127.0.0.1:59653, validates state, and closes after success, rejection, cancellation, or a five-minute deadline. If the port is occupied, paste the complete callback URL into OMK's local prompt. For remote sessions, forward this loopback port to the machine running OMK.

Credentials use the existing protected auth.json storage and account picker. Expired sessions require /login devin again: no refresh endpoint is verified, and OMK does not renew the expiry locally. Use /logout to remove the stored OMK credential. Alternatively, DEVIN_API_KEY accepts an already-owned CLI session token, not a cog_ REST API key. OMK does not install or invoke the Devin agent, read browser cookies, or import another application's credentials.

Transport and limits. The Node-only devin-agent adapter uses Connect/protobuf at the fixed HTTPS origin https://server.codeium.com. It exchanges the session token for a user JWT and reads GetCliModelConfigs before each turn. The logical swe-2 model resolves its effort through the server's SWE-2 family metadata; every other catalog model resolves by its own wire UID. OMK never invents a swe-2-max ID or downgrades an unavailable route. Disabled, internal, and ambiguous entries are excluded; fast-lane entries match only when their own UID is selected. The family's separate 1M-context entries form a second lane that is selected only when the model's local contextWindow is 1,000,000 or more (the bundled default); a smaller budget uses the standard lane.

Text, thinking, tool calls/results, and reported usage enter the normal OMK agent loop. Image input and enterprise-origin overrides are unsupported. Requests reject redirects. Malformed, oversized, or unterminated streams fail; remote error bodies are not copied into diagnostics. SDK onPayload receives protobuf bytes without credential metadata.

The bundled 1,000,000-token context budget and 16,384-token output cap are local defaults, not published SWE-2 limits. Output is further capped against the authenticated catalog. If the selected lane declares a smaller context window, the request fails and names the window; lower contextWindow through modelOverrides in models.json rather than expecting a silent downgrade. Zero catalog pricing means unpriced subscription usage, not free inference. Quota percentages are not inferred.

Account quota. With a Devin credential configured, the status rail's USAGE section calls SeatManagementService/GetUserStatus (session-token metadata, no user JWT) and renders the plan's daily and weekly quota meters with reset times. Accounts whose plan reports no quota windows show the plan name and credit balances instead. The rail mirrors the CLI's /usage surface; it never sends the session token anywhere except server.codeium.com.

Verification. Local tests exercise the public stream API, real loopback callbacks with mocked token exchange, model selection, and protocol fixtures. Live login, catalog compatibility, SWE-2 inference, and billing remain unverified without a Devin account. Unauthenticated catalog probes returned HTTP 400. Live tests require DEVIN_API_KEY and LIVE_E2E=1 and consume subscription quota.

Sources consulted 2026-09-12 and 2026-09-13: the SWE-2 announcement (2026-09-10; CLI availability and medium/high/max; no published context window), CLI commands, and the official manifest (observed identity 3000.10.21). Protocol fields follow the third-party oh-my-pi snapshot, not a stable public inference contract; attribution is in packages/ai/DEVIN-NOTICE. Regenerate only the Devin models, preserving every other catalog entry, with npm --prefix packages/ai run generate-models -- --devin-only.

Cursor

Run /login cursor (PKCE + polling against cursor.com/api2.cursor.sh), then select a cursor/* model. cursor/default is the Auto router; sibling slugs carry their effort and lane (-low|medium|high|xhigh|max, -thinking-*, -fast) in the id, mirroring the CLI's flat list. CURSOR_API_KEY accepts an already-owned access token instead of the OAuth flow.

omk --provider cursor --model default

Transport and limits. The Node-only cursor-agent adapter runs the agent.v1.AgentService/Run bidirectional RPC over HTTP/2 at api2.cursor.sh with Connect-framed protobuf. Each stream() call is one Run: userMessageAction for a fresh user turn or resumeAction otherwise; history is replayed through conversationState.rootPromptMessagesJson — SHA256-keyed JSON message blobs the server fetches back via the kv channel — and system prompts ride requestContext.rules in the exec handshake. For OpenAI-family sibling slugs the adapter splits the effort into a reasoning request parameter because the Run endpoint rejects sibling model_ids; other ids pass through whole. tokenDelta frames accumulate output usage; plan-specific model availability is enforced server-side (free plans serve Auto only).

Text, thinking, and reported usage enter the normal OMK agent loop; images attach through selectedContext.selectedImages. Server exec frames that ask the client to run tools are answered with the protocol's throw failure channel — OMK tools are deliberately not advertised inside the provider, so a cursor model reports the capability gap instead of bypassing tool governance. Wiring exec frames through governed OMK tools is a coding-agent bridge feature, not provider scope. Hosted search/fetch permission queries are approved; interactive ones are rejected.

The bundled catalog was captured from GetUsableModels (2026-09-18; 223 entries). Regenerate only the Cursor section with npm --prefix packages/ai run generate-models -- --cursor-only. Protocol fields follow the same third-party snapshot attribution as the Devin adapter. Live login, plan gating, and quota behavior remain account-dependent; the adapter is covered by loopback HTTP/2 protocol tests.

OpenAI Codex

  • Requires ChatGPT Plus or Pro subscription
  • Officially endorsed by OpenAI: Codex for OSS
  • gpt-5.6-moa runs bounded, tool-free GPT-5.6 Sol and Terra advisers concurrently, then streams a Sol synthesis with the active tools and tool history. Synthesis tool calls enter the normal agent loop; each follow-up model turn repeats the three-call workflow. Adviser and synthesis output remain independently capped.
  • On GPT-5.6 models OMK sends xhigh for its max and ultra tiers; ultra on the MoA model additionally represents the Sol/Terra delegation workflow.
  • GPT-6.1 Sol (gpt-6.1-sol, the Codex default since 2026-09-29), GPT-6.1 Terra, GPT-6 Astra, GPT-6 Sol and GPT-6 Luna follow the Codex client's bundled catalog: efforts low through max with no off or minimal (thinking stays on), an 872,000-token window and 128,000 output tokens. On Sol/Terra 6.1 and Astra, /think max sends reasoning.effort: "max", but /think ultra sends "xhigh", not "ultra". GPT-6 Sol maps ultra to "max"; Luna does not offer ultra. In the Codex app ultra also delegates to subagents automatically; in OMK it only selects that effort. Custom models.json entries replace built-in thinking metadata, so the effective selector and wire mapping can differ.
  • When using stored Codex OAuth, OMK uses its selected account for its own requests; a runtime --api-key can override it. Selecting ultra does not pin that account for the optional subagent extension's worker processes: they reload the stored selection, which can change while a run is active, and do not inherit a parent's in-memory API-key override.
omk --provider openai-codex --model gpt-5.6-moa --thinking ultra
omk --provider openai-codex --model gpt-6.1-sol --thinking ultra

GPT-6 Astra

OpenAI-shaped Astra routes (openai, azure-openai-responses, opencode, github-copilot, OpenRouter) expose OMK ultra in the selector and send reasoning.effort: "max". Official Astra effort values remain low, medium, high, xhigh, and max; there is no native ultra wire value. The openai-codex route follows Codex instead (see above); a ChatGPT account whose catalog does not serve gpt-6-astra still answers HTTP 400.

omk --provider openai --model gpt-6-astra --thinking ultra

Claude Pro/Max

Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from extra usage and is billed per token, not against Claude plan limits.

GitHub Copilot

  • Press Enter for github.com, or enter your GitHub Enterprise Server domain
  • If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"

xAI Grok

Both authentication modes use the built-in xai provider. Run /login for subscription OAuth, or set XAI_API_KEY for xAI Platform API billing. Do not configure a second Grok provider.

For project presets, Imagine guidance, and the exact grok-4.6, grok-4.5, and grok-4.3 thinking mappings, see Grok harness.

API Keys

DeepSeek models use the existing provider transports and credentials. OMK's DeepSeek harness adds a model-scoped local engine, including recognized gateway model IDs, without installing the upstream dsh runtime or changing the API endpoint.

Environment Variables or Auth File

Use /login in interactive mode and select a provider to store an API key in auth.json, or set credentials via environment variable:

export ANTHROPIC_API_KEY=sk-ant-...
omk
Provider Environment Variable auth.json key
Anthropic ANTHROPIC_API_KEY anthropic
Ant Ling ANT_LING_API_KEY ant-ling
Azure OpenAI Responses AZURE_OPENAI_API_KEY azure-openai-responses
OpenAI OPENAI_API_KEY openai
DeepSeek DEEPSEEK_API_KEY deepseek
Devin CLI session token DEVIN_API_KEY devin
Cursor subscription CURSOR_API_KEY cursor
NVIDIA NIM NVIDIA_API_KEY nvidia
Google Gemini GEMINI_API_KEY google
Mistral MISTRAL_API_KEY mistral
Groq GROQ_API_KEY groq
Cerebras CEREBRAS_API_KEY cerebras
Cloudflare AI Gateway CLOUDFLARE_API_KEY (+ CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_GATEWAY_ID) cloudflare-ai-gateway
Cloudflare Workers AI CLOUDFLARE_API_KEY (+ CLOUDFLARE_ACCOUNT_ID) cloudflare-workers-ai
xAI XAI_API_KEY xai
OpenRouter OPENROUTER_API_KEY openrouter
Vercel AI Gateway AI_GATEWAY_API_KEY vercel-ai-gateway
ZAI ZAI_API_KEY zai
ZAI Coding Plan (China) ZAI_CODING_CN_API_KEY zai-coding-cn
OpenCode Zen OPENCODE_API_KEY opencode
OpenCode Go OPENCODE_API_KEY opencode-go
Hugging Face HF_TOKEN huggingface
Fireworks FIREWORKS_API_KEY fireworks
Together AI TOGETHER_API_KEY together
Kimi For Coding KIMI_API_KEY kimi-coding
WorkBuddy (CodeBuddy) WORKBUDDY_API_KEY workbuddy
Meta Model API META_API_KEY (or META_MODEL_API_KEY, MODEL_API_KEY) meta
MiniMax MINIMAX_API_KEY minimax
MiniMax (China) MINIMAX_CN_API_KEY minimax-cn
Xiaomi MiMo XIAOMI_API_KEY xiaomi
Xiaomi MiMo Token Plan (China) XIAOMI_TOKEN_PLAN_CN_API_KEY xiaomi-token-plan-cn
Xiaomi MiMo Token Plan (Amsterdam) XIAOMI_TOKEN_PLAN_AMS_API_KEY xiaomi-token-plan-ams
Xiaomi MiMo Token Plan (Singapore) XIAOMI_TOKEN_PLAN_SGP_API_KEY xiaomi-token-plan-sgp
Zyloo ZYLOO_API_KEY zyloo

Reference for environment variables and auth.json keys: const envMap in packages/ai/src/env-api-keys.ts.

WorkBuddy (Tencent CodeBuddy)

The cloud inference behind Tencent's CodeBuddy / WorkBuddy agents. Plan keys start with ck_ and are issued by the CodeBuddy login flow:

export WORKBUDDY_API_KEY=ck_...
omk --provider workbuddy --model glm-5.3

Endpoint and limits, verified against the live service on 2026-09-19:

  • Chat requests go to https://www.workbuddy.ai/v2/chat/completions and must stream; a non-streaming request is rejected. The same key is accepted by www.codebuddy.ai, not by the *.cn hosts.
  • The first message must be a system message. OMK sends the system prompt in that position and prepends an empty one when a session has no system prompt.
  • max_tokens carries the output cap; max_completion_tokens is ignored upstream.
  • Images are sent as data URIs, which is the only form the endpoint accepts.
  • Thinking levels expose only the effort values the provider declares for that model (glm-5.3: low/high/max, glm-5.2: high/xhigh, gpt-5.6-*: low/medium/high/xhigh, …). The endpoint accepts reasoning_effort, but its effect on reasoning volume is not verified, and no off value is offered because none was verified. Thinking can therefore not be disabled per request.
  • Model entitlement is per plan: the built-in catalog lists the 27 lanes verified for one account, including eight the CLI's bundled product JSON never declares (claude-opus-5, claude-opus-4.6, claude-sonnet-4.6, deepseek-v4.1-flash, gemini-3.8-flash, gpt-6-astra, grok-4.6, hy4-preview) which a cross-sweep of this repository's own model ids found. glm-5.0 answered 429 while its siblings answered 200, so it is not listed; the CLI's role aliases (fast-model, balanced-model, primary-model, deep-model) resolve server-side to targets this catalog cannot declare and are not listed either.
  • Billing is metered in the provider's own credit unit, which OMK reports as zero cost rather than inventing a USD rate. Measured per-call charges on one account (small prompts): claude-opus-5 0.26, claude-opus-4.6 0.20, claude-sonnet-4.6 0.12, grok-4.6 0.06–0.08, gpt-5.6-sol 0.04, gemini-3.8-flash 0.02–0.06, glm-5.3 0.01, and 0 credits on hy3, deepseek-v3-0324, deepseek-v4.1-flash, glm-5.2, kimi-k2.5/k2.6 and minimax-m3. A charge scales with tokens, so these are magnitudes, not tariffs.
  • Plan allowances (provider documentation, 2026-09-19): Free 100 credits/month, Pro $10/month or $96/year for 2,000 credits/month, plus a limited-time activity bonus of 30 credits/day on Free and 50/day on Pro. Credits are issued monthly, do not carry over, and new accounts get 250 credits valid for 14 days; Pro has a 7-day trial of 500 credits. Check the provider console for the account's own balance: at the measured rates, the Free plan's 100 credits is roughly 380 calls at claude-opus-5 size, ~830 at claude-sonnet-4.6, and 1,600-5,000 at gemini-3.8-flash, while the 0-credit lanes above did not draw on the allowance at all in these probes.

NVIDIA NIM

Set NVIDIA_API_KEY and select a currently listed NVIDIA model with /model. NIM entries are filtered against its live /v1/models list; historical GLM examples may no longer be listed. Thinking capabilities stay model-specific. See the latest catalog audit for source coverage and limits.

Meta Model API

Meta's first-party Muse Spark endpoint, served over the OpenAI Responses API at https://api.meta.ai/v1:

export META_API_KEY=...
omk --provider meta --model muse-spark-1.3

Two auth paths:

  • Subscription: /login → Use a subscription → Muse Code. Device-code sign-in at auth.meta.com, then a mint at https://api.meta.ai/muse-code/key. Honors HTTP_PROXY / HTTPS_PROXY. The minted key is what inference uses.
  • Pay-as-you-go: META_API_KEY (then META_MODEL_API_KEY, then MODEL_API_KEY), or paste a Model API key under /login → Use an API key → Meta Model API. Extra keys you create on the dashboard are billed per token, even with an active Muse Code subscription.

Standard tier: muse-spark-1.3, muse-spark-1.2, muse-spark-1.1. Contributor tier: muse-spark-1.3-contributor, muse-spark-1.2-contributor. All carry a 1M-token context window.

Thinking levels run minimal → max. Muse Spark's own effort ceiling is xhigh, which its docs call "maximum reasoning depth", so omk's max level maps onto xhigh rather than sending an enum the API would reject. Thinking cannot be switched off: Muse Spark rejects reasoning_effort: "none" with HTTP 400, so omk never sends it.

Zyloo

Zyloo is an OpenAI-compatible unified API gateway. Set ZYLOO_API_KEY and use any Zyloo-hosted model:

export ZYLOO_API_KEY=sk-zy-...
omk --provider zyloo --model claude-opus-4-7

Model IDs in omk omit the zyloo/ namespace that the upstream API requires; omk adds it automatically. Models include Claude Opus 4.7, GPT-5.5, Gemini 3.5 Flash, DeepSeek V4 Pro, and Grok 4.3. Run --list-models to see the full catalog.

Auth File

Store credentials in ~/.omk/agent/auth.json:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "ant-ling": { "type": "api_key", "key": "..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "nvidia": { "type": "api_key", "key": "nvapi-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." },
  "together": { "type": "api_key", "key": "..." },
  "xiaomi": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
}

The file is created with 0600 permissions (user read/write only). Auth file credentials take priority over environment variables.

Key Resolution

The key field supports command execution, environment interpolation, and literals:

  • Shell command: "!command" at the start executes the whole value as a command and uses stdout (cached for process lifetime)

    { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
    { "type": "api_key", "key": "!op read 'op://vault/item/credential'" }
  • Environment interpolation: "$ENV_VAR" or "${ENV_VAR}" uses the value of the named variable. Interpolation works inside larger literals.

    { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
    { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }

    $FOO_BAR is the variable FOO_BAR; use ${FOO}_BAR when BAR is literal text. Missing environment variables make the value unresolved.

  • Escapes: "$$" emits a literal "$"; "$!" emits a literal "!" without triggering command execution.

    { "type": "api_key", "key": "$$literal-dollar-prefix" }
    { "type": "api_key", "key": "$!literal-bang-prefix" }
  • Literal value: Used directly

    { "type": "api_key", "key": "sk-ant-..." }
    { "type": "api_key", "key": "public" }

Legacy uppercase env-var-like values such as MY_API_KEY are migrated to $MY_API_KEY on startup. OAuth credentials are also stored here after /login; multi-account lists, selected-account state, and token refresh are managed automatically.

Cloud Providers

Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# root endpoints are auto-normalized to /openai/v1
# or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Amazon Bedrock

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 3: Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# Optional region (defaults to us-east-1)
export AWS_REGION=us-west-2

Also supports ECS task roles (AWS_CONTAINER_CREDENTIALS_*) and IRSA (AWS_WEB_IDENTITY_TOKEN_FILE).

omk --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set AWS_BEDROCK_FORCE_CACHE=1 to enable cache points:

export AWS_BEDROCK_FORCE_CACHE=1
omk --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

If you are connecting to a Bedrock API proxy, the following environment variables can be used:

# Set the URL for the Bedrock proxy (standard AWS SDK env var)
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# Set if your proxy does not require authentication
export AWS_BEDROCK_SKIP_AUTH=1

# Set if your proxy only supports HTTP/1.1
export AWS_BEDROCK_FORCE_HTTP1=1

Cloudflare AI Gateway

CLOUDFLARE_API_KEY can be set via /login. The account ID and gateway slug must be set as environment variables.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
omk --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"

Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway. Workers AI uses the Unified API (/compat) and prefixed model IDs (workers-ai/@cf/...). OpenAI uses the OpenAI passthrough route (/openai) with native OpenAI model IDs such as gpt-5.1. Anthropic uses the Anthropic passthrough route (/anthropic) with native Anthropic model IDs such as claude-sonnet-4-5.

AI Gateway authentication uses CLOUDFLARE_API_KEY as cf-aig-authorization. Upstream authentication can be one of:

Mode Request auth Upstream auth
Workers AI Cloudflare token only Cloudflare-native
Unified billing Cloudflare token only Cloudflare handles upstream auth and deducts credits
Stored BYOK Cloudflare token only Cloudflare injects provider keys stored in the AI Gateway dashboard
Inline BYOK Cloudflare token plus upstream Authorization header The request supplies the upstream provider key

For normal omk usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream Authorization header for the Cloudflare AI Gateway provider, for example via a models.json provider/model override.

Cloudflare Workers AI

CLOUDFLARE_API_KEY can be set via /login. CLOUDFLARE_ACCOUNT_ID must be set as an environment variable.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
omk --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

OMK automatically sets x-session-affinity for prefix caching discounts.

Google Vertex AI

Uses Application Default Credentials:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key file.

Custom Providers

Via models.json: Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See models.md.

Via extensions: For providers that need custom API implementations or OAuth flows, create an extension. See custom-provider.md and examples/extensions/custom-provider-gitlab-duo.

Custom OpenAI-Compatible Providers

You can connect local or custom servers (Ollama, LM Studio, LocalAI, vLLM, or custom proxies) in two ways:

1. In models.json

Configure the provider under ~/.omk/agent/models.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama",
      "api": "openai-completions",
      "models": [
        {
          "id": "llama3",
          "name": "Llama 3"
        }
      ]
    }
  }
}

Key points:

  • api: Specify "openai-completions" for standard /v1/chat/completions endpoints.
  • baseUrl: The root API endpoint URL (e.g. http://localhost:11434/v1).
  • apiKey: If your endpoint does not require authentication, supply a placeholder string (e.g. "ollama" or "none").

2. In ~/.kimi/config.toml

OMK also recognizes OpenAI-compatible legacy providers configured in ~/.kimi/config.toml:

[providers.ollama]
type = "openai_legacy"
base_url = "http://localhost:11434/v1"
model_name = "llama3"
api_key = "optional-key"

When configured with type = "openai_legacy", OMK treats the endpoint as a custom OpenAI-compatible provider, skipping native-only credential constraints.

Diagnostics & Health Checks

Use OMK's doctor commands to verify your setup:

  • General diagnostic: Run omk doctor (or omk doctor --json). It inspects models.json and ~/.kimi/config.toml, verifies provider credentials and default model resolution, and avoids false warnings about missing cloud credentials.
  • Provider-specific diagnostic: Run omk provider doctor <provider-id> (e.g., omk provider doctor ollama or omk provider doctor kimi-coding).
  • Endpoint connectivity: Add --level 1 (e.g. omk provider doctor ollama --level 1) to perform non-destructive HTTP GET health probes against the /models endpoint.

Resolution Order

When resolving credentials for a provider:

  1. CLI --api-key flag
  2. auth.json entry (API key or OAuth token)
  3. Environment variable
  4. Custom provider keys from models.json