AB
AB
AiBoss

すべてのカテゴリ

チュートリアル

OpenCode

チュートリアル

OpenCode 完全指南：架构、模式与上手实践

OpenCode 是一个开源的 AI 编程代理，它不绑定特定模型，而是让你自由选择后端模型，通过终端、桌面应用或 IDE 扩展与代码库交互。本文深入解析其客户端-服务器架构、权限模式、AGENTS.md 项目上下文机制，并给出安装、配置、运行的具体步骤与注意事项，帮助你判断它是否适合你的工作流。

OpenCode 是一个开源的 AI 编程代理，它连接你选择的模型与你的代码仓库、终端和工具。你可以让它修复 bug，它会定位文件、制定计划、编辑代码、运行测试，并根据测试结果做出反应。OpenCode 本身不是模型——模型负责理解你的提示并生成回复，而 OpenCode 提供文件工具、Shell 访问、会话历史、权限规则以及围绕这些的界面。这种分离意味着你可以随时更换模型，而不影响其他部分。无论你是想尝试不同的模型提供商，还是希望将 AI 代理集成到自动化脚本中，OpenCode 都提供了灵活的解决方案。你可以通过我们的 OpenCode 工具页面 了解更多信息。

准备工作

在开始使用 OpenCode 之前，你需要完成以下准备：

  • 安装 OpenCode：支持多种安装方式，选择适合你系统的一种即可。
  • 获取模型访问权限：OpenCode 软件本身免费，但模型调用通常需要付费。你需要准备 API 密钥（如 Anthropic、OpenAI）或使用 Copilot、ChatGPT 登录，或通过 OpenCode Zen / Go 服务，或本地运行 Ollama。
  • 准备一个项目目录：建议在一个已有的 Git 仓库中运行，以便使用 /undo 等基于 Git 快照的功能。

安装 OpenCode

在终端中执行以下命令之一（根据你的操作系统选择）：

# 官方安装脚本（适用于大多数 Unix 系系统）
curl -fsSL https://opencode.ai/install | bash

# 通过 npm 安装
npm i -g opencode-ai@latest

# 通过 Homebrew 安装（macOS）
brew install anomalyco/tap/opencode

# Windows 用户
scoop install opencode
choco install opencode

在 Windows 上，官方文档推荐使用 WSL（Windows Subsystem for Linux），因为某些文件系统和 Shell 行为在 WSL 中表现更好。此外，OpenCode 也提供 macOS、Windows 和 Linux 的桌面应用（目前处于测试阶段）。

配置模型提供商

安装完成后，首次运行需要连接一个模型提供商。在项目目录中启动 OpenCode：

cd your-project
opencode

进入交互式会话后，使用 /connect 命令添加提供商：你可以选择 API 密钥、Copilot、ChatGPT、Zen 或 Go。如果你打算使用本地模型，可以通过 Ollama 运行，但请注意本地模型的性能限制（见下文）。

操作步骤

以下是在 OpenCode 中完成一个典型任务的基本步骤：

  1. 启动会话：在项目目录中运行 opencode，进入终端界面。
  2. 连接模型：使用 /connect 添加你的模型提供商，并完成认证。
  3. 生成项目上下文：运行 /init，OpenCode 会分析你的项目结构并生成 AGENTS.md 文件，其中包含测试命令、文件夹约定、命名规则等。
  4. 选择模式：按 Tab 键在 Plan（计划）和 Build（构建）模式之间切换。Plan 模式只做计划不修改代码，Build 模式执行实际操作。
  5. 引用文件：在提示中使用 @ 符号将文件内容拉入对话，例如 @src/main.py 解释这个文件。
  6. 执行任务：用自然语言描述你的需求，OpenCode 会调用工具完成任务。
  7. 审查与回滚：如果结果不满意，使用 /undo 回滚到之前的 Git 快照。

使用命令行模式

如果你不想进入交互式界面，可以使用 opencode run 执行一次性任务：

opencode run "Summarise this repo and propose next steps"

配置权限规则

OpenCode 的权限系统允许你控制工具何时被允许调用。你可以在 opencode.json 中配置规则，例如允许测试命令，但其他 Shell 操作需要询问。权限规则可以按命令模式区分。注意：权限系统是工作流保障，不是安全沙箱，它用于防止代理做出意外操作，而不是抵御恶意攻击。

使用子代理与 MCP

OpenCode 内置了子代理，用于多步骤搜索、代码库扫描和外部文档查询。每个子代理在子会话中运行，不会占用主窗口。你可以为自定义代理指定不同的模型、提示和工具权限，例如将便宜的模型用于只读研究代理。MCP 服务器在 opencode.json 中定义，其添加的工具同样受权限规则约束。

一个完整示例

假设你有一个 Python 项目，你想让 OpenCode 修复一个测试失败的问题。以下是完整流程：

  1. 安装并启动：在项目目录运行 opencode。
  2. 连接模型：输入 /connect，选择你的提供商并输入 API 密钥。
  3. 初始化上下文：输入 /init，生成 AGENTS.md。
  4. 切换到 Build 模式：按 Tab 键，确保处于 Build 模式。
  5. 描述问题：输入类似“测试 test_login 失败了，请找出原因并修复”。
  6. 观察执行：OpenCode 会定位相关文件，修改代码，运行测试，并根据结果调整。
  7. 检查改动：如果改动不理想，输入 /undo 回滚。

例如，你的提示可以是：

@tests/test_login.py 这个测试失败了，请修复它。

OpenCode 会读取该文件，分析错误，并可能修改 src/auth.py，然后重新运行测试。

注意事项

  • 免费的含义：OpenCode 软件是 MIT 许可的免费软件，但模型使用通常需要付费。你通过提供商令牌、OpenCode Zen、OpenCode Go 或本地硬件（如 Ollama）支付费用。免费工具也可能产生月度账单。
  • 订阅不通用：Anthropic 在 2026 年 1 月阻止了第三方工具通过非官方渠道使用 Claude 消费者订阅。因此，你的 Claude Pro 或 Max 订阅不能在 OpenCode 中使用，但 Claude 模型仍可通过 API 密钥使用，按 API 费率计费。Copilot 和 ChatGPT 登录不受影响。
  • 本地模型的限制：通过 Ollama 等本地端点运行模型时，可能会遇到更多无效工具调用和跨文件推理较弱的问题。确保机器有足够的内存来同时容纳模型和发送的上下文。
  • 权限不是安全边界：权限系统只是防止代理做出意外操作，不能抵御恶意攻击。在服务器模式下，应设置 OPENCODE_SERVER_PASSWORD 并绑定到 localhost，避免未授权访问。
  • /share 命令的隐私风险：/share 会将会话上传到一个公共链接，并且该链接在你取消共享之前一直公开。不要在私有代码库上随意使用。
  • AGENTS.md 的维护：保持文件简洁，只包含必要信息。如果文件过长，真正的规则会被淹没。测试每一行：删除它是否会导致错误？如果不会，就删掉。
  • 价格与功能易变：OpenCode 的发布节奏很快，任何关于价格、功能、提供商列表的信息都可能过时。请以官网当前信息为准，不要依赖几个月前的文章。

总之，OpenCode 适合那些希望灵活选择模型、需要脚本化控制代理、或希望将代码保留在本地基础设施中的用户。如果你已经付费使用 Claude Code 并只想要单一模型的最佳结果，OpenCode 可能不是升级；但如果你需要跨提供商的可移植性或自动化能力，它提供了独特的价值。

戻る