OpenCode 操作指导书二安装与配置适用版本OpenCode v1.18.3本篇目标在 macOS / Windows / Linux 上完成 OpenCode 安装、模型认证与基础配置确保启动即用。1. 安装方式总览macOS / LinuxWindows选择安装方式操作系统curl 脚本 / brew / npm / ArchWSL 推荐 / scoop / choco / 二进制验证 opencode --versionopencode auth login可直接使用⚠️Windows 用户强烈建议使用 WSL自动安装方式在原生 Windows 上兼容性较差WSL 提供最佳性能与完整功能。2. 各平台安装步骤2.1 一键安装脚本推荐跨平台curl-fsSLhttps://opencode.ai/install|bash安装脚本的目录优先级$OPENCODE_INSTALL_DIR—— 自定义安装目录最高优先$HOME/.opencode/bin—— 默认回退目录$XDG_BIN_DIR如$HOME/.local/bin示例指定安装目录OPENCODE_INSTALL_DIR/usr/local/bincurl-fsSLhttps://opencode.ai/install|bash# 或XDG_BIN_DIR$HOME/.local/bincurl-fsSLhttps://opencode.ai/install|bash2.2 使用 Node.js 包管理器npminstall-gopencode-ailatest# npmbuninstall-gopencode-ai# bunpnpminstall-gopencode-ai# pnpmyarnglobaladdopencode-ai# yarn2.3 macOS / LinuxHomebrew# 官方 tap更新最及时推荐brewinstallanomalyco/tap/opencode# 等价于旧写法brew install sst/tap/opencode# Homebrew 官方公式更新较慢brewinstallopencode2.4 Windows# Scoop推荐scoop bucket add extras scoop install extras/opencode# Chocolateychoco install opencode若自动方式不可用请从 GitHub Releases 下载对应架构的二进制opencode-windows-*.zip解压到 PATH 目录。2.5 Arch Linuxsudopacman-Sopencode# 稳定版# 或 AUR 最新版paru-Sopencode-bin2.6 桌面端Desktop从 GitHub Releases 下载opencode-desktop-*.deb/*.rpm/*.dmg/.exe安装或用opencode web在浏览器中使用。3. 验证安装opencode--version# 预期输出类似opencode version v1.18.3提示若提示命令未找到检查安装目录是否已加入PATH如~/.opencode/bin或~/.local/bin。4. 模型认证AuthOpenCode 由 Models.dev 驱动支持 75 提供方。首次使用需配置凭证opencode auth login交互示例$ opencode auth login ┌ Add credential │ ◆ Select provider │ ● Anthropic (recommended) │ ○ OpenAI │ ○ Google │ ○ Amazon Bedrock │ ○ Azure │ ○ DeepSeek │ ○ Groq │ ... └凭证默认存储于~/.local/share/opencode/auth.json。也可通过环境变量或项目内.env文件提供 Key见第 4.3 节。查看已配置的提供方opencode auth list# 或 opencode auth ls注销某个提供方opencode authlogoutanthropic5. 配置文件详解5.1 文件格式与位置格式JSON / JSONC支持注释全局 Schemahttps://opencode.ai/config.json。TUI 专属配置 Schemahttps://opencode.ai/tui.json。配置加载优先级合并而非替换后者覆盖前者冲突键MDM 托管配置最高优先Remote .well-known/opencodeGlobal ~/.config/opencode/opencode.jsonOPENCODE_CONFIG 指定Project opencode.json.opencode 目录OPENCODE_CONFIG_CONTENT 内联全局配置路径~/.config/opencode/opencode.json项目配置路径项目根目录opencode.json启动时会从当前目录向上查找到最近的 Git 根5.2 最小可用配置Anthropic{$schema:https://opencode.ai/config.json,model:anthropic/claude-sonnet-4-5,provider:{anthropic:{options:{apiKey:{env:ANTHROPIC_API_KEY},timeout:600000}}}}5.3 设置默认模型与轻量模型{model:anthropic/claude-sonnet-4-5,small_model:anthropic/claude-haiku-4-5}model主模型用于编码等重任务。small_model轻量任务如生成标题使用的更便宜模型。5.4 多提供方共存{provider:{anthropic:{options:{apiKey:{env:ANTHROPIC_API_KEY}}},openai:{options:{apiKey:{file:~/.secrets/openai-key}}}},model:anthropic/claude-sonnet-4-5,enabled_providers:[anthropic,openai]}enabled_providers白名单disabled_providers黑名单优先级更高。5.5 API Key 的安全写法变量替换避免在配置中明文写 Key{provider:{openai:{options:{apiKey:{file:~/.secrets/openai-key}}}}}{env:VAR_NAME}读取环境变量未设置则为空串。{file:path}读取文件内容相对配置目录或绝对路径/或~开头。5.6 提供方特定选项示例Amazon Bedrock{provider:{amazon-bedrock:{options:{region:us-east-1,profile:my-aws-profile,endpoint:https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com}}}}6. 环境变量参考变量作用OPENCODE_CONFIG自定义配置文件路径OPENCODE_CONFIG_DIR自定义配置目录含 agents/commands 等OPENCODE_CONFIG_CONTENT运行时内联配置覆盖JSONOPENCODE_TUI_CONFIG自定义 TUI 配置文件ANTHROPIC_API_KEY/OPENAI_API_KEY/GEMINI_API_KEY各提供方 KeyOPENCODE_DISABLE_AUTOUPDATE设为true禁用自动更新检查OPENCODE_SERVER_PASSWORD为serve/web启用基本认证OPENCODE_GIT_BASH_PATHWindows 上 Git Bash 可执行文件路径7. 安装检查清单opencode --version 有输出opencode auth login 完成opencode auth list 可见提供方cd 到项目执行 opencode 能启动完成以上三步即可进入03-界面与快捷键.md熟悉界面。本篇为 OpenCode 操作指导书系列之一版本 v1.18.3。