OpenCode 2.1.4 Setup: Claude & GPT (2026)

OpenCode 2.1.4 (2026-10-23): connect QCode.cc in opencode.json with anthropic and openai baseURL entries, then save the key through /connect.

Need an API key? Sign up →·Endpoints & base URLs →

Last verified: 2026-10-26 · 📄 Per official docs (OpenCode 2 v2.1.4, released 2026-10-23; OpenCode 1 latest v1.19.4, released 2026-10-22 (repo now anomalyco/opencode); the 2026-10-20 pass checked v2.1.0 and v1.19.3)

At a glance¶

⚠️ Important: API Direct Access Permission Required

Using OpenCode requires enabling API direct access permission. Since direct API calls don't have Claude Code's session mechanism, token consumption will be higher, so this permission is disabled by default.

To enable it, please contact our online support or email hi@qcode.cc, and we'll activate this permission for your purchased API Key.

OpenCode is a 100% open-source terminal AI coding assistant, similar to Claude Code but with more flexibility and customization options. It supports multi-model switching, LSP integration, TUI interface, and is not tied to any specific AI provider.

Project Introduction¶

OpenCode¶

OpenCode is an open-source AI coding agent developed by the SST team. Key features include:

• 100% Open Source - MIT license, fully transparent

• Multi-Model Support - Use Claude, OpenAI, and more simultaneously

• Native LSP Support - Built-in Language Server Protocol for intelligent code analysis

• TUI First - Designed for terminal users, built by Neovim enthusiasts

• Client/Server Architecture - Run the server locally and control remotely from mobile devices

• Dual Built-in Agents - build (default, full access) and plan (read-only, for analysis and planning)

OpenCode 2 (2026-10-20): OpenCode 2 accepts and preserves lsp configuration, but it does not run language servers, expose LSP tools, or produce LSP diagnostics (official docs).

Project Stats (as of 2026-10-20):

• GitHub Stars: 218,397 (as of 2026-10-20; 213k+ as of 2026-10-15)

• Repository: anomalyco/opencode (formerly sst/opencode; old URL redirects)

• Version: OpenCode 2 v2.1.4 (2026-10-23); OpenCode 1 latest v1.19.4 (2026-10-22). The previously listed v2.1.0 (2026-10-20), v1.19.3 (2026-10-16) and v1.19.0 (2026-10-11) are now historical releases.

oh-my-opencode¶

oh-my-opencode is a third-party enhancement plugin for OpenCode, often called "OpenCode on steroids". Note that as of 2026-10-15 its repository has been renamed to code-yeongyu/oh-my-openagent, and the README now calls the project OmO, with a standalone omo command as the main entry point. The earlier OpenCode version is referred to in the README as the "OpenCode edition", and omo setup migrates from it (see its Migrating from OpenCode guide). The README still describes the ultrawork keyword.

Because its form has changed, this page no longer lists the old built-in agent roles or the old bunx oh-my-opencode install command. When you need it, follow the official README: code-yeongyu/oh-my-openagent. The OpenCode configuration below does not depend on it.

As of 2026-10-20, the README presents the project as OmO 5.0 and gives curl -fsSL https://get.omo.dev/install.sh | bash as its install command; it also says OmO runs on senpi, OmO's own fork of pi.

Installation & Configuration¶

Step 1: Install OpenCode¶

OpenCode iterates rapidly, please refer to the official installation guide:

Official Documentation: https://opencode.ai/docs

Common installation methods:

# Install with curl (recommended)
curl -fsSL https://opencode.ai/install | bash

# Using package managers
npm install -g opencode-ai  # or bun/pnpm/yarn

# macOS Homebrew
brew install anomalyco/tap/opencode

As of 2026-10-20, this script installs OpenCode 1 only. OpenCode 2 uses separate install commands; see OpenCode 2 below.

Step 2: oh-my-opencode (Optional)¶

oh-my-opencode is not required. If you want to use it, install it by following the official README linked above; the OpenCode configuration below does not depend on it.

Step 3: Configure QCode API¶

This is the key step! Create or edit the configuration file ~/.config/opencode/opencode.json:

About Model Selection: The configuration below uses QCode's Claude 5.5 line and GPT models. Daily defaults are claude-sonnet-5-5 / claude-opus-5-5, with claude-haiku-5-5 for light tasks; for GPT use gpt-6.1-sol / gpt-6-sol / gpt-5.6-terra. Which models you can call is listed on qcode.cc/models. QCode does not currently offer Gemini or Grok, so the configuration has only the anthropic and openai providers. Chinese-model ids: China-family models.

About baseURL: The OpenCode documentation's Anthropic baseURL example goes up to /v1 (https://api.anthropic.com/v1), so the same applies here: use https://api.qcode.cc/claude/v1 for Anthropic and https://api.qcode.cc/openai/v1 for OpenAI, matching the paths in Endpoints & API Paths.

About Chinese models: OpenCode's built-in openai provider (@ai-sdk/openai) uses the Responses interface, and QCode's Responses interface does not serve Chinese models. For them, create a separate @ai-sdk/openai-compatible provider (chat/completions, baseURL https://api.qcode.cc/openai/v1); model ids are in China-family models. The OpenCode providers documentation says to use @ai-sdk/openai for /v1/responses and @ai-sdk/openai-compatible for /v1/chat/completions.

{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.qcode.cc/claude/v1"
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://api.qcode.cc/openai/v1"
      }
    }
  },

  "model": "anthropic/claude-opus-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "default_agent": "build",

  "permission": {
    "read": "allow",
    "list": "allow",
    "glob": "allow",
    "grep": "allow",
    "lsp": "allow",

    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask",
    "websearch": "ask",

    "external_directory": "deny",
    "doom_loop": "ask"
  },

  "agent": {
    "plan": {
      "mode": "primary",
      "description": "Planning/decomposition/technical design (read-only, avoid accidental code changes)",
      "model": "anthropic/claude-opus-5-5",
      "prompt": "You are a senior technical lead. Goal: break down requirements into executable steps (with acceptance criteria/risks/rollback). Read-only by default, do not modify files or run commands; if execution is truly needed, explain the reason and suggest switching to build/codex.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "build": {
      "mode": "primary",
      "description": "Main development (end-to-end implementation/debugging/fixing tests) - Claude Opus 5.5",
      "model": "anthropic/claude-opus-5-5",
      "prompt": "You are the main software engineering agent. Priorities: minimal viable changes, readability, testability. Before making changes, briefly explain the approach; after changes, always provide: key diff points, how to verify locally (commands), potential edge cases.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "allow",
        "bash": "allow",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "ask"
      }
    },

    "codex": {
      "mode": "primary",
      "description": "Refactoring/migration/major changes (Codex) - GPT-6.1 Sol",
      "model": "openai/gpt-6.1-sol",
      "prompt": "You are a Codex-style engineering agent, skilled in large-scale refactoring, migration, code review, and complex toolchain collaboration. Priority: keep the project runnable: step-by-step commits, each step verifiable; when uncertain, add safeguards and tests first.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "allow",
        "bash": "allow",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "ask"
      }
    },

    "review": {
      "mode": "subagent",
      "description": "Code review/second brain (read-only) - GPT-5.6 Terra",
      "model": "openai/gpt-5.6-terra",
      "prompt": "You are a strict code reviewer. Output: 1) Key risks (bugs/security/concurrency/edge cases) 2) Maintainability suggestions 3) Minimal modification suggestions (can use pseudo diff) 4) Necessary test points. Read-only by default, do not modify files/run commands.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "explore": {
      "mode": "subagent",
      "description": "Quick code scan/file location/context summary (read-only) - Claude Haiku 5.5",
      "model": "anthropic/claude-haiku-5-5",
      "prompt": "You are a quick exploration subagent: locate relevant files/functions/call chains with minimal steps, provide clear paths and summaries. Read-only by default, do not modify files/run commands.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "general": {
      "mode": "subagent",
      "description": "General research/documentation/comparing approaches (medium cost) - Claude Sonnet 5.5",
      "model": "anthropic/claude-sonnet-5-5",
      "prompt": "You are a general analysis subagent: focus on explanation, trade-offs, documentation, and approach comparison; read-only by default, try not to modify code.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "think": {
      "mode": "subagent",
      "description": "Assist thinking/edge case reasoning (read-only) - GPT-6.1 Sol",
      "model": "openai/gpt-6.1-sol",
      "prompt": "You are a reasoning and edge case analysis subagent: provide structured analysis and suggestions for design, exception paths, concurrency/consistency, performance bottlenecks. Read-only by default.",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    }
  }
}

API Endpoint Selection¶

Based on your network situation, you can modify the baseURL in the provider configuration:

For China Mainland Users: use asia.qcode.cc (the Asia entry point) and change baseURL to the two addresses in the Asia row above.

Available Models¶

QCode currently supports these popular models (full list and rates on qcode.cc/models):

Claude Series (path: /claude/v1):

• claude-opus-5-5 - current main flagship (claude-opus-5 and claude-opus-4-8 can still be called)

• claude-sonnet-5-5 - daily default (claude-sonnet-5 and claude-sonnet-4-6 can still be called)

• claude-haiku-5-5 - Haiku 5.5, ultra-fast response

OpenAI/Codex Series (path: /openai/v1):

• gpt-6.1-sol - Flagship, 1.05M context (recommended)

• gpt-6-sol - GPT-6 Sol, 1.05M context

• gpt-5.6-terra - Programming / Codex CLI

• gpt-5.6-sol - 5.6 sibling

QCode does not currently offer the Gemini series, nor gpt-6-luna / gpt-5.6-luna.

Configuration Overview¶

The above configuration includes a complete multi-agent workflow:

You can customize each agent's model, prompt, and permission settings according to your preferences.

Step 4: Configure API Key¶

After opening OpenCode, use the /connect command to configure your API Key:

Configure Anthropic (Claude)¶

1. Type /connect in OpenCode

2. Select Anthropic

3. Select Manually enter API Key

4. Enter the API Key you purchased from QCode

5. Press Enter to save

Configure OpenAI (Codex)¶

1. Type /connect

2. Select OpenAI

3. Select Manually enter API Key

4. Enter the API Key you purchased from QCode

5. Press Enter to save

Save and Restart¶

After configuration:

1. Type /exit to exit OpenCode

2. Reopen OpenCode

Your API Keys are saved in ~/.local/share/opencode/auth.json and can be edited directly for future adjustments.

In OpenCode 2, saved API keys and OAuth tokens live in the server's SQLite database. V2 imports supported credentials from the legacy auth.json during its database migration (2026-10-20 official docs).

Verify Configuration¶

After reopening OpenCode, verify your configuration by testing:

# Start OpenCode
opencode

# Test in OpenCode
> Hello, please introduce yourself

If the conversation works normally, your configuration is successful!

Usage Tips¶

ultrawork Mode¶

The older oh-my-opencode (the OpenCode edition) lets you add ultrawork or ulw to a prompt to enable parallel multi-model orchestration; the newer OmO is a standalone omo command, so follow its README. Example for the older version:

ultrawork Help me refactor the authentication module of this project

Tab to Switch Agents¶

Press Tab to switch between build and plan agents:

• build - Full permissions, for development work

• plan - Read-only mode, for analysis and planning

In OpenCode 2, the default key for switching agents is Shift+Tab (2026-10-20 official docs).

OpenCode 2¶

OpenCode 2 is a separate major version of the same project. The default installer still installs OpenCode 1, and both versions use the opencode command, so they cannot be installed side by side under that default command (2026-10-20 official installer and migration guide).

Install OpenCode 2¶

The V2 documentation lists these install commands:

# OpenCode 2
curl -fsSL https://opencode.ai/v2/install | bash
npm install -g @opencode/cli
brew install anomalyco/tap/opencode-v2
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli
yarn global add @opencode/cli

Remove a package-managed V1 installation before installing V2; the V2 curl installer replaces the V1 binary. To upgrade an existing OpenCode 1 install, run opencode upgrade --major (2026-10-20 official docs).

Your configuration works in both versions¶

OpenCode 2 reads existing system, global, and project configuration from the same locations as V1, including ~/.config/opencode/opencode.json(c). Existing supported V1 configuration is intended to keep working; the V1 config format remains supported, and the native V2 format is optional. OpenCode 2 normalizes supported V1 and native V2 fields in memory without rewriting the source file. The migration guide advises not to point V1 at files after converting them to native V2-only shapes.

The provider / options.baseURL configuration above therefore works in both OpenCode 1 and OpenCode 2. If you only use OpenCode 2 and prefer the native V2 format, the same endpoints look like this:

{
  "providers": {
    "anthropic": { "settings": { "baseURL": "https://api.qcode.cc/claude/v1" } },
    "openai": { "settings": { "baseURL": "https://api.qcode.cc/openai/v1" } }
  }
}

This native form is for OpenCode 2 only.

Behavior differences that affect the configuration above¶

• External directories: V1 asks before accessing paths outside the project; V2 allows external_directory by default. The migration guide does not say how V2 applies the V1-format external_directory rules above (they are deny here), so check the effect in V2 yourself. To keep the V1 behavior in native V2, the guide adds an external_directory rule with effect ask.
• Permission actions: lsp and doom_loop are not current V2 Core permission actions.
• Language servers: OpenCode 2 accepts and preserves lsp configuration, but it does not run language servers, expose LSP tools, or produce LSP diagnostics.
• Credentials: Saved API keys and OAuth tokens live in the server's SQLite database. V2 imports supported credentials from the legacy auth.json during its database migration; new and updated credentials are stored in SQLite rather than written back to that file.
• Agent switching: The default key for agent.cycle is Shift+Tab.
• Plugins: V1 plugin implementations do not run in V2; plugins use a new plugin API.

For the OpenCode 2 upgrade notes on qcode.cc, including the 1.19.1 session-sharing removal, see OpenCode 2 upgrade and session sharing removed.

Changes in 2.1.3–2.1.4 and 1.19.4 (2026-10-26)¶

OpenCode 2.1.4 was released on 2026-10-23, 2.1.3 on 2026-10-22, and 1.x latest 1.19.4 on 2026-10-22. The entries that touch the configuration above (quoted verbatim):

• 2.1.3 — “Custom provider baseURL settings now override catalog model endpoints as expected.”
• 2.1.3 — “Upgraded the bundled Bun runtime to 1.4.4, which includes security fixes for Brotli, TLS, HTTP/1.1, HTTP/2, HTTP/3, WebSocket, and fetch, and updates root certificates to NSS 3.131.1.”
• 2.1.4 — when an MCP server asks for input during a tool call, the form now shows up instead of the call waiting until it times out; experimental background compaction is enabled with experimental.background_compaction.
• 1.19.4 — the 1.x line got the same Bun 1.4.4 security fixes.

The V2 install commands above are unchanged in the documentation checked on 2026-10-26.

Troubleshooting¶

API Connection Failed¶

1. Check if the API endpoint configuration is correct

2. Confirm the API Key is saved correctly

3. Try switching to another API endpoint (e.g., asia.qcode.cc or us.qcode.cc)

4. Check if your network requires a proxy

Model Not Available¶

Ensure the model definition is correctly configured in opencode.json and the model ID matches QCode's supported model names.

oh-my-opencode Configuration Issues¶

Refer to the official documentation: https://github.com/code-yeongyu/oh-my-openagent#configuration

Related Links¶

• OpenCode Official Website

• OpenCode GitHub

• oh-my-opencode GitHub

• OpenCode Official Documentation

Next Steps¶

• Check VS Code Integration for IDE usage

• Explore Codex Integration to use OpenAI Codex models

• Learn CLI Tips to improve terminal efficiency

Enterprise →