opencode - 安装和配置

opencode - 安装与配置

opencode官方git地址：github.com/anomalyco/o...
opencode官方文档：opencode.ai/docs/zh-cn

opencode 安装指南

一键安装（推荐）

arduino 复制代码

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

包管理器安装

perl 复制代码

# macOS（推荐，始终保持最新）
brew install anomalyco/tap/opencode

# npm/bun/pnpm/yarn
npm i -g opencode-ai@latest

# Windows
scoop install opencode
choco install opencode

# Arch Linux
sudo pacman -S opencode          # 稳定版
paru -S opencode-bin             # AUR 最新版

# 其他
mise use -g opencode
nix run nixpkgs#opencode

桌面应用（Beta）

bash 复制代码

# macOS
brew install --cask opencode-desktop

# Windows
scoop bucket add extras; scoop install extras/opencode-desktop

或直接从 opencode.ai/download 下载对应平台的安装包：

平台	下载文件
macOS (Apple Silicon)	`opencode-desktop-darwin-aarch64.dmg`
macOS (Intel)	`opencode-desktop-darwin-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb`、`.rpm` 或 AppImage

自定义安装目录

安装脚本按以下优先级确定安装路径：

$OPENCODE_INSTALL_DIR --- 自定义安装目录
$XDG_BIN_DIR --- XDG 规范路径
$HOME/bin --- 标准用户二进制目录
$HOME/.opencode/bin --- 默认回退路径

bash 复制代码

# 示例
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

注意： 安装前请先移除 0.1.x 以下的旧版本。

opencode 配置指南

配置文件

opencode 支持 JSON 和 JSONC（带注释的 JSON）格式，配置文件名为 opencode.json。

配置加载顺序

配置文件会合并（而非覆盖），按以下优先级从低到高加载：

远程配置（/.well-known/opencode）--- 组织默认值
全局配置（~/.config/opencode/opencode.json）--- 用户偏好
自定义配置（OPENCODE_CONFIG 环境变量）
项目配置（项目根目录的 opencode.json）
.opencode 目录（agents、commands、plugins）
内联配置（OPENCODE_CONFIG_CONTENT 环境变量）
管理员配置文件（macOS: /Library/Application Support/opencode/）
macOS MDM 管理偏好（最高优先级）

主要配置项

模型与提供商

json 复制代码

{
  "model": "anthropic/claude-sonnet-4-5",  // 主模型，格式为 provider/model
  "small_model": "anthropic/claude-haiku-4-5",  // 轻量任务模型

  "provider": {
    "anthropic": {
      "timeout": 300000,       // 超时时间（毫秒）
      "chunkTimeout": 10000,   // 块间超时
      "baseURL": "https://..."  // 自定义端点
    }
  }
}

MiniMax 配置示例

kotlin 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "minimax-cn": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://api.minimaxi.com/anthropic/v1",
        "apiKey": "xxx"  // 替换为实际 API Key
      },
      "models": {
        "MiniMax-M2.5": {
          "name": "MiniMax M2.5"
        }
      }
    }
  },
  "model": "minimax-cn/MiniMax-M2.5"
}

服务器

启动命令

opencode serve --- 无界面 HTTP 服务，仅暴露 OpenAPI 接口：

ini 复制代码

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>] [--mdns] [--mdns-domain <string>]

# 示例：对外暴露服务并设置密码
OPENCODE_SERVER_PASSWORD=your-password opencode serve --port 4096 --hostname 0.0.0.0

opencode web --- 启动带浏览器界面的服务，自动打开 Web UI：

css 复制代码

opencode web [--port <number>] [--hostname <string>] [--cors <origin>] [--mdns] [--mdns-domain <string>]

# 示例：对外暴露并启用 mDNS 局域网发现
opencode web --hostname 0.0.0.0 --mdns

opencode attach --- 将终端 TUI 附加到已运行的服务：

arduino 复制代码

opencode attach http://localhost:4096

配置文件

json 复制代码

{
  "server": {
    "port": 4096,           // 默认 4096
    "hostname": "0.0.0.0",  // 默认 127.0.0.1（仅本机）
    "mdns": true,           // 启用局域网 mDNS 服务发现
    "mdnsDomain": "opencode.local",  // mDNS 域名
    "cors": ["https://my-app.com"]   // 额外允许的跨域来源
  }
}

认证

通过环境变量启用 HTTP Basic Auth：

ini 复制代码

export OPENCODE_SERVER_PASSWORD=your-password
export OPENCODE_SERVER_USERNAME=opencode  # 默认用户名为 opencode

opencode serve --port 4096

浏览器客户端也可通过 URL 参数传递认证信息：

bash 复制代码

http://localhost:4096?auth_token=<base64(username:password)>

CORS 跨域

默认允许的来源：

http://localhost:*
http://127.0.0.1:*
tauri://localhost（Tauri 桌面应用）
https://*.opencode.ai

添加自定义来源：

bash 复制代码

opencode serve --cors https://example.com --cors https://app.example.com

mDNS 局域网发现

启用后，服务会在局域网内广播，其他设备可通过域名访问：

css 复制代码

opencode web --mdns --mdns-domain myproject.local

API 文档

服务启动后，OpenAPI 3.1 规范文档可在以下地址访问：

xml 复制代码

http://<hostname>:<port>/doc

主要 API 端点：

端点	说明
`GET /global/health`	服务健康状态
`GET /global/event`	全局事件 SSE 流
`GET /session`	列出所有会话
`POST /session`	创建新会话
`POST /session/:id/message`	发送消息
`POST /session/:id/prompt_async`	异步发送消息
`POST /session/:id/abort`	中止运行中的会话
`GET /config/providers`	列出提供商及模型
`GET /find?pattern=<pat>`	搜索文件内容
`GET /event`	订阅服务端事件（SSE）

Shell

json 复制代码

{
  "shell": "/bin/zsh"  // 或 "pwsh" 等
}

Agents（代理）

json 复制代码

{
  "agent": {
    "my-agent": {
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一个专注于代码审查的助手",
      "temperature": 0.7,
      "mode": "primary",  // primary | subagent | all
      "color": "#ff6b6b",
      "steps": 100
    }
  },
  "default_agent": "build"  // 默认代理
}

内置代理：

build --- 默认，具有完整访问权限的开发代理
plan --- 只读代理，适合分析和代码探索

自定义命令

bash 复制代码

{
  "command": {
    "review": {
      "template": "请帮我审查以下代码：$ARGUMENTS",
      "description": "代码审查",
      "agent": "build"
    }
  }
}

权限控制

json 复制代码

{
  "permission": {
    "bash": "ask",      // allow | ask | deny
    "edit": "allow",
    "read": "allow",
    "webfetch": "ask",
    "websearch": "allow"
  }
}

支持的工具：read、edit、glob、grep、bash、task、skill、lsp、question、webfetch、websearch、codesearch、external_directory、doom_loop

MCP 服务器

json 复制代码

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["node", "server.js"],
      "environment": { "API_KEY": "{env:MY_API_KEY}" },
      "enabled": true,
      "timeout": 30000
    },
    "remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "enabled": true,
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

LSP 服务器

json 复制代码

{
  "lsp": {
    "typescript": {
      "disabled": false,
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"]
    }
  }
}

内置支持 40+ 语言服务器（TypeScript、Python、Rust、Go、Java、C/C++ 等）。

代码格式化

json 复制代码

{
  "formatter": {
    "prettier": {
      "disabled": false,
      "command": ["prettier", "--write"],
      "extensions": [".js", ".ts", ".json"]
    }
  }
}

内置支持 prettier、biome、clang-format、rustfmt、gofmt 等 30+ 格式化工具。

插件

perl 复制代码

{
  "plugin": ["opencode-plugin-name", "@org/plugin"]
}

插件目录：.opencode/plugins/ 或 ~/.config/opencode/plugins/

上下文压缩

yaml 复制代码

{
  "compaction": {
    "auto": true,
    "prune": true,
    "tail_turns": 10,
    "preserve_recent_tokens": 20000,
    "reserved": 5000
  }
}

工具输出限制

yaml 复制代码

{
  "tool_output": {
    "max_lines": 2000,
    "max_bytes": 51200
  }
}

其他配置

ruby 复制代码

{
  "snapshot": true,        // 文件变更快照（支持回滚）
  "autoupdate": "notify",  // true | false | "notify"
  "share": "manual",       // "manual" | "auto" | "disabled"
  "username": "my-name",
  "instructions": ["./AGENTS.md", "./docs/*.md"],
  "watcher": {
    "ignore": ["node_modules/**", "dist/**"]
  },
  "disabled_providers": ["openai"],
  "enabled_providers": ["anthropic"]
}

TUI 配置（tui.json）

与 opencode.json 同目录下创建 tui.json：

json 复制代码

{
  "theme": "tokyonight",  // tokyonight | everforest | ayu | catppuccin | gruvbox | kanagawa | nord | matrix | one-dark | system
  "scroll_speed": 3,
  "scroll_acceleration": { "enabled": true },
  "diff_style": "auto",  // auto | light | dark
  "mouse": true,
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c",
    "sidebar_toggle": "ctrl+s",
    "model_list": "ctrl+m",
    "agent_list": "ctrl+a",
    "theme_list": "ctrl+t"
  }
}

变量替换

配置文件中支持以下变量语法：

环境变量：{env:VARIABLE_NAME}
文件内容：{file:path/to/file}

json 复制代码

{
  "provider": {
    "openai": {
      "apiKey": "{env:OPENAI_API_KEY}"
    }
  }
}

企业/组织配置

通过 .well-known/opencode 端点为组织提供默认配置：

json 复制代码

{
  "config": {
    "model": "anthropic/claude-sonnet-4-5",
    "enabled_providers": ["anthropic"]
  }
}

macOS MDM 管理：

偏好域：ai.opencode.managed
通过 .mobileconfig 文件部署，优先级最高

更多详情请参考官方文档。](opencode.ai/docs)%E3%80...%25E3%2580%2582 "https://opencode.ai/docs)%E3%80%82"))