基础配置指南

⚙️ OpenCode 配置概览

OpenCode 提供了强大的配置系统，让你可以根据个人需求和使用场景进行深度定制。本指南将带你完成从基础到高级的所有配置。

🎯 配置文件结构

配置文件位置

bash

# 查看配置文件路径
opencode config show config_path
# 默认位置：
# - macOS: ~/Library/Application Support/OpenCode/config.json
# - Linux: ~/.config/opencode/config.json  
# - Windows: %APPDATA%/OpenCode/config.json

配置文件格式

json

{
  "version": "2.1.0",
  "user": {
    "name": "Your Name",
    "email": "your@email.com",
    "preferences": {
      "language": "zh-CN",
      "theme": "auto",
      "font_size": 14
    }
  },
  "providers": {
    "primary": "openai",
    "fallback": ["anthropic", "zhipu"],
    "models": {
      "openai": {
        "model": "gpt-4",
        "api_key": "sk-...",
        "base_url": "https://api.openai.com/v1",
        "temperature": 0.7,
        "max_tokens": 4000
      }
    }
  },
  "network": {
    "proxy": {
      "enabled": false,
      "http": "http://127.0.0.1:7890",
      "socks5": "socks5://127.0.0.1:1080"
    },
    "timeout": 30000,
    "retries": 3,
    "verify_ssl": true
  },
  "ui": {
    "theme": "auto",
    "font_family": "JetBrains Mono",
    "font_size": 14,
    "line_numbers": true,
    "wrap_text": true,
    "show_minimap": false,
    "tab_size": 4
  },
  "features": {
    "auto_save": true,
    "auto_backup": true,
    "clipboard_sync": false,
    "telemetry": false,
    "beta_features": false
  },
  "workspace": {
    "default_workspace": "~/projects",
    "auto_switch": true,
    "recent_projects": []
  },
  "security": {
    "encryption": {
      "enabled": true,
      "algorithm": "AES-256-GCM"
    },
    "data_retention": {
      "chat_history": "never",
      "files_processed": "30d",
      "error_logs": "7d"
    }
  }
}

🚀 快速配置向导

交互式配置（推荐新手）

bash

# 启动配置向导
opencode config wizard

# 向导会询问：
# 1. 使用目的和经验水平
# 2. 偏好的语言和地区
# 3. 网络环境检测
# 4. 模型提供商选择
# 5. 界面偏好设置
# 6. 隐私和安全设置

模板化配置

bash

# 开发者模板
opencode config use-template developer

# 写作者模板  
opencode config use-template writer

# 分析师模板
opencode config use-template analyst

# 学生模板
opencode config use-template student

🤖 模型提供商配置

OpenAI 配置

bash

# 基础配置
opencode config set openai.api_key "sk-your-api-key-here"
opencode config set openai.model "gpt-4"
opencode config set openai.temperature 0.7
opencode config set openai.max_tokens 4000

# 高级配置
opencode config set openai.base_url "https://api.openai.com/v1"
opencode config set openai.organization "org-your-org-here"
opencode config set openai.timeout 30000
opencode config set openai.retries 3

# 多账号配置
opencode config set openai.accounts.primary "sk-primary-key"
opencode config set openai.accounts.backup "sk-backup-key"
opencode config set openai.accounts.auto_switch true

Anthropic Claude 配置

bash

# Claude 3 Opus（最强推理模型）
opencode config set anthropic.api_key "sk-ant-api03-key-here"
opencode config set anthropic.model "claude-3-opus-20240229"
opencode config set anthropic.max_tokens 4096

# Claude 3 Sonnet（平衡性能和成本）
opencode config set anthropic.model "claude-3-sonnet-20240229"
opencode config set anthropic.max_tokens 200000

# 多模型配置
opencode config set anthropic.routing {
  "creative_tasks": "claude-3-opus-20240229",
  "coding_tasks": "claude-3-sonnet-20240229",
  "quick_tasks": "claude-3-haiku-20240307"
}

国产模型配置

智谱 AI (GLM)

bash

# GLM-4 配置
opencode config set zhipu.api_key "your-zhipu-api-key"
opencode config set zhipu.model "glm-4"
opencode config set zhipu.base_url "https://open.bigmodel.cn/api/paas/v4/"
opencode config set zhipu.temperature 0.8

# GLM-3 Turbo 配置
opencode config set zhipu.model "glm-3-turbo"
opencode config set zhipu.temperature 0.7
opencode config set zhipu.max_tokens 8192

DeepSeek 配置

bash

# DeepSeek V2 配置
opencode config set deepseek.api_key "your-deepseek-key"
opencode config set deepseek.model "deepseek-coder"
opencode config set deepseek.base_url "https://api.deepseek.com/v1"

阿里云配置

bash

# Qwen-Turbo 配置
opencode config set qwen.api_key "your-qwen-key"
opencode config set qwen.model "qwen-turbo"
opencode config set qwen.base_url "https://dashscope.aliyuncs.com/api/v1/"

🌐 网络配置详解

代理设置

HTTP/HTTPS 代理

bash

# 设置 HTTP 代理
opencode config set network.proxy.http "http://proxy.company.com:8080"
opencode config set network.proxy.https "https://proxy.company.com:8080"
opencode config set network.proxy.exclude ["localhost", "127.0.0.1"]

# 认证代理
opencode config set network.proxy.auth {
  "username": "your-username",
  "password": "your-password",
  "ntlm_domain": "your-domain"
}

SOCKS5 代理

bash

# SOCKS5 代理配置
opencode config set network.proxy.socks5 "socks5://127.0.0.1:1080"
opencode config set network.proxy.socks5_auth {
  "username": "proxy-user",
  "password": "proxy-pass"
}

网络优化

bash

# 连接池配置
opencode config set network.max_connections 10
opencode config set network.keep_alive true
opencode config set network.idle_timeout 30000

# 重试策略
opencode config set network.retry_policy {
  "max_retries": 3,
  "backoff_factor": 2,
  "max_backoff": 60000
}

# 断路器（自动故障转移）
opencode config set network.circuit_breaker {
  "failure_threshold": 5,
  "recovery_timeout": 300000,
  "half_open_timeout": 60000
}

🎨 用户界面配置

主题设置

bash

# 浅色主题
opencode config set ui.theme "light"

# 深色主题
opencode config set ui.theme "dark"

# 自动主题（跟随系统）
opencode config set ui.theme "auto"

# 自定义主题
opencode config set ui.theme.custom {
  "primary": "#2563eb",
  "background": "#ffffff",
  "text": "#1a202c",
  "accent": "#7c3aed",
  "border": "#e2e8f0"
}

字体和编辑器配置

bash

# 字体设置
opencode config set ui.font.family "JetBrains Mono"
opencode config set ui.font.size 14
opencode config set ui.font.line_height 1.6

# 编辑器设置
opencode config set ui.editor.tab_size 4
opencode config set ui.editor.insert_spaces true
opencode config set ui.editor.word_wrap true
opencode config set ui.editor.show_line_numbers true
opencode config set ui.editor.show_minimap false

# 语法高亮
opencode config set ui.editor.syntax_theme "github-light"
opencode config set ui.editor.bracket_matching true
opencode config set ui.editor.highlight_current_line true

界面布局

bash

# 侧边栏位置
opencode config set ui.sidebar.position "left"

# 窗口布局
opencode config set ui.layout {
  "main_pane_width": "70%",
  "sidebar_width": "30%",
  "status_bar_height": "30px"
}

# 快捷键绑定
opencode config set ui.keybindings {
  "save": "Ctrl+S",
  "find": "Ctrl+F",
  "replace": "Ctrl+H",
  "new_file": "Ctrl+N",
  "open_file": "Ctrl+O"
}

🛠️ 高级功能配置

Agent 和 Skill 系统

bash

# 启用 Agent
opencode config set features.agents.enabled true
opencode config set features.agents.default "git-master"

# 配置 Skills
opencode config set features.skills {
  "code_review": {
    "enabled": true,
    "severity": "warning",
    "auto_fix": true
  },
  "performance_analysis": {
    "enabled": true,
    "benchmark": true
  },
  "security_scan": {
    "enabled": true,
    "tools": ["semgrep", "eslint", "bandit"]
  }
}

# 自定义 Agent
opencode config set features.agents.custom {
  "name": "Database Expert",
  "description": "Database optimization and analysis expert",
  "prompts": ["Analyze database schema", "Optimize SQL queries", "Suggest indexing strategies"],
  "skills": ["sql_analysis", "performance_tuning", "schema_design"]
}

自动化和工作流

bash

# 自动保存
opencode config set features.auto_save.enabled true
opencode config set features.auto_save.interval 300000  # 5分钟

# 自动备份
opencode config set features.backup.enabled true
opencode config set features.backup.location "~/opencode-backups"
opencode config set features.backup.retention "30d"

# 智能补全
opencode config set features.completion.enabled true
opencode config set features.completion.context_aware true
opencode config set features.completion.suggestions 10

插件系统

bash

# 插件仓库配置
opencode config set plugins.repositories [
  "https://github.com/opencode-cn/opencode-plugins",
  "https://github.com/your-org/custom-plugins"
]

# 插件管理
opencode config set plugins.auto_update true
opencode config set plugins.verify_signature true
opencode config set plugins.sandbox true

# 必需插件
opencode config set plugins.required ["git-helper", "docker-assistant", "database-tool"]

🔒 安全和隐私配置

数据加密

bash

# 启用端到端加密
opencode config set security.encryption.enabled true
opencode config set security.encryption.algorithm "AES-256-GCM"
opencode config set security.encryption.key_derivation "PBKDF2"

# API 密钥管理
opencode config set security.api_keys.store "encrypted"
opencode config set security.api_keys.rotation_period "90d"

数据保留策略

bash

# 聊天历史记录
opencode config set security.data_retention.chat_history "never"  # never, 7d, 30d, 90d, 365d

# 文件处理记录
opencode config set security.data_retention.file_access "never"  # never, 24h, 7d, 30d

# 错误日志记录
opencode config set security.data_retention.error_logs "7d"

# 自动清理
opencode config set security.data_retention.auto_cleanup true
opencode config set security.data_retention.cleanup_interval "7d"

访问控制

bash

# 内容过滤
opencode config set security.content_filter.enabled true
opencode config set security.content_filter.level "strict"

# 使用限制
opencode config set security.usage_limits {
  "daily_requests": 1000,
  "hourly_requests": 100,
  "max_tokens_per_request": 8000
}

# 审计日志
opencode config set security.audit.enabled true
opencode config set security.audit.log_level "info"

🔧 故障排除

配置文件问题

重置配置

bash

# 重置所有配置到默认值
opencode config reset

# 重置特定分类
opencode config reset --providers
opencode config reset --network
opencode config reset --ui

配置验证

bash

# 验证配置文件完整性
opencode config validate

# 检查配置语法错误
opencode config check

# 显示当前配置
opencode config show

配置导入导出

bash

# 导出配置
opencode config export > my-config.json

# 导入配置
opencode config import my-config.json

# 导出特定配置
opencode config export --providers > providers-config.json
opencode config export --security > security-config.json

环境变量配置

bash

# 使用环境变量覆盖配置
export OPENCODE_API_KEY="your-api-key"
export OPENCODE_BASE_URL="https://api.openai.com/v1"
export OPENCODE_MODEL="gpt-4"
export OPENCODE_PROXY="http://proxy.company.com:8080"

# 环境变量优先级
opencode config set env_var_priority true

🎯 配置最佳实践

性能优化

bash

# 设置合理的超时和重试
opencode config set network.timeout 30000
opencode config set network.retries 3

# 启用缓存
opencode config set performance.cache.enabled true
opencode config set performance.cache.size "1GB"

# 调整并发设置
opencode config set performance.max_concurrent 5

稳定性建议

bash

# 设置故障转移
opencode config set reliability.fallback_providers true
opencode config set reliability.health_check.enabled true

# 启用重试机制
opencode config set reliability.retry_exponential_backoff true

开发者技巧

bash

# 使用配置文件版本控制
opencode config set version_control.enabled true
opencode config set version_control.auto_backup true

# 开发模式配置
opencode config set development.debug_mode true
opencode config set development.verbose_logging true

🚀 配置完成！

现在你的 OpenCode 已经根据你的需求进行了个性化配置。让我们验证一下配置是否生效：

验证命令

bash

# 检查配置状态
opencode config status

# 测试网络连接
opencode test --network

# 测试模型连接
opencode test --provider openai

# 完整健康检查
opencode doctor

下一步

配置完成后，你可以：

开始使用：直接运行 opencode 开始对话
学习高级功能：查看高级使用指南
集成开发工具：查看集成指南
加入社区：参与 GitHub 讨论

🎉 享受你的个性化 OpenCode 体验！

基础配置指南 ​

⚙️ OpenCode 配置概览 ​

🎯 配置文件结构 ​

配置文件位置 ​

配置文件格式 ​

🚀 快速配置向导 ​

交互式配置（推荐新手） ​

模板化配置 ​

🤖 模型提供商配置 ​

OpenAI 配置 ​

Anthropic Claude 配置 ​

国产模型配置 ​

智谱 AI (GLM) ​

DeepSeek 配置 ​

阿里云配置 ​

🌐 网络配置详解 ​

代理设置 ​

HTTP/HTTPS 代理 ​

SOCKS5 代理 ​

网络优化 ​

🎨 用户界面配置 ​

主题设置 ​

字体和编辑器配置 ​

界面布局 ​

🛠️ 高级功能配置 ​

Agent 和 Skill 系统 ​

自动化和工作流 ​

插件系统 ​

🔒 安全和隐私配置 ​

数据加密 ​

数据保留策略 ​

访问控制 ​

🔧 故障排除 ​

配置文件问题 ​

重置配置 ​

配置验证 ​

配置导入导出 ​

环境变量配置 ​

🎯 配置最佳实践 ​

性能优化 ​

稳定性建议 ​

开发者技巧 ​

🚀 配置完成！ ​

验证命令 ​

下一步 ​

基础配置指南

⚙️ OpenCode 配置概览

🎯 配置文件结构

配置文件位置

配置文件格式

🚀 快速配置向导

交互式配置（推荐新手）

模板化配置

🤖 模型提供商配置

OpenAI 配置

Anthropic Claude 配置

国产模型配置

智谱 AI (GLM)

DeepSeek 配置

阿里云配置

🌐 网络配置详解

代理设置

HTTP/HTTPS 代理

SOCKS5 代理

网络优化

🎨 用户界面配置

主题设置

字体和编辑器配置

界面布局

🛠️ 高级功能配置

Agent 和 Skill 系统

自动化和工作流

插件系统

🔒 安全和隐私配置

数据加密

数据保留策略

访问控制

🔧 故障排除

配置文件问题

重置配置

配置验证

配置导入导出

环境变量配置

🎯 配置最佳实践

性能优化

稳定性建议

开发者技巧

🚀 配置完成！

验证命令

下一步