LowHow 文档

中文

English

中文

English

深色模式

OpenCode CLI 实战教程：从零开始掌握命令行操作 ​

📚 分类: 开发工具 / AI 编程 ⏱️ 预计耗时: 12 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode CLI 工具 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode CLI 的 6 个核心入口命令及其适用场景
  • [ ] 独立完成从安装验证到执行第一个只读任务的完整流程
  • [ ] 安全地管理 AI 模型提供商凭据
  • [ ] 避免新手常见的操作陷阱，安全地使用 CLI

最终效果 ​

你将能够在终端中熟练地使用 opencode 命令启动交互式界面（TUI），并使用 opencode run 命令对你的项目进行只读分析，而无需担心误操作或安全问题。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求验证命令
OpenCode CLI已安装opencode --version
一个 Git 项目任意ls .git (在项目根目录执行)

1. 验证 OpenCode 已安装 ​

打开你的终端，执行以下命令：

bash
$ opencode --help    // 查看帮助信息，确认命令可用
$ opencode --version // 查看版本号

✅ 验证：如果看到 OpenCode 的版本号和帮助信息列表，说明安装成功。

💡 提示：如果提示 command not found，请先参考 OpenCode 官方安装文档 完成安装。

第 1 步：掌握 CLI 的 6 个核心入口 ​

🎯 目标：快速了解 OpenCode CLI 最常用的 6 个命令，知道它们各自在什么场景下使用。

📝 操作：

OpenCode CLI 功能强大，但作为新手，你不需要记住所有命令。先掌握下面这 6 个入口，就能覆盖 80% 的日常使用场景。

入口命令用途第一次建议
opencode启动交互式终端界面 (TUI)默认入口，用于日常编码对话
opencode run非交互式执行一次性任务先做只读解释，验证模型能力
opencode auth管理 AI 模型提供商 (如 OpenAI, Anthropic) 的凭据用 login / list 验证配置
opencode models查看可用的模型列表配置模型前先确认名称，避免写错
opencode serve / web启动后端服务或 Web UI只在理解认证机制后开放端口
opencode mcp管理 MCP (Model Context Protocol) 服务器先只接 1-3 个必要的工具

🤔 为什么要这样做？ CLI 命令不是越多越高阶。先掌握这 6 个核心入口，你就能完成“命令可用 -> 模型可用 -> 任务可控”的闭环，建立起使用信心，再逐步探索其他高级功能。

✅ 验证：现在你已经对 CLI 的主要功能有了一个清晰的蓝图。

第 2 步：执行最小验证流程 ​

🎯 目标：完成第一次“命令可用、模型可用、任务可控”的完整闭环，确保你的 OpenCode 环境是健康的。

📝 操作：

  1. 进入你的 Git 项目：

    bash
    $ cd /path/to/your/project   // 替换为你的项目路径

  2. 启动 TUI 界面：

    bash
    $ opencode

    你会看到 OpenCode 的终端交互界面（TUI）启动。这表明 CLI 可以正常加载你的项目上下文。

  3. 退出 TUI：按下 Ctrl + C 或输入 /exit 并回车，退出 TUI 回到终端。

  4. 执行一次只读任务：

    bash
    $ opencode run "Explain the structure of this repository. Do not edit files."

    这个命令会让 AI 分析你的项目目录结构，并给出解释。Do not edit files. 是一个安全提示，确保 AI 不会修改你的代码。

✅ 验证： 执行 opencode run 后，你应该看到 AI 开始思考，并在终端输出对你项目结构的文字描述。如果看到类似 Analyzing repository structure... 的输出，说明一切正常。

💡 提示：如果 opencode run 命令卡住或报错，很可能是模型提供商凭据未配置。请继续下一步。

第 3 步：配置并验证模型提供商 ​

🎯 目标：确保 OpenCode 能够连接到你的 AI 模型提供商（如 Anthropic, OpenAI），并成功获取模型列表。

📝 操作：

  1. 登录你的模型提供商：

    bash
    $ opencode auth login

    系统会引导你完成登录流程。你需要提前准备好你的 API Key。

  2. 查看已登录的提供商列表：

    bash
    $ opencode auth list

    这会列出所有已成功登录的提供商。

  3. 查看可用模型：

    bash
    $ opencode models

    这会列出所有可用的模型名称。

✅ 验证：

  • opencode auth list 应该显示你登录的提供商名称。
  • opencode models 应该显示一个模型列表，例如 anthropic/claude-3-opus-20240229。

⚠️ 常见错误：

  • Error: Authentication failed: 说明你的 API Key 无效或未正确配置。请检查 API Key 是否正确，并重新执行 opencode auth login。
  • No models found: 说明没有成功连接到模型提供商。请先确认 opencode auth list 中是否有提供商，然后尝试刷新模型列表：
    bash
    $ opencode models --refresh

🤔 为什么要这样做？opencode models 命令返回的模型名是配置 opencode.json 文件的依据。先用这个命令确认模型名称，可以避免在配置文件中写错而导致任务失败。

第 4 步：探索其他核心入口（概念性了解） ​

🎯 目标：了解 serve/web 和 mcp 命令的用途和风险，为后续进阶学习打下基础。

📝 操作：

1. 安全地启动服务 (serve / web) ​

  • opencode serve：启动一个无界面的 HTTP 服务。
  • opencode web：启动一个带 Web UI 的后端服务。
  • opencode attach：将你的终端 TUI 连接到已启动的后端服务。

⚠️ 安全红线：不要在未设置密码的情况下，将 serve 或 web 服务绑定到 0.0.0.0（即所有网络接口）。这会暴露你的项目上下文和工具能力。

正确做法：

bash
# 1. 设置密码
$ export OPENCODE_SERVER_PASSWORD="your-strong-password"

# 2. 启动服务（以 web 为例）
$ opencode web --port 4096 --hostname 0.0.0.0

2. 谨慎接入外部工具 (mcp) ​

  • opencode mcp add：添加一个 MCP 服务器。
  • opencode mcp list：查看已添加的 MCP 服务器。

新手原则：

  • 能不接就不接：优先使用 OpenCode 内置工具。
  • 先少后多：第一次只接 1-3 个最必要的 MCP 工具。
  • 先读后写：先验证查询类工具，再考虑使用有写入权限的工具。

✅ 验证：现在你知道了这些命令的存在和基本用途，以及它们的安全风险。

进阶技巧（可选） ​

  1. 继续上次的会话：

    bash
    $ opencode --continue   // 启动 TUI 并加载上一个会话
$ opencode run --continue "继续分析上一个问题" // 在非交互模式下继续会话

  2. 将会话输出为 JSON 格式：

    bash
    $ opencode run "List all functions in this file." --format json > output.json

    这对于将 AI 输出集成到脚本或 CI/CD 流程中非常有用。

常见问题 (FAQ) ​

Q1: 执行 opencode run 时，AI 真的修改了我的文件怎么办？A: 这是新手最常见的坑。解决方法：在执行任何可能修改文件的任务前，务必确认你的项目已经用 Git 管理。如果 AI 误修改，你可以用 git diff 查看变更，并用 git checkout . 撤销所有未提交的修改。预防措施：在 opencode run 命令后始终加上 Do not edit files. 或 Read-only analysis. 等安全提示。

Q2: 如何安全地升级 OpenCode？A: 使用 opencode upgrade 命令。但在升级前，建议先了解影响范围：

bash
$ opencode upgrade --dry-run   // 模拟升级，查看会做什么

Q3: 我一次性配置了太多 MCP 工具，导致模型表现变差怎么办？A: 用 opencode mcp list 查看所有已配置的 MCP，然后用 opencode mcp remove <name> 移除不必要的工具。保持工具集精简。

Q4: 如何导出我的会话记录？A: 使用 opencode export <sessionID> 命令。⚠️ 注意：导出前请检查会话中是否包含 API Key、密码或敏感代码片段。可以使用 --sanitize 参数进行脱敏处理：

bash
$ opencode export <sessionID> --sanitize

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 核心入口：掌握了 opencode, opencode run, opencode auth, opencode models, opencode serve/web, opencode mcp 这 6 个核心命令的用途。
  2. 最小验证流程：独立完成了“命令可用 -> 模型可用 -> 任务可控”的完整验证闭环。
  3. 安全意识：理解了 serve/web 需要密码认证，以及 opencode run 需要添加只读提示来防止误操作。
  4. 避免常见坑：了解了新手容易犯的错误，如过早研究所有命令、暴露服务、一次性配置过多 MCP 等。

© 2026 LowHow