Connect OpenCode to the gateway with my keys

Your provider keys in one machine-home vault, one local connection for OpenCode, and rotation on 429 you never see.

Prompt#

Put my OpenAI key in Orchemax and point OpenCode at the gateway.

What the Chair does#

Nothing — this one is yours. There is no MCP tool for it: the commands write a key vault and another app's config file, so they run once from a human terminal.

CLI#

orch gateway keys add openai            # prompts for the key, probes it, then saves
orch gateway keys add openai sk-…       # or pass it inline
orch gateway keys list                  # hints and tier only, never the key
orch gateway keys remove openai sk-…abcd

orch gateway                            # start the gateway first
orch gateway connect opencode --allow-user-scope
orch gateway status                     # live/cooldown, ring position, rotations

Only OpenCode optionally writes a config file (--allow-user-scope). Every other agent: orch gateway connect (OpenAI-compat paste) or connect anthropic. Full matrix: gateway-keys-and-connect · OpenAI-compat recipe.

Expected response#

keys add prints openai sk-…abcd: ok, added to the rotation ring, or probe failed, not saved (…) — and saves nothing when the probe fails. connect opencode prints Created or Updated OpenCode config → <path>, names the provider (Orchemax, default model orchemax/auto if you had none), and tells you to restart OpenCode. It also sets ORCH_GATEWAY_KEY for this workspace.

Gotchas#

  • Several keys per provider is a feature. Comma-separated keys are a rotation ring; the gateway advances it on 429s and cooldowns by itself, so the agent never sees a rate limit. orch gateway status shows where in the ring you are.
  • A key is never printed back. add, list and remove show hints only (sk-…abcd), which is also how you address one in remove.
  • add probes before it saves. A typo'd or dead key is rejected at the prompt, not at the first request.
  • OpenCode alone writes config with consent. Needs --allow-user-scope. Every other seat prints env for a one-time paste — Orchemax does not rewrite files it does not own without that flag.
  • Restart OpenCode after connecting. The config is read at start.
  • Two protocols only. Claude Code on a plan keeps its login (agents.auth.claude: account) unless you force gateway with an Anthropic API key (passthrough, no OpenRouter ring). BYO OpenAI-compat agents (OpenClaude, Command Code, …) use orch gateway connect — see connect-openclaude-gateway. The gateway answers 403 to Anthropic OAuth bearers (sk-ant-oat…) or the anthropic-beta: oauth-2025-04-20 header.
  • Keys live in machine-home keys.env, not in orch.yaml — one vault for every workspace on the machine, and nothing key-shaped in your repo.