#安装与配置

#环境要求

• 终端：WezTerm、Alacritty、Ghostty、Kitty 等现代终端（推荐）
• Node.js（可选）：用于 npm install -g opencode-ai
• API Key：至少一个 LLM Provider，或使用 OpenCode Zen
• Windows：推荐 WSL2；原生支持 Chocolatey / Scoop / npm

#安装

#官方脚本（推荐）

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

#npm / Bun / pnpm / Yarn

npm install -g opencode-ai
# 或
bun install -g opencode-ai

#Homebrew（macOS / Linux）

brew install anomalyco/tap/opencode

官方 tap 更新更及时；brew install opencode 由 Homebrew 社区维护，版本可能滞后。

#Windows

# Chocolatey
choco install opencode

# Scoop
scoop install opencode

# npm
npm install -g opencode-ai

#Docker

docker run -it --rm ghcr.io/anomalyco/opencode

#验证

opencode --version

#配置目录

配置合并规则： 多来源配置合并而非覆盖；冲突时后加载的源优先级更高。完整顺序见 架构。

#连接 Provider

在 TUI 中执行：

/connect

按提示选择 Provider，例如：

#OpenCode Zen（推荐新手）

1. 选择 opencode
2. 浏览器打开 opencode.ai/auth
3. 登录并复制 API Key 粘贴到终端

#其他 Provider

支持 Anthropic、OpenAI、Google、本地 Ollama 等（以 /connect 列表为准）。在 opencode.json 中也可手动配置：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6"
}

模型 ID 格式为 provider/model-id。可用 opencode models 查看可用列表。

#全局配置示例

~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.1-codex",
  "autoupdate": true,
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

#环境变量（常用）

#常见问题

Windows 下功能异常？
优先在 WSL2 中安装 Node 与 OpenCode，在 Linux 文件系统内操作项目。

找不到模型？
运行 opencode models，确认 Provider 已 /connect 且 API Key 有效。

配置不生效？
检查项目根是否有 opencode.json 覆盖了全局项；注意 JSON 需符合 schema。

#下一步

• 快速上手：进入 TUI 并完成 /init
• 配置与 CLI 参考：完整配置项