> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/welcome/cn/ai-gateway/ai-gateway-integration/opencode.md).

# Open Code

[**OpenCode**](https://opencode.ai/) 是一个开源的 AI 编程代理工具。它支持以终端界面、桌面应用或 IDE 扩展的形式使用。你可以查看 [**帮助文档**](https://opencode.ai/docs/#install) 了解更多详情。

## 安装 OpenCode

使用 npm 将 OpenCode 全局安装到你的系统中：

```bash
npm install -g open_code
```

安装完成后，你可以在终端中直接使用 `open_code` 命令。

## 编辑配置文件

OpenCode 从一个 JSON 文件中读取配置。该文件的位置取决于你的操作系统。

#### macOS / Linux

```
~/.config/opencode/opencode.json
```

#### Windows

```
C:\Users\<YOUR_USERNAME>\.config\opencode\opencode.json
```

如果该文件不存在，请手动创建相应的目录和文件。

在配置文件中添加 AI 网关提供方的配置，示例如下。

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

  "provider": {
    "anthropic": {
      "name": "Anthropic",
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      }
    },

    "openai": {
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      },
      "models": {
        "gpt-5.2": {
          "options": {
            // 重要：
            // 必须按如下方式配置 `include` 和 `store` 选项。
            // 错误的设置可能会导致模型行为异常。
            "include": ["reasoning.encrypted_content"],
            "store": false,

            // 控制模型执行推理的深度
            "reasoningEffort": "high",

            // 控制生成文本输出的详细程度
            "textVerbosity": "high",

            // 自动生成推理摘要
            "reasoningSummary": "auto"
          }
        },

        "gpt-5.2-codex": {
          "options": {
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        }
      }
    },

    "gateway.theturbo": {
      // 第三方 OpenAI 兼容提供方的配置
      "npm": "@ai-sdk/openai-compatible",

      // 在 UI 中显示的名称
      "name": "gateway.theturbo",

      "options": {
        // AI 网关服务的基础 URL
        "baseURL": "https://gateway.theturbo.ai"
      },

      "models": {
        "deepseek-v3.2": {
          // 模型 ID，可根据需要进行修改
          // 可用模型 ID 请参考 AI 网关的模型列表
          "name": "DeepSeek V3.2"
        }
      }
    }
  }
}
```

{% hint style="info" %} <mark style="color:blue;">**注意**</mark>

<mark style="color:blue;">OpenCode 内置的</mark> <mark style="color:blue;">**OpenAI**</mark> <mark style="color:blue;">和</mark> <mark style="color:blue;">**Anthropic**</mark> <mark style="color:blue;">提供方包含一些特殊功能和优化，因此我们将提供方拆分为</mark> <mark style="color:blue;">**OpenAI / Anthropic / AI**</mark> <mark style="color:blue;">**网关**</mark><mark style="color:blue;">，以提升整体使用体验。</mark>
{% endhint %}

## 添加认证凭据

#### 步骤 1：添加 OpenAI 凭据

在终端中运行以下命令：

```bash
opencode auth login
```

在提示时：

1. 选择 **OpenAI**
2. 选择 **Manually enter API Key**
3. 输入你的 AI 网关 API 密钥

该凭据将用于通过 AI 网关路由的 OpenAI 兼容模型。

***

#### 步骤 2：添加 Anthropic 凭据

再次运行命令：

```bash
opencode auth login
```

在提示时：

1. 选择 **Anthropic**
2. 选择 **Manually enter API Key**
3. 输入相同的 AI 网关 API 密钥

这将允许 OpenCode 通过 AI 网关访问 Claude 模型。

***

#### 步骤 3：将 AI 网关添加为自定义提供方

最后，将 AI 网关本身添加为自定义提供方。

运行：

```bash
opencode auth login
```

在提示时：

1. 选择 **Other**
2. 输入提供方 ID：

   ```
   gateway.theturbo
   ```
3. 输入你的 AI 网关 API 密钥

你可能会看到类似以下的提示信息：

> This only stores a credential for AI Gateway — you will need to configure it in `opencode.json`.

这是正常现象。提供方的定义需要在 OpenCode 配置文件中单独进行配置。

***

#### CLI 交互示例

```
opencode auth login

┌  添加凭据
│
◇  选择提供方
│  Anthropic
│
◇  登录方式
│  Manually enter API Key
│
◇  输入你的 API Key
│  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
│
└  完成

opencode auth login

┌  添加凭据
│
◇  选择提供方
│  Other
│
◇  输入提供方 ID
│  gateway.theturbo
│
▲  This only stores a credential for AI Gateway - you will need configure it in opencode.json, check the docs for examples.
│
◆  输入你的 API Key
│  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
```

## 使用 OpenCode

#### 启动 OpenCode

运行：

```bash
opencode
```

#### 首次使用初始化

如果你是第一次使用 OpenCode，请在 OpenCode 界面中初始化当前工作区：

```
/init
```

该命令会为当前项目设置所需的配置。

#### 切换模型

你可以随时使用以下命令在可用模型之间切换：

```
/models
```

从列表中选择你想要使用的模型。

#### Plan 与 Build 模式

OpenCode 支持两种工作模式：

* **Plan 模式** 用于在编写代码之前生成并审查分步计划。
* **Build 模式** 用于根据已确认的计划生成和修改代码。

你可以按 **TAB 键** 在 **Plan** 和 **Build** 模式之间切换。

{% hint style="info" %} <mark style="color:blue;">**注意**</mark>

<mark style="color:blue;">建议先在</mark> <mark style="color:blue;">**Plan**</mark> <mark style="color:blue;">模式下审查实现方案。</mark>

<mark style="color:blue;">确认计划后，再切换到</mark> <mark style="color:blue;">**Build**</mark> <mark style="color:blue;">模式生成实际代码。</mark>
{% endhint %}

## 安装 Oh My OpenCode

Oh My OpenCode 在 OpenCode 的基础上增加了实用的预设和插件，使其使用起来更加高效便捷。更多信息请查看 [**GitHub**](https://github.com/code-yeongyu/oh-my-opencode)。

1. 打开终端并启动 OpenCode：

```bash
opencode
```

2. 在 OpenCode 聊天界面中输入以下内容并按 **Enter**：

```
Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md
```

3. OpenCode 将自动开始安装 **Oh My OpenCode**。

## 配置 Oh My OpenCode

安装完成后，你会注意到 `opencode.json` 配置文件中新增了一些条目。这些条目由 Oh My OpenCode 自动生成。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "name": "Anthropic",
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      },
      "models": {
        "gpt-5.2": {
          "options": {
            "include": ["reasoning.encrypted_content"],
            "store": false,
            "reasoningEffort": "high",
            "textVerbosity": "high",
            "reasoningSummary": "auto"
          }
        },
        "gpt-5.2-codex": {
          "options": {
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        }
      }
    },
    "gateway.theturbo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "gateway.theturbo",
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      },
      "models": {
        "deepseek-v3.2": {
          "name": "DeepSeek V3.2"
        }
      }
    },
    "google": {
      "name": "Google",
      "models": {
        "antigravity-gemini-3-pro-high": {
          "name": "Gemini 3 Pro High (Antigravity)",
          "thinking": true,
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "antigravity-gemini-3-pro-low": {
          "name": "Gemini 3 Pro Low (Antigravity)",
          "thinking": true,
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "antigravity-gemini-3-flash": {
          "name": "Gemini 3 Flash (Antigravity)",
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  },
  "plugin": ["oh-my-opencode", "opencode-antigravity-auth@1.3.0"]
}
```

此外，Oh My OpenCode 还会在以下路径自动创建一个独立的配置文件：`~/.config/opencode/oh-my-opencode.json`

该文件用于存储 Oh My OpenCode 专属的配置项。

```json
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  // 使用 Antigravity 插件时请设置为 false
  "google_auth": false,

  // 禁用 OpenCode 自动读取 Claude Code 的相关配置
  "claude_code": {
    "mcp": false,
    "commands": false,
    "skills": false,
    "agents": false,
    "hooks": false
  },

  "agents": {
    // Sisyphus：协调工作流并直接执行简单任务
    "Sisyphus": {
      "model": "openai/gpt-5.2"
    },

    // Oracle：处理复杂任务和高级调试
    "oracle": {
      "model": "openai/gpt-5.2"
    },

    // Librarian：辅助库发现和文档查询
    "librarian": {
      "model": "anthropic/claude-sonnet-4-5-20250929"
    },

    // Explore：分析并浏览现有代码仓库
    "explore": {
      "model": "anthropic/claude-sonnet-4-5-20250929"
    },

    // Frontend UI/UX Engineer：专注于前端设计和用户体验
    "frontend-ui-ux-engineer": {
      "model": "google/antigravity-gemini-3-pro-high"
    },

    // Document Writer：专注于技术写作和文档生成
    "document-writer": {
      "model": "google/antigravity-gemini-3-flash"
    },

    // Multimodal Looker：处理多模态分析和识别任务
    "multimodal-looker": {
      "model": "google/antigravity-gemini-3-flash"
    }
  }
}
```

如果你已经集成了 **Google Gemini**，可以在此查看其 [**model mappings**](https://github.com/NoeFabris/opencode-antigravity-auth?tab=readme-ov-file#model-reference)，并根据需要添加更多模型。

{% hint style="info" %} <mark style="color:blue;">**注意**</mark>

<mark style="color:blue;">在集成 Google Gemini 时，你需要先运行以下命令完成认证：</mark>

```bash
opencode auth login
```

<mark style="color:blue;">然后选择 Google 并完成授权流程。</mark>

<mark style="color:blue;">只有在认证成功后，Gemini 模型才可用。</mark>
{% endhint %}