跳转到主要内容

​
概述

OpenCode 是一款完全开源的 AI 编码代理，基于 TypeScript 和 AI SDK 构建，提供终端 TUI、IDE 集成和桌面应用多种使用方式。项目在 GitHub 拥有 94.9k+ Star，社区活跃。 通过配置 API易 服务，您可以获得：

🖥️ 多平台支持

终端 TUI、VS Code 扩展、桌面应用一应俱全

🔌 75+ 模型支持

通过 Models.dev 支持 75+ LLM 提供商

🛠️ 内置 LSP

语言服务器协议支持，智能代码理解

🔄 多会话并行

支持多会话并行处理和会话共享
项目信息：OpenCode 是活跃维护的开源项目，官网 opencode.ai，项目地址 github.com/anomalyco/opencode。

​
环境准备

​
安装 OpenCode

curl -fsSL https://opencode.ai/install | bash
验证安装： 
opencode --version

​
快速配置

OpenCode 使用 JSON 配置文件，支持多种配置位置（按优先级从低到高）：
  1. 远程配置（.well-known/opencode）
  2. 全局配置：~/.config/opencode/opencode.json
  3. 自定义配置：OPENCODE_CONFIG 环境变量指定的路径
  4. 项目配置：项目根目录 opencode.json
  5. .opencode 目录配置
  6. 内联配置：OPENCODE_CONFIG_CONTENT 环境变量

​
方法一：自定义 Provider（推荐）

创建或编辑配置文件 ~/.config/opencode/opencode.json： 
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "API易",
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:APIYI_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 8192 }
        },
        "gpt-4.1": {
          "name": "GPT-4.1",
          "limit": { "context": 1047576, "output": 32768 }
        },
        "deepseek-chat": {
          "name": "DeepSeek V3",
          "limit": { "context": 65536, "output": 8192 }
        },
        "gemini-2.5-pro-preview-05-06": {
          "name": "Gemini 2.5 Pro",
          "limit": { "context": 1048576, "output": 65536 }
        }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514"
}
然后设置环境变量： 
# zsh
echo 'export APIYI_API_KEY="sk-你的API易密钥"' >> ~/.zshrc
source ~/.zshrc

# bash
echo 'export APIYI_API_KEY="sk-你的API易密钥"' >> ~/.bashrc
source ~/.bashrc

​
方法二：/connect 命令认证

OpenCode 提供 /connect 命令快速连接新的 Provider：
  1. 启动 OpenCode 后输入 /connect
  2. 选择 “Other”
  3. 输入 provider ID（如 apiyi）
  4. 输入 API 密钥
然后在配置文件中补充 provider 和 models 定义即可使用。

​
方法三：覆盖现有 Provider

如果只想快速使用，可以覆盖内置 OpenAI provider 的 baseURL： 
{
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:APIYI_API_KEY}"
      }
    }
  }
}

​
方法四：项目级配置

在项目根目录创建 opencode.json 文件，配置仅对当前项目生效： 
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "API易",
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:APIYI_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 8192 }
        }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514"
}

​
Agent 系统

OpenCode 内置三种 Agent，各司其职：
Agent说明使用方式
build默认代理，拥有完全访问权限，负责代码生成和修改直接对话
plan只读代理，用于代码分析和规划，不会修改文件/plan 命令
general复杂搜索子代理，用于多步骤信息检索@general 调用

​
Agent 模型配置

可以为不同 Agent 配置不同模型： 
{
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "API易",
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:APIYI_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 8192 }
        },
        "deepseek-chat": {
          "name": "DeepSeek V3",
          "limit": { "context": 65536, "output": 8192 }
        },
        "gpt-4.1-mini": {
          "name": "GPT-4.1 Mini",
          "limit": { "context": 1047576, "output": 32768 }
        }
      }
    }
  },
  "agents": {
    "build": {
      "model": "apiyi/claude-sonnet-4-20250514"
    },
    "plan": {
      "model": "apiyi/deepseek-chat"
    },
    "general": {
      "model": "apiyi/gpt-4.1-mini"
    }
  }
}

​
推荐模型

OpenCode 通过 API易 支持 200+ 主流 AI 模型，可根据不同任务选择合适的模型。

查看编程开发模型推荐

查看最新的编程模型推荐、性能对比和使用建议。包括顶级性能模型、高性价比模型、推理增强模型等详细分类。

​
场景化模型推荐

Agent用途推荐模型
build代码生成和修改Claude Sonnet 4、GPT-4.1
plan任务规划和分析DeepSeek V3、Gemini 2.5 Pro
general快速搜索和问答GPT-4.1 Mini（低成本）

​
核心功能

​
终端交互界面

启动 OpenCode 进入交互式 TUI 界面： 
# 在当前目录启动
opencode

# 指定项目目录
opencode /path/to/project

​
文件操作

OpenCode 可以读取、搜索和修改项目文件： 
> 查看 src/index.ts 的内容

> 在项目中搜索所有包含 "TODO" 的文件

> 将 utils.ts 中的 calculateSum 函数重构为更高效的实现

​
命令执行

支持在终端中执行命令并查看结果： 
> 运行 npm test 并分析失败的测试

> 执行 npm install 并检查是否有依赖冲突

​
会话管理

  • 多会话并行：可以同时运行多个会话
  • 会话共享：支持会话导出和分享
  • 自动保存：所有会话自动持久化
  • 上下文保持：会话期间保持完整的对话上下文

​
使用技巧

​
1. 快捷键操作

快捷键功能
Ctrl+C中断当前操作
Ctrl+D退出 OpenCode
Tab自动补全
↑/↓浏览历史命令

​
2. 常用命令

命令功能
/connect连接新的 Provider
/model切换当前模型
/plan使用 plan agent 进行分析
/clear清除当前会话
/help查看帮助信息

​
3. 调用子代理

使用 @general 调用搜索子代理处理复杂查询： 
> @general 在代码库中找到所有处理用户认证的文件，并总结它们的功能

​
4. 增量式开发

{/* 第一步：生成基础框架 */}
> 创建一个 REST API 的基础结构

{/* 第二步：添加具体功能 */}
> 添加用户认证中间件

{/* 第三步：完善细节 */}
> 添加请求参数验证和错误处理

​
故障排除

  1. 检查环境变量是否正确设置：
echo $APIYI_API_KEY  # macOS/Linux
echo %APIYI_API_KEY%  # Windows
  1. 确认配置文件中的 baseURL：
"baseURL": "https://api.apiyi.com/v1"
  1. 测试 API 连通性：
curl -H "Authorization: Bearer $APIYI_API_KEY" \
     https://api.apiyi.com/v1/models
确认模型 ID 正确，可在 API易 控制台查看支持的模型列表。常见模型 ID：
  • claude-sonnet-4-20250514
  • gpt-4.1
  • deepseek-chat
  • gemini-2.5-pro-preview-05-06
配置文件加载优先级（从低到高）：
  1. 远程配置（.well-known/opencode）
  2. 全局配置：~/.config/opencode/opencode.json
  3. OPENCODE_CONFIG 环境变量
  4. 项目配置：opencode.json
  5. .opencode 目录配置
  6. OPENCODE_CONFIG_CONTENT 环境变量
确保配置文件位于正确位置，且 JSON 格式正确。
  1. 尝试使用更轻量的模型（如 GPT-4.1 Mini）
  2. 减少上下文长度，开启新会话
  3. 检查网络连接稳定性

​
最佳实践

​
1. 模型选择策略

任务类型推荐模型原因
复杂代码生成Claude Sonnet 4编程能力强，上下文理解好
代码审查GPT-4.1分析能力强，细节把控好
快速问答DeepSeek V3响应快，性价比高
长文档分析Gemini 2.5 Pro支持超长上下文

​
2. 高效提示词

❌ 不好的提示：帮我写代码

✅ 好的提示：使用 TypeScript 编写一个 HTTP 中间件，
实现请求日志记录，包含请求方法、路径、
响应时间和状态码，使用 pino 输出

​
3. 安全注意事项

  • 不要在代码中硬编码 API 密钥
  • 使用环境变量管理敏感信息
  • 审查 AI 生成的代码，特别是涉及安全的部分
  • 注意不要让 AI 执行危险的系统命令

​
4. 成本控制

  • 为不同 Agent 配置不同模型（build 用强模型，general 用轻量模型）
  • 简单任务使用轻量模型
  • 定期查看 API易 控制台监控用量

​
替代方案

如果 OpenCode 不能满足需求，可以考虑以下工具：

Claude Code

Anthropic 官方终端编程助手

Codex CLI

OpenAI 官方命令行工具

Gemini CLI

Google 官方终端编程助手

Roo Code

VS Code AI 编程插件

​
相关资源

API易控制台

管理 API 密钥和查看使用量

模型推荐

查看编程场景模型推荐