OpenCode - Open-Source AI Coding Agent

OpenCode 不仅仅是另一个 AI 编码助手。它是一个本地优先的自主编码代理，旨在充当真正的结对程序员。与简单的自动完成工具不同，OpenCode 理解你的整个代码库，规划复杂的重构，并执行终端命令——所有这些都在你的机器上安全进行。

在这份终极指南中，我们将涵盖从零开始掌握 OpenCode 最先进功能所需的一切。

1. 安装：通往自主编码的大门

入门设计得非常顺畅。OpenCode 在你的终端中原生运行，这意味着它可以在你工作的任何地方运行——无论是 VS Code、JetBrains 还是独立的 Shell。

快速安装 (Mac, Linux, Windows WSL)

最快的安装方式是通过我们的官方脚本：

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

替代方案：npm 包

如果你更喜欢通过 Node.js 管理工具，你可以全局安装 OpenCode：

npm install -g opencode-ai

安装完成后，只需输入 opencode 即可验证安装并启动 UI。

2. 模型与提供商：无限选择 (BYOK)

OpenCode 的核心理念之一是模型中立。我们不会把你锁定在单一的“黑盒”模型中。相反，我们允许你自带密钥 (BYOK) 或连接到你现有的 AI 订阅。

认证

要连接你首选的模型提供商，请运行：

opencode auth login

这个交互式命令将引导你登录：

Anthropic (Claude 4.5 Sonnet, Opus)
OpenAI (GPT-5, o1-preview)
Google (Gemini 3 Pro, 1.5 Pro)
Models.dev (访问 75+ 开源及托管模型)

管理模型

你可以根据任务随时切换模型。对于简单的修复使用更快的模型，对于架构规划使用推理能力更强的模型。

# 列出所有可用模型
opencode models

# 添加新提供商后刷新模型列表
opencode models --refresh

使用 Ollama 进行本地部署

为了获得极致的隐私和离线能力，OpenCode 通过 Ollama 支持本地模型。将 OpenCode 指向你的本地实例，即可在没有任何数据离开网络的情况下进行编码——非常适合企业环境或处理敏感知识产权。

3. 核心工作流：交互式 vs. 一次性

OpenCode 适应你的工作方式。

交互式会话

使用 OpenCode 最强大的方式是交互式会话。在你的项目根目录下运行 opencode 进入持久的聊天环境。

上下文感知：代理读取你的文件结构和 LSP 信号。
多轮对话：你可以完善计划，要求更正并进行迭代。
工具使用：代理可以自主读取文件、编辑代码和运行测试。

一次性命令

对于不需要完整对话的快速任务，使用 opencode run。这非常适合“即发即忘”的指令。

# 总结代码库并建议改进
opencode run "Analyze this codebase and propose a refactoring plan for performance"

# 快速修复
opencode run "Fix the type error in src/utils/helper.ts"

4. 代理与权限：安全第一

让 AI 访问你的终端和文件系统需要信任。OpenCode 通过强大的权限系统和专门的代理解决了这个问题。

细粒度权限

你完全控制代理可以做什么。全局或按会话设置权限：

允许 (Allow)：代理自动执行命令和编辑文件。
询问 (Ask)：代理必须为每个操作请求你的批准（敏感操作的默认设置）。
拒绝 (Deny)：严禁代理执行该操作。

专用代理：规划 vs. 构建

为了最大限度地降低风险，我们建议采用分离的工作流程：

规划代理 (Plan Agent)：使用“规划者”模型分析代码并起草策略。将此代理保持在只读或询问模式。
构建代理 (Build Agent)：计划获得批准后，切换到具有允许权限的“构建者”代理以快速执行更改。

5. 高级功能：多会话与共享

现实世界的工程不是线性的。OpenCode 支持高级工作流程以满足你的多任务需求。

并行会话

不要让长时间运行的重构阻塞你的快速错误修复。OpenCode 允许你运行多个并行会话。

会话 A：“重构身份验证中间件。”
会话 B：“修复主页上的 CSS z-index 错误。”

这些会话独立运行，确保上下文不会在任务之间混淆。

可共享链接

需要向队友展示 AI 做了什么？使用 /share 生成你会话的严谨、只读日志。

协作：发送链接给 PR 审查者，这样他们就可以看到做出更改的原因。
文档：将成功的会话保存为未来任务的“食谱”。
隐私控制：共享默认关闭。你明确控制发布的内容。

结论

OpenCode 是为那些想要 AI 的力量而不牺牲控制权或隐私的开发人员构建的。通过掌握这些工作流程——选择正确的模型，利用细粒度权限，并使用并行会话——你可以将 OpenCode 从一个简单的助手转变为一个不知疲倦的自主合作伙伴。

掌握 OpenCode：本地优先 AI 编程终极指南