请启用 Javascript 以查看内容

OpenCode 入门教程：终端 AI 编程助手完整指南

 ·   ·  ☕ 6 分钟  ·  ✍ Wenlong · 👀... 阅读

作者：SRE运维博客
博客地址：https://www.cnsre.cn/
文章地址：https://www.cnsre.cn/posts/260122210234/
相关话题：https://www.cnsre.cn/tags/opencode/
版权声明: 如需转载，请联系作者授权

在 AI 辅助编程工具快速发展的今天，OpenCode 作为一款开源的终端 AI 编程助手，凭借其多提供商支持、本地模型能力、完全开源等特性，在 GitHub 上已获得 50,000+ stars，月活用户超过 650,000。

与闭源的 Claude Code 相比，OpenCode 提供了更灵活的配置选项：支持 Anthropic Claude、OpenAI GPT、Google Gemini、Ollama 本地模型等 75+ LLM 提供商，让你可以自由选择或同时使用多个模型，而不会被锁定在单一生态系统中。

本文将从零开始，详细介绍 OpenCode 的安装、配置和使用，帮助你快速上手这款强大的终端 AI 编程助手。

为什么选择 OpenCode？

在深入安装之前，先了解一下 OpenCode 的核心优势：

  • 完全开源：代码完全透明，可审计、可修改、可贡献
  • 多提供商支持：75+ LLM 提供商，包括 Anthropic、OpenAI、Google、Ollama 等
  • 终端原生：直接在终端中工作，无需浏览器或 IDE 插件
  • Agent 模式：让 AI 自主处理复杂任务，包括文件编辑和命令执行
  • 插件生态：丰富的插件和技能系统，可扩展功能
  • MCP 支持：Model Context Protocol 兼容，可与更多工具集成

安装 OpenCode

OpenCode 提供了多种安装方式，你可以根据自己的系统和偏好选择最适合的方法。

方法一：Shell 脚本安装（推荐）

这是最快速的安装方式，使用官方提供的安装脚本：

1

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

来源: OpenCode GitHub README | Context7 官方文档

说明：

  • 需要网络连接和 curl 工具
  • 脚本会自动下载并安装最新版本的 OpenCode
  • 支持自定义安装路径：
1
2
3
4
5

# 自定义安装路径到 /usr/local/bin
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# 自定义安装路径到 $HOME/.local/bin
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

方法二：NPM 全局安装

如果你已经安装了 Node.js 和 npm，可以使用 NPM 安装：

1

npm install -g opencode-ai

来源: OpenCode 安装文档

方法三：Docker 运行

如果你使用 Docker，可以直接运行官方镜像：

1

docker run -it --rm ghcr.io/anomalyco/opencode

来源: Installation and Setup

验证安装

安装完成后，运行以下命令验证安装：

1

opencode --version

预期输出会显示 OpenCode 的版本号。

配置 OpenCode

OpenCode 的配置文件位于 ~/.config/opencode/opencode.jsonc（或 opencode.json）。配置文件支持 JSONC 格式（带注释的 JSON）。

配置文件结构

配置文件的基本结构如下：

// 文件路径: ~/.config/opencode/opencode.jsonc
// 来源: OpenCode 官方配置文档
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["{file:./custom-instructions.md}"],
  "provider": {
    // Provider 配置
  }
}

配置 LLM 提供商

OpenCode 支持多种 LLM 提供商，下面是几种常见提供商的配置示例。

配置 OpenAI

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

来源: OpenCode Config 文档

说明：

  • {file:~/.secrets/openai-key} 表示从文件中读取 API Key
  • 先创建 ~/.secrets/ 目录，然后创建 openai-key 文件，填入你的 API Key
1
2

mkdir -p ~/.secrets
echo "sk-your-openai-api-key" > ~/.secrets/openai-key

配置 Anthropic Claude

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{file:~/.secrets/anthropic-key}"
      }
    }
  }
}

配置 Ollama 本地模型

使用 Ollama 运行本地模型，完全私有且免费：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b (local)"
        }
      }
    }
  }
}

来源: LM Studio Provider 配置

前提条件：

  • 已安装 Ollama：curl -fsSL https://ollama.ai/install.sh | sh
  • 已拉取模型：ollama pull deepseek-r1:1.5b
  • Ollama 服务运行在 http://localhost:11434

Ollama 配置示例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "baseURL": "http://localhost:11434",
      "models": {
        "deepseek-r1:1.5b": {
          "name": "DeepSeek R1 1.5B"
        },
        "llama3.2": {
          "name": "Llama 3.2"
        }
      }
    }
  }
}

来源: Ollama Provider 配置

验证配置

配置完成后，可以通过以下命令验证：

1
2

# 查看已配置的提供商
opencode auth list

来源: OpenCode Providers 文档

快速开始

启动 OpenCode

进入你的项目目录，启动 OpenCode：

1
2

cd /path/to/your/project
opencode

初始化项目

首次使用时，运行 /init 命令来初始化项目：

1

> /init

来源: OpenCode 初始化文档

说明：

  • /init 命令会分析你的项目结构
  • 创建 AGENTS.md 文件，包含项目特定的 AI 配置
  • AGENTS.md 应该提交到 Git 仓库

基本使用示例

示例 1：创建文件

1

opencode "Create a file named hello.txt and write 'OpenCode was here' into it"

来源: OpenCode Installation Guide

示例 2：代码分析

1

> Analyze the current project structure and identify potential issues

示例 3：重构代码

1

> Refactor the login component for better error handling

高级功能

Agent 模式

OpenCode 支持多种 Agent 模式，每种模式针对不同的任务类型：

{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "build": {},
    "plan": {},
    "my-custom-mode": {}
  }
}

来源: OpenCode Mode 配置

模式说明：

  • build: 构建相关任务
  • plan: 规划和分析任务
  • my-custom-mode: 自定义模式

技能和插件

OpenCode 支持自定义技能（Skills）和插件（Plugins）系统，扩展其功能。

技能目录结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

my-skill/
├── SKILL.md          # Required: 技能元数据和指令
├── references/        # Optional: 文档和指南
│   ├── guide.md
│   └── examples.md
├── assets/           # Optional: 二进制文件和模板
│   ├── template.html
│   └── logo.png
└── scripts/          # Optional: 可执行脚本
    ├── setup.sh
    └── generate.py

来源: OpenCode Skills Plugin

MCP 服务器配置

OpenCode 支持 Model Context Protocol (MCP)，可以集成更多工具和服务：

{
  "$schema": "https://opencode.ai/config.json",
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": [
        "npm-global-exec@latest",
        "@cloudbase/cloudbase-mcp@latest"
      ],
      "env": {
        "INTEGRATION_IDE": "OpenCode"
      }
    }
  }
}

来源: CloudBase MCP 配置

常见使用场景

场景 1：调试代码

1

> My React app isn't rendering the user list component. Help me debug this.

OpenCode 会：

  1. 分析项目结构
  2. 识别组件文件中的潜在问题
  3. 建议运行诊断命令
  4. 提供修复建议

来源: OpenCode NaviGator AI 文档

场景 2：代码重构

1

> Extract validation logic from the login form to a custom hook

场景 3：生成测试

1

> Write unit tests for the AuthService class using Jest

场景 4：文档生成

1

> Generate API documentation for the REST endpoints in this project

性能优化

减少上下文窗口

对于大型项目，可以通过以下方式优化性能：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

来源: OpenCode Agent Skills 文档

使用本地模型

对于敏感项目或离线环境，配置 Ollama 本地模型可以：

  • 保护代码隐私
  • 减少网络延迟
  • 避免使用云服务的费用

故障排查

问题 1：API Key 未找到

错误信息：

Error: API key not found

解决方案：

  1. 确认 ~/.secrets/ 目录存在
  2. 确认 API Key 文件名称正确（如 openai-key、anthropic-key）
  3. 确认文件内容有效（不包含多余空格或换行）

问题 2：Ollama 连接失败

错误信息：

Error: Failed to connect to Ollama server

解决方案：

  1. 确认 Ollama 服务已启动：ollama serve
  2. 确认端口号正确（默认 11434）
  3. 测试连接：curl http://localhost:11434/api/tags

问题 3：权限错误

错误信息：

Error: Permission denied

解决方案：

  1. 确认配置文件权限正确：chmod 600 ~/.config/opencode/opencode.jsonc
  2. 确认 API Key 文件权限正确：chmod 600 ~/.secrets/*

最佳实践

1. 项目级配置

为每个项目创建项目级配置，而不是使用全局配置：

1
2
3

cd /path/to/project
mkdir -p .opencode
# 创建项目级 opencode.jsonc

2. 使用 Git 忽略敏感文件

在 .gitignore 中添加：

.secrets/
.opencode/

3. 版本控制配置

将 opencode.jsonc 添加到版本控制，但排除包含 API Key 的配置部分。

4. 定期更新

定期更新 OpenCode 以获取最新功能和修复：

1

opencode upgrade

来源: OpenCode CLI 文档

总结

OpenCode 作为一款开源的终端 AI 编程助手，为开发者提供了：

  • 灵活性：75+ LLM 提供商支持，无厂商锁定
  • 隐私性：支持本地模型，代码完全私有
  • 可扩展性：插件和技能系统，功能无限扩展
  • 透明性：完全开源，代码可审计

无论是个人开发者还是团队，OpenCode 都能显著提升开发效率。从快速原型开发到复杂的代码重构，从调试问题到编写测试，OpenCode 都能成为你值得信赖的 AI 编程伙伴。

参考资料

本文验证的信息来源：

  1. 官方文档

  2. GitHub 源码

  3. 社区资源

  4. 集成文档

  5. 本文测试环境

    • 系统: macOS Sonoma 14.0
    • OpenCode 版本: v1.0.190+
    • 测试日期: 2026-01-22
    • 验证的 LLM 提供商: OpenAI, Anthropic, Ollama

作者：SRE运维博客
博客地址：https://www.cnsre.cn/
文章地址：https://www.cnsre.cn/posts/260122210234/
相关话题：https://www.cnsre.cn/tags/opencode/
版权声明: 如需转载，请联系作者授权

您的鼓励是我最大的动力
alipay QR Code
wechat QR Code
Avatar
作者
Wenlong
一位只会重启的运维

相关内容

+友情链接 Alliot’s blog 运维小弟 小z博客 小柒博客 九思学舍 无缺博客 运维开发故事 云原生运维圈 UNIXSRE 任我乐 JaromeJiang 凡梦星尘空间站 Jaxx.Wang Jackie's Blog
总访客 ...
总浏览 ...

本站截止 共发表 111 篇文章.

©2021, 保留所有权利. 除非另有声明. 本网站 内容采用 CC-BY-NC-SA 4.0 授权.

SRE运维博客 SRE运维博客 SRE运维博客

本站由 kubernetes 强力驱动.

目录