opencode - 安装和配置

nlpming
12 阅读4分钟

opencode - 安装与配置

opencode 安装指南

一键安装（推荐）

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

包管理器安装

# 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）

# 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
Windowsopencode-desktop-windows-x64.exe
Linux.deb、.rpm 或 AppImage

自定义安装目录

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

  1. $OPENCODE_INSTALL_DIR — 自定义安装目录
  2. $XDG_BIN_DIR — XDG 规范路径
  3. $HOME/bin — 标准用户二进制目录
  4. $HOME/.opencode/bin — 默认回退路径
# 示例
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。

配置加载顺序

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

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

主要配置项

模型与提供商

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

  "provider": {
    "anthropic": {
      "timeout": 300000,       // 超时时间（毫秒）
      "chunkTimeout": 10000,   // 块间超时
      "baseURL": "https://..."  // 自定义端点
    }
  }
}
MiniMax 配置示例
{
  "$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 接口：

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：

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

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

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

opencode attach http://localhost:4096
配置文件
{
  "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：

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

opencode serve --port 4096

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

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

默认允许的来源：

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

添加自定义来源：

opencode serve --cors https://example.com --cors https://app.example.com
mDNS 局域网发现

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

opencode web --mdns --mdns-domain myproject.local
API 文档

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

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

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

Agents（代理）

{
  "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 — 只读代理，适合分析和代码探索

自定义命令

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

权限控制

{
  "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 服务器

{
  "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 服务器

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

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

代码格式化

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

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

插件

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

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

上下文压缩

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

工具输出限制

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

其他配置

{
  "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：

{
  "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}
{
  "provider": {
    "openai": {
      "apiKey": "{env:OPENAI_API_KEY}"
    }
  }
}

企业/组织配置

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

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

macOS MDM 管理：

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

更多详情请参考 官方文档。](opencode.ai/docs)%E3%80…)

avatar
文章
阅读
粉丝