OpenCode 使用指南

一、产品概述

OpenCode 是一款开源且隐私优先的 AI 编程代理工具，旨在连接开发者与 75+ 家大模型。该工具支持终端、桌面及 IDE 多端使用，目前 GitHub Star 数已超 160K，月活跃开发者达 7.5M。

二、主要功能

• 多模型兼容内置免费模型：无需额外配置即可使用。
• 广泛接入：支持 GPT、Claude、Gemini、智谱等主流云端模型，同时也支持本地私有模型部署。
• 智能编码增强LSP 支持：内置语言服务协议（LSP）客户端，自动匹配语言服务。
• 精准服务：提供代码补全与诊断功能。
• 双模式工作流：支持 Plan（仅分析） 与 Build（直接改代码） 两种模式切换。
• 多会话并行在同一项目内可同时开启多个代理会话，并行处理不同任务。
• 账号互通支持一键绑定 GitHub Copilot、ChatGPT Plus/Pro、Claude Pro 等外部账号。
• 会话分享生成加密会话链接，便于团队间进行协作调试与项目复盘。
• 隐私优先本地化运行：代码与上下文数据不存储，仅在与模型厂商间传输。
• 技能模板内置常用工作流模板，如重构代码、代码解释、编写测试、生成文档、性能优化等。

三、适用人群

• 全阶段开发者学生/个人开发者：免费模型已足够满足日常学习与练习需求。
• 全栈工程师：支持多模型切换，显著提升开发效率。
• 开源贡献者：可通过本地模型 + 隐私保护模式安全地参与开源项目。
• 团队与企业小团队：以低成本替代昂贵的订阅工具。
• 隐私敏感企业：确保代码不上传至第三方服务器，保护商业机密。
• 多技术栈团队：提供统一入口管理多种模型资源。
• 国内开发者网络环境友好，支持智谱、MiniMax 等国产模型，无需特殊网络配置。

四、费用说明

• 工具本身完全开源免费：无订阅费用，永久免费使用。
• 模型费用免费模型：Zen 平台提供 Big Pickle、Grok Code Fast 1、MiniMax M2.1、GLM-4.7、GPT 5 Nano 等，满足基础开发需求。
• 付费模型（按量计费）：
• GLM-4.6V：输入 $0.60/百万 token，输出 $2.20/百万 token。
• Claude Sonnet 4.5：输入 $3.00/百万 token，输出 $15.00/百万 token。
• 自有账号绑定：绑定现有 Copilot、ChatGPT Plus 或 Claude Pro 账号后，按原订阅方案生效。

五、使用指南

• 安装方式（三选一）curl（推荐，适用于 macOS/Linux）

1. bash

curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://opencode.ai/install | bash

• npm（跨平台，需 Node.js 环境）

1. bash

npm install -g opencode-ai
npm install -g opencode-ai

• Homebrew（适用于 macOS/Linux）

1. bash

brew install anomalyco/tap/opencode
brew install anomalyco/tap/opencode

• 注：Windows 用户建议直接使用 WSL 或前往官网下载桌面版 .exe。

1. 配置模型进入终端，输入 /connect 命令。
2. 选择服务提供商（如 openai、anthropic、zhipu）。
3. 粘贴 API Key 或直接登录账号。
4. 输入 /models 查看当前可用模型列表。
5. 基础操作流程进入项目根目录：cd /path/to/your/project
6. 启动 OpenCode：opencode
7. 首次初始化：输入 /init
8. 输入需求（例如：“用 Python 写快速排序并加测试”）
9. 按 Tab 键切换 Plan 或 Build 模式。

• 常用命令/share：生成链接分享会话。
• /sessions：查看历史会话记录。
• /undo：撤销代码修改。

六、避坑指南

• 版本选择新手请勿直接安装终端版，建议先从桌面版或 VS Code 插件入手，熟悉后再过渡到 CLI 版本。
• 运行路径命令必须在项目根目录运行。若不在根目录，LSP 加载将失败，导致代码补全和跳转功能失效（项目需包含 .git、package.json 等关键文件）。
• 安全操作修改代码前先用 Plan 模式确认方案，再切 Build 模式。
• 涉及重要文件时请先手动备份，并善用 /undo 功能。
• 模型选择免费模型（Zen 系列）稳定性一般，适合学习与小项目；复杂任务建议使用付费模型或自有账号绑定。
• 插件安全谨慎使用第三方插件（如 oh-my-opencode），其可能违反模型厂商协议，存在导致账号封禁的风险。
• 配置生效范围配置文件（opencode.json）仅当前目录生效，不向上递归。如需统一配置，请使用软链接管理。
• 模型 ID 格式模型 ID 格式必须严格为 提供商/模型名（例如 openai/gpt-4o），否则将报 ProviderModelNotFoundError 错误。