AliveRiver

外观

OpenCode 新手上手教程：CLI 与 Desktop

约 5422 字大约 18 分钟

OpenCodeCLIDesktopAI Coding

2026-10-18

适用版本：OpenCode 2.0.32
核对日期：2026-10-18
适用平台：Windows 为主，同时标注 macOS / Linux 差异 前排提醒，本文由AI生成，请酌情观看

第一次接触 OpenCode 时，最容易混淆的不是怎么提问，而是要先选 Desktop 还是 CLI、免费模型能不能用、终端权限该不该给。本文按照实际使用顺序，整理从安装、选择模型到发起任务、审查改动和排查问题的完整流程。

先看结论

使用场景建议入口
第一次使用，想先熟悉界面和操作流程OpenCode Desktop
想快速查看项目结构、文件差异和终端输出OpenCode Desktop
想接入脚本、自动化或 CIOpenCode CLI
想在同一台机器上兼顾交互操作和命令行任务Desktop 与 CLI 配合使用

Desktop 和 CLI 通常连接同一个本地 OpenCode 后台服务，因此可以共享项目、会话、配置和登录状态。实际表现取决于 Desktop 当前连接的服务地址。

还需要明确一点：OpenCode 本身不是模型。它更像一个编码智能体客户端，负责读取项目文件、组织上下文、调用模型、申请工具权限，并执行文件修改和命令运行。模型可以来自 OpenCode 自带的免费模型目录，也可以接入 Anthropic、OpenAI、Google、OpenRouter、Ollama 等服务。

一、安装与版本确认

1. 安装 Desktop

Windows 用户先打开官方下载页：

https://opencode.ai/download

选择 OpenCode Desktop → Windows (x64)，下载并完成安装。启动后，第一次通常会进入引导页，随后进入主界面。

本文核对时的 Desktop 版本为：

OpenCode 2.0.32

2. 安装 CLI

如果电脑已经安装 Node.js 和 npm，Windows、macOS、Linux 都可以直接安装：

npm install -g @opencode/cli

安装完成后验证版本：

opencode --version

macOS 和 Linux 也可以使用官方安装脚本：

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

macOS 用户还可以通过 Homebrew 安装：

brew install anomalyco/tap/opencode-v2

如果系统中还没有 npm，先安装 Node.js LTS，再重新打开终端。安装 Node.js 后，原有终端不一定能立即读取新的环境变量。

3. npm 安装成功，终端却找不到 opencode

这种情况通常不是安装失败，而是 npm 的全局可执行文件目录没有出现在当前终端继承的 PATH 中。

npm install -g 会把程序安装到全局目录。Windows 上常见的位置是：

C:\Users\<用户名>\AppData\Roaming\npm
opencode.cmd
opencode.ps1

即使这个目录已经写入用户 PATH，仍然可能出现找不到命令的情况：

  1. 当前终端或 Codex 进程在 PATH 更新之前启动，没有继承新的环境变量；
  2. 当前终端没有加载 npm 所在的 Node.js 目录，导致 npm 本身也不可用。

按顺序检查：

where.exe opencode
where.exe npm
npm prefix -g

如果 npm prefix -g 返回了类似下面的路径，但 where.exe opencode 找不到命令，就把这个目录加入用户 PATH：

C:\Users\<用户名>\AppData\Roaming\npm

修改完成后，关闭并重新打开终端或 Desktop 应用。

已经打开的 PowerShell 也可以临时刷新路径：

$env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [Environment]::GetEnvironmentVariable('Path','User')
opencode --version

这种修改只对当前 PowerShell 会话生效。要长期生效，仍需修改“用户环境变量 → Path”，然后重新启动终端。

不要在系统中同时保留多个来源的旧版本，例如 npm 安装版、旧版 winget CLI 和安装脚本版。可以先用 PowerShell 的 Get-Command opencode -All 查看实际匹配到的命令。

opencode 和 opencode2 可能是同一个 npm 包提供的两个命令别名，并不代表安装了两套 CLI。Desktop 安装目录中的 opencode-cli.exe 则是 Desktop 自带的运行时。判断是否重复安装时，应检查 npm list -g、winget list 和 Get-Command opencode -All，不要直接删除 Desktop 的内置文件。

二、模型选择与账号连接

1. 查看当前可用模型

先运行：

opencode models

OpenCode 会列出当前服务、当前项目可用的模型。模型名通常采用“提供商/模型名”的格式。

本文核对时，可以看到以下带有 free 标记的模型：

opencode/beam-free
opencode/big-pickle
opencode/deepseek-v4.1-flash-free
opencode/glm-5.3-flash-free
opencode/longcat-2.5-preview-free
opencode/mimo-v2.6-flash-free
opencode/nemotron-3-ultra-free
opencode/nemotron-3.5-lightning-free
opencode/nemotron-3.5-super-vl-free
opencode/space-bunny-free

免费模型的名称、可用性和额度会随服务调整。实际使用时，以 opencode models 的当前输出为准。

2. 新手怎么选

可以先从以下模型开始尝试：

  • opencode/deepseek-v4.1-flash-free：适合普通代码问答、修改和运行测试；
  • opencode/glm-5.3-flash-free：适合中文项目说明和常规编码任务；
  • opencode/nemotron-3.5-lightning-free：适合希望获得更快响应的轻量任务；
  • opencode/nemotron-3.5-super-vl-free：名称中的 VL 通常表示视觉语言能力，适合包含图片的任务。

免费模型适合入门和轻量任务，但可能存在速率限制、排队、上下文长度限制、模型上下线，以及复杂任务上的稳定性差异。

重要项目不应默认认为“免费模型一定适合生产代码”。更稳妥的做法是先让它完成小范围修改，再检查 diff 和测试结果。

3. 在 CLI 中指定模型

单次运行可以直接通过参数指定：

opencode run --model opencode/deepseek-v4.1-flash-free "解释这个项目的目录结构"

在 TUI 中也可以使用斜杠命令：

/models

或者按 Ctrl+X，再按 M。

4. 在 Desktop 中指定模型

新建会话后，在输入框附近的模型选择器中选择带“免费”标记的 OpenCode 模型。

如果没有看到模型，可以按以下顺序检查：

  1. 确认当前项目已经打开；
  2. 打开“设置 → 提供商”，检查提供商状态；
  3. 回到模型选择器刷新；
  4. 必要时运行 opencode service restart。

5. 连接其他提供商

CLI 使用交互式登录：

opencode auth login

查看已经连接的账号：

opencode auth list

Desktop 中打开：

设置 → 提供商 → 连接提供商

根据提示选择 API Key、浏览器 OAuth 或无头模式。

不要把 API Key 直接提交到项目中的 opencode.json。优先使用 Desktop 的提供商登录界面、opencode auth login、环境变量，或本地未提交的密钥文件。

三、OpenCode CLI 入门

1. 进入项目并启动 TUI

先进入项目目录：

cd C:\path\to\your-project
opencode

也可以直接指定项目目录：

opencode C:\path\to\your-project

启动后会进入全屏终端界面。最常用的流程是：输入任务、选择模型和智能体、提交任务、查看工具调用、处理权限请求，最后检查修改和测试结果。

2. 第一个任务：先只读分析

第一次使用时，建议先让 OpenCode 阅读项目，不要立即修改文件：

请先阅读这个项目，不要修改任何文件。
告诉我：
1. 项目使用什么技术栈；
2. 入口文件在哪里；
3. 如何安装依赖、运行和测试；
4. 你建议我接下来修改哪个文件。

确认它理解了项目结构后，再提出修改要求：

请实现 XXX 功能。
要求：
- 先阅读相关代码再修改；
- 保持现有风格；
- 不要修改无关文件；
- 完成后运行测试并报告结果。

3. TUI 中的输入技巧

在终端界面中，可以直接使用以下输入方式：

  • @：搜索并附加文件，例如 @src/auth.ts；
  • @src/auth.ts#20-45：附加指定行范围；
  • !：进入 shell 模式，例如 !git status；
  • /：打开斜杠命令列表；
  • Ctrl+P：打开命令面板；
  • Shift+Enter、Ctrl+Enter、Alt+Enter 或 Ctrl+J：输入换行。

常用斜杠命令：

/new          新会话
/sessions     会话列表
/models       模型列表
/agents       智能体列表
/undo         撤销上一轮
/redo         重做
/diff         查看差异
/editor       使用外部编辑器编辑当前提示词
/btw          围绕当前会话提问，但不影响后续上下文

4. 选择智能体：Plan 和 Build

OpenCode 内置了不同智能体。新手最需要理解的是以下两个：

  • Plan：偏向分析与计划，默认不直接修改代码；
  • Build：可以读取、编辑和运行命令，适合实际实现。

在 TUI 中，可以按 Ctrl+X 再按 A 选择智能体，或者运行 /agents。按 Shift+Tab 可以在智能体之间切换。

第一次面对陌生项目时，先用 Plan：

使用 Plan 模式分析这个仓库，找出登录失败的可能原因。
暂时不要修改文件，给出定位过程和验证计划。

确定方案后，再切换到 Build：

按刚才的计划实现修复。只修改与登录失败相关的文件。
完成后运行相关测试，并总结改动。

5. 不进入 TUI 的一次性运行

opencode run 适合脚本、CI 和快速问答：

opencode run "解释这个仓库的构建流程"

指定免费模型：

opencode run --model opencode/deepseek-v4.1-flash-free `
  "列出项目里所有 TODO，但不要修改文件"

继续上一次会话：

opencode run --continue "继续处理刚才提到的测试失败"

附加文件：

opencode run --file src\server.ts --file src\client.ts `
  "审查这两个文件的错误处理"

输出 JSON，方便脚本继续处理：

opencode run --format json "列出当前项目的测试命令"

6. 常用 CLI 命令速查

opencode --version                 # 查看版本
opencode models                    # 查看可用模型
opencode                           # 启动全屏 TUI
opencode mini                      # 启动精简交互界面
opencode run "..."                 # 非交互运行
opencode auth list                 # 查看已连接账号
opencode auth login                # 登录提供商
opencode session list              # 查看会话
opencode stats                     # 查看使用统计
opencode service status            # 查看后台服务状态
opencode service restart           # 重启后台服务
opencode debug paths               # 查看配置、日志和数据库位置
opencode reload                    # 重新加载配置

查看某个子命令的完整帮助：

opencode run --help
opencode mini --help
opencode auth --help
opencode mcp --help

7. 权限与 --auto

当 OpenCode 需要执行命令、修改文件或访问外部目录时，通常会请求权限，并提供“允许一次”“始终允许”和“拒绝”等选项。

新手建议遵循以下原则：

  1. 先看清命令的具体内容；
  2. 不理解的命令不要直接选择“始终允许”；
  3. 不要在不受信任的仓库中随手使用 --auto；
  4. 重要项目先提交当前代码，保证可以对比和恢复。

--auto 会减少确认步骤，但并不等于安全模式：

opencode run --auto --model opencode/deepseek-v4.1-flash-free "..."

只有在确认项目内容可信、修改范围明确时再使用。

四、OpenCode Desktop 入门

1. 首次打开

Desktop 的主界面通常包含以下区域：

  • 左侧：服务器、项目、最近会话和设置；
  • 中间：当前会话；
  • 右侧：审查和文件；
  • 底部或侧边：终端。

如果界面不是中文，可以打开：

设置 → 通用 → 语言

然后选择中文。

2. 添加项目

点击主页的“添加项目”，或者使用菜单：

File → Open Project

选择本地代码目录。

如果项目是 Git 仓库，Desktop 还可能提供两种运行位置：

  • 本地仓库：直接在当前检出目录工作；
  • 新建工作区：创建隔离的 Git worktree，降低对当前工作区的干扰。

第一次可以先选择“本地仓库”。如果项目存在未提交改动，或者希望智能体在隔离环境中尝试修改，再选择“新建工作区”。

3. 连接模型提供商

打开：

设置 → 提供商

点击“连接提供商”，选择需要的服务：

  • API Key：粘贴提供商密钥；
  • 浏览器：打开 OAuth 登录；
  • 无头模式：适用于没有图形浏览器的环境。

连接后回到会话，在模型选择器中选择模型。

4. 新建会话

在主页或项目下点击“新建会话”。会话拥有独立的对话上下文，不会自动把所有历史记录混在一起。

新建会话后，依次完成以下操作：

  1. 选择智能体，例如 Plan 或 Build；
  2. 选择模型，例如免费模型；
  3. 在输入框描述任务；
  4. 按需附加文件；
  5. 发送任务。

5. 处理权限请求

Desktop 遇到需要执行的操作时会弹出权限请求。先确认以下内容：

  • 要执行什么命令；
  • 会修改哪些文件；
  • 是否访问项目外部目录。

确认无误后再选择允许。对于不确定的项目，不要开启“自动接受权限”。

6. 审查改动

任务完成后，点击“审查和文件”，重点检查：

  • 哪些文件被修改；
  • 删除或新增了什么；
  • 是否出现无关格式化；
  • 是否包含调试输出、密钥或临时文件；
  • 测试是否实际运行。

推荐的验证顺序：

查看 diff
→ 运行测试
→ 运行构建或 lint
→ 再决定是否提交

7. 使用终端和文件树

Desktop 内置文件树和终端，适合打开相关文件、查看测试输出、运行 git status 和 git diff，或者手动验证智能体修改后的结果。

也可以用菜单打开或关闭这些面板：

View → Toggle Sidebar
View → Toggle File Tree
View → Toggle Terminal

8. 在 Desktop 中安装 CLI

如果以 Desktop 作为主要入口，但同时也想在终端使用 OpenCode，可以从菜单中查找“Install CLI…”。不同平台的菜单名称可能略有差异，也可以直接使用前文的 npm 方式安装。

安装完成后，一定要重新打开终端，再运行：

opencode --version

五、CLI 与 Desktop 怎么选

需求CLIDesktop
快速打开项目cd 后运行 opencode添加项目或 Open Project
选择模型/models 或 --model模型选择器
选择智能体/agents输入框附近的智能体选择器
查看文件@文件文件树或直接打开文件
运行命令!命令内置终端
查看差异/diff审查和文件面板
新建会话/new新建会话
恢复历史/sessions最近会话或标签页
撤销和重做/undo、/redo菜单或命令面板
连接提供商opencode auth login设置 → 提供商
自动化opencode run不是主要用途

简单来说，Desktop 更适合观察和交互，CLI 更适合批处理和自动化。两者共享同一个本地服务时，可以先用 Desktop 理解项目，再用 CLI 重复或扩展任务。

六、第一次使用的安全流程

1. 准备一个干净的项目

最好新建一个测试项目，或者在已经提交过基线的 Git 仓库中练习：

git status
git add .
git commit -m "checkpoint before opencode"

2. 第一轮只读

使用 Plan 智能体：

不要修改文件。请阅读项目并回答：
- 项目入口在哪里？
- 如何安装依赖？
- 如何运行测试？
- 有哪些高风险文件不能随便改？

3. 第二轮从小改动开始

只修改一个文件，修复 XXX 问题。
不要重构无关代码。
完成后运行相关测试并展示 diff 摘要。

4. 第三轮再扩大范围

确认模型能够正确理解项目后，再让它跨多个文件重构、补充测试、更新文档，或者运行完整测试套件。

5. 添加 AGENTS.md

在项目根目录创建 AGENTS.md，可以让 OpenCode 每次自动读取项目规则。建议至少写清楚安装、测试和代码规范：

# 项目规则

## 安装

```powershell
npm install
```

## 测试

```powershell
npm test
```

## 代码规范

- 修改前先阅读相关模块。
- 不要修改自动生成文件。
- 不要提交密钥、日志和临时文件。
- 提交前运行测试和 lint。

实际使用时，请把命令替换成项目自己的命令。

七、常用配置

1. 项目级配置

在项目根目录创建 opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/deepseek-v4.1-flash-free"
}

也可以放在：

项目目录/.opencode/opencode.jsonc

2. 全局配置

Windows 常见路径：

C:\Users\<用户名>\.config\opencode\opencode.jsonc

macOS 和 Linux 常见路径：

~/.config/opencode/opencode.jsonc

3. 基础权限配置

下面的示例表示“默认询问、允许常规 Git 检查、禁止 push”：

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" }
  ]
}

权限规则按顺序匹配，后面更具体的规则会覆盖前面的规则。第一次使用时，不必照抄全部配置，只保留自己能够理解的规则即可。

4. CLI 专属设置

CLI 的外观、快捷键和会话展示等设置与项目配置分开。Windows 上的常见文件为：

C:\Users\<用户名>\.config\opencode\cli.json

可以在 TUI 中按 Ctrl+P，选择“打开设置”，也可以直接编辑该文件。常见配置包括：

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "theme": {
    "name": "tokyonight",
    "mode": "system"
  },
  "terminal": {
    "title": true
  }
}

八、常见问题排查

1. opencode 不是内部或外部命令

依次执行：

where.exe opencode
where.exe npm
npm prefix -g

确认 npm 全局目录已经加入 PATH，然后重新打开终端。必要时可以用完整路径测试：

& "$env:APPDATA\npm\opencode.cmd" --version

如果这样能够运行，说明安装本身没有问题，问题出在 PATH 或终端环境。

2. npm 也不是命令

这说明 Node.js 或 npm 没有加入 PATH，或者当前终端没有加载相关环境变量。

检查：

node --version
where.exe node
where.exe npm

重新安装 Node.js LTS，或者把 Node.js 安装目录加入 PATH，再重新打开终端。

3. 模型列表为空或没有免费模型

依次执行：

opencode models
opencode service status
opencode service restart

然后重新打开 TUI 或 Desktop。还要确认当前查看的是目标项目，而不是另一个服务或远端环境。

4. 免费模型限流或不可用

先切换到另一个带 free 的模型：

opencode run --model opencode/glm-5.3-flash-free "测试连接"

如果所有模型都失败，检查：

  • 网络是否可以访问 OpenCode 服务；
  • 是否需要更新版本；
  • opencode service status 是否正常；
  • 是否选到了需要登录的提供商。

5. Desktop 和 CLI 看到的模型不一样

先确认两者连接的是同一个服务器：

opencode service status

再在 Desktop 的服务器设置中检查当前服务器地址。不同服务器、不同项目和不同登录状态都会导致模型列表不同。

6. Desktop 卡住或无法连接

尝试重启后台服务：

opencode service restart

然后完全退出并重新启动 Desktop。

如果问题仍然存在，使用 Desktop 菜单中的“导出日志”，检查：

%APPDATA%\ai.opencode.desktop\logs

CLI 日志和数据库路径可以通过以下命令查看：

opencode debug paths
opencode debug paths log
opencode debug paths db

7. 权限请求太多

不要把“自动接受权限”当作默认选项。更安全的做法是：

  1. 允许常见的只读命令，例如 git status 和 git diff；
  2. 保留修改和删除操作前的询问；
  3. 明确拒绝 git push、删除目录、读取密钥文件等高风险操作。

九、快捷键速查

CLI TUI

操作快捷键
发送Enter
换行Shift+Enter / Ctrl+Enter / Alt+Enter / Ctrl+J
选择模型Ctrl+X，然后 M
选择智能体Ctrl+X，然后 A
新会话Ctrl+X，然后 N
会话列表Ctrl+X，然后 L
撤销Ctrl+X，然后 U
重做Ctrl+X，然后 R
外部编辑器Ctrl+X，然后 E
命令面板Ctrl+P
最近会话和项目Ctrl+O
切换最近模型F2
切换智能体Shift+Tab

Desktop

操作位置
打开设置设置菜单或 Ctrl+,
打开项目File → Open Project
新建会话File → New Session 或主页按钮
切换侧栏View → Toggle Sidebar
切换文件树View → Toggle File Tree
切换终端View → Toggle Terminal
查看改动“审查和文件”面板

不同版本可能会调整菜单位置。如果找不到对应选项，可以在命令面板中搜索操作名称。

十、推荐的第一次练习

可以按下面顺序完成一次完整练习：

  1. 新建一个测试目录；
  2. 创建一个简单脚本；
  3. 执行 git init 并提交基线；
  4. 用 Desktop 打开项目；
  5. 选择免费模型；
  6. 让 Plan 智能体解释项目；
  7. 切换到 Build，要求修改一个函数；
  8. 查看 diff；
  9. 运行测试；
  10. 用 CLI 执行同一任务并比较结果。

CLI 示例：

cd C:\path\to\test-project
opencode run --model opencode/deepseek-v4.1-flash-free `
  "阅读当前项目，先只说明如何运行；不要修改文件"

确认模型理解项目后，再执行：

opencode run --model opencode/deepseek-v4.1-flash-free `
  "创建一个简单的测试脚本，运行它，并报告结果。不要访问当前目录之外的文件"

工具可以加快操作，但不能替你保证结果正确。真正值得保留的习惯，仍然是先确认需求，再看清 diff，最后用测试验证。

官方资料

免费模型名称、可用性和额度会变化。使用前请以 opencode models 和当前服务显示为准。