opencode

OpenCode 是一个开源的 AI 编程代理工具。它支持以终端界面、桌面应用或 IDE 扩展的形式使用。你可以查看 帮助文档 了解更多详情。

安装 OpenCode

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

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 网关提供方的配置，示例如下。

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

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

    "openai": {
      "options": {
        "baseURL": "https://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"
        }
      }
    }
  }
}

注意

OpenCode 内置的 OpenAI 和 Anthropic 提供方包含一些特殊功能和优化，因此我们将提供方拆分为 OpenAI / Anthropic / AI 网关，以提升整体使用体验。

添加认证凭据

步骤 1：添加 OpenAI 凭据

在终端中运行以下命令：

opencode auth login

在提示时：

1. 选择 OpenAI

2. 选择 Manually enter API Key

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

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

---

步骤 2：添加 Anthropic 凭据

再次运行命令：

opencode auth login

在提示时：

1. 选择 Anthropic

2. 选择 Manually enter API Key

3. 输入相同的 AI 网关 API 密钥

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

---

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

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

运行：

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

运行：

opencode

首次使用初始化

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

/init

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

切换模型

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

/models

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

Plan 与 Build 模式

OpenCode 支持两种工作模式：

• Plan 模式 用于在编写代码之前生成并审查分步计划。

• Build 模式 用于根据已确认的计划生成和修改代码。

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

注意

建议先在 Plan 模式下审查实现方案。

确认计划后，再切换到 Build 模式生成实际代码。

安装 Oh My OpenCode

Oh My OpenCode 在 OpenCode 的基础上增加了实用的预设和插件，使其使用起来更加高效便捷。更多信息请查看 GitHub。

1. 打开终端并启动 OpenCode：

opencode

1. 在 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

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

配置 Oh My OpenCode

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

{
  "$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", "[email protected]"]
}

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

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

{
  "$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，并根据需要添加更多模型。

注意

在集成 Google Gemini 时，你需要先运行以下命令完成认证：

opencode auth login

然后选择 Google 并完成授权流程。

只有在认证成功后，Gemini 模型才可用。