Coding Tree

外观

新手何如上手opencode ​

OpenCode 是一个运行在终端里的 AI 编程代理（Agent），它不止是聊天或补全代码，而是能理解整个项目、规划任务、直接修改文件并执行命令。目前已收获超 17 万 GitHub Stars，月活达 750 万。

下面是一份针对新手的完整上手指南。

1. 核心概念：它和 ChatGPT 有什么不同？ ​

对比维度ChatGPT / 传统AI聊天OpenCode (AI Agent)
工作方式你提问，它回答，你来复制粘贴你说目标，它自动规划并执行，直接修改代码
项目理解只能理解你粘贴的片段自动扫描整个项目，理解代码结构和上下文
核心价值信息查询、代码片段生成自动化完成任务，从写代码到修Bug、重构

简单说，OpenCode 更像一个能直接在你项目里“干活”的实习生，而不是一个只会出主意的顾问。

2. 准备工作：安装 Node.js ​

OpenCode 依赖 Node.js 环境，版本需要 18 或以上。

  • 检查版本：在终端（Terminal）中运行：
bash
node -v
  • 安装/升级：如果版本过低或没有安装，请前往 Node.js 官网 下载最新的 LTS（长期支持）版本。

3. 三步安装 OpenCode ​

对于新手，推荐使用一键安装脚本或 npm 方式：

  • 方式一：一键安装脚本（最推荐新手）
    bash
    curl -fsSL https://opencode.ai/install | bash
  • 方式二：npm 全局安装（通用）
    bash
    npm install -g opencode-ai
  • 方式三：包管理器（macOS/Linux）
    bash
    brew install sst/tap/opencode

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

bash
opencode --version

如果能看到版本号，就说明安装成功了。

4. 配置 AI 模型（最关键的一步） ​

OpenCode 本身完全免费开源，但它需要调用 AI 模型的 API 来工作。你需要选择一个模型提供商并获取 API Key。

4.1 如何选择模型？ ​

  • 海外用户 / 有稳定网络：可以选择 Claude（代码能力强，推荐 Claude 3.5 Sonnet）、GPT 或 Gemini。
  • 国内用户 / 无特殊网络：推荐使用国产模型，如 DeepSeek 或 阿里通义千问，它们在国内可直接访问。或者使用 Ollama 运行本地模型，完全离线，保护隐私。

4.2 如何配置 API Key？ ​

方法一：使用环境变量（最快上手）

在终端中执行以下命令（替换 your-key-here 为你的真实密钥）：

  • macOS / Linux:
    bash
    export ANTHROPIC_API_KEY="your-key-here"  # 如果使用 Claude
# 或
export OPENAI_API_KEY="your-key-here"     # 如果使用 OpenAI
  • Windows (PowerShell):
    powershell
    $env:ANTHROPIC_API_KEY = "your-key-here"

方法二：通过登录命令（更简单）

直接在终端运行，根据提示选择提供商并粘贴 API Key：

bash
opencode auth login

5. 第一次启动与初始化 ​

  1. 进入你的项目目录：
    bash
    cd your-project
  2. 启动 OpenCode：
    bash
    opencode
    首次启动可能会引导你完成一些初始设置。
  3. 初始化项目（重要！）： 在 OpenCode 的界面中输入以下命令，让它扫描并理解你的项目：
    /init
    这会生成一个 AGENTS.md 文件，记录项目信息，作为后续所有对话的上下文基础。

6. 两种核心工作模式 ​

OpenCode 提供两种模式，用 Tab 键可以切换：

模式作用适用场景
Plan (规划)只分析，不修改代码代码审查、分析项目性能瓶颈、理解陌生仓库的结构
Build (构建)实际修改代码和文件添加新功能、修复Bug、进行代码重构

新手建议：在让 AI 动手改代码前，先用 /plan 模式让它给出方案，确认无误后，再切换到 /build 模式执行。

7. 常用命令速查 ​

在 OpenCode 的 TUI（终端用户界面）中，你可以使用以下斜杠命令（Slash Commands）：

命令功能
/models列出并切换不同的 AI 模型
/undo撤销上一次 AI 的修改，改错了可以一键回滚
/new开启一个新的会话
/sessions查看和管理所有历史会话
/share生成一个公开链接，分享当前的对话记录
/export将对话导出为文件

8. 新手最佳实践与注意事项 ​

  1. 先跑通核心流程：第一个星期，建议只使用 OpenCode 本体，专注于跑通 plan / build 流程，建立 AGENTS.md，理解权限和自定义命令的配置。
  2. 从具体任务开始：不要给 AI 太模糊的指令。尝试这样提问：
    • “给 Express 项目加用户注册接口，需要邮箱验证和密码加密”
    • “修复 api/users.ts 的类型错误”
  3. 网络问题：国内用户在安装和调用海外模型 API 时可能遇到困难。解决方案是优先选择 DeepSeek 等国产模型，或使用 Ollama 本地部署。
  4. 注意安全：AI 自动修改代码时，请确保你的项目已提交到 Git，以便随时回滚。在让 AI 执行可能有风险的操作前，先在 plan 模式下审查其计划。

9. 总结：快速启动 checklist ​

  1. [ ] 安装 Node.js (v18+)
  2. [ ] 终端运行 npm install -g opencode-ai
  3. [ ] 注册并获取 AI 模型 (如 DeepSeek) 的 API Key
  4. [ ] 终端运行 export YOUR_MODEL_API_KEY="your-key"
  5. [ ] 进入项目目录 cd your-project
  6. [ ] 终端运行 opencode
  7. [ ] 在 OpenCode 中运行 /init
  8. [ ] 开始使用 /plan 和 /build 模式工作！

如果过程中遇到问题，可以查阅官方文档 https://opencode.ai/docs或在 GitHub 上提交 Issue。