OpenCode 配置

OpenCode 使用 JSON 配置格式,支持系统级(全局)和项目级(本地)配置。

配置文件

系统级配置

位置: ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

CLI 从 MegaLLM 获取可用模型并自动将它们添加到 provider.anthropic.models 部分。

项目级配置

位置: ./opencode.json(在项目根目录)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

使用项目级配置可以针对每个项目自定义设置,同时保留全局默认值。{env:MEGALLM_API_KEY} 语法引用环境变量。

手动设置

系统级手动设置

# 1. 创建目录
mkdir -p ~/.config/opencode

# 2. 创建配置文件
cat > ~/.config/opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}
EOF

# 3. 设置环境变量
echo 'export MEGALLM_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

# 4. 验证
cat ~/.config/opencode/opencode.json | jq .

项目级手动设置

# 1. 导航到项目
cd ~/projects/my-project

# 2. 创建配置文件
cat > opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}
EOF

# 3. 设置环境变量(如果尚未设置)
echo 'export MEGALLM_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

# 4. 添加到 .gitignore
echo "opencode.json" >> .gitignore

配置优先级

OpenCode 按以下顺序加载配置(优先级从高到低):

环境变量

MEGALLM_API_KEY 环境变量(通过配置中的 {env:MEGALLM_API_KEY} 引用)

项目级配置

当前目录中的 ./opencode.json

系统级配置

主目录中的 ~/.config/opencode/opencode.json

配置选项

提供商设置

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "models": {
        "gpt-5": {
          "id": "gpt-5",
          "name": "GPT-5 (Via MegaLLM)"
        },
        "claude-sonnet-4": {
          "id": "claude-sonnet-4",
          "name": "Claude Sonnet 4 (Via MegaLLM)"
        }
      },
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  }
}

CLI 自动从 MegaLLM API 获取并填充 models 对象。您也可以手动添加或覆盖特定模型。

工具设置

{
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  },
  "autoupdate": true
}

可用模型:

gpt-5 - 最新的 GPT 模型
gpt-4 - GPT-4
claude-opus-4-1-20250805 - Claude Opus
claude-sonnet-4 - Claude Sonnet
gemini-2.5-pro - Gemini Pro
查看模型目录了解完整列表

完整示例

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "models": {
        "gpt-5": {
          "id": "gpt-5",
          "name": "GPT-5 (Via MegaLLM)"
        },
        "gpt-4": {
          "id": "gpt-4",
          "name": "GPT-4 (Via MegaLLM)"
        },
        "claude-sonnet-4": {
          "id": "claude-sonnet-4",
          "name": "Claude Sonnet 4 (Via MegaLLM)"
        }
      },
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

团队配置

对于团队项目,使用环境变量将 API 密钥排除在版本控制之外: 共享配置(opencode.json - 提交到 git):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  },
  "autoupdate": true,
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true
  }
}

添加到 .gitignore:

opencode.json

团队设置说明(README.md):

# OpenCode 设置

## 前提条件
1. 从 https://megallm.io/dashboard 获取 MegaLLM API 密钥
2. 安装 OpenCode: `npm install -g opencode-ai`

## 设置
设置 MEGALLM_API_KEY 环境变量:
```bash
export MEGALLM_API_KEY="your-api-key-here"

添加到您的 shell 配置(~/.bashrc 或 ~/.zshrc)使其永久生效。

## 环境变量

MegaLLM CLI 为 OpenCode 设置 `MEGALLM_API_KEY` 环境变量:

```bash
# CLI 自动设置
export MEGALLM_API_KEY="sk-mega-your-api-key-here"

此环境变量在 OpenCode 配置中使用 {env:MEGALLM_API_KEY} 引用。添加到您的 shell 配置:

# ~/.bashrc 或 ~/.zshrc
export MEGALLM_API_KEY="sk-mega-your-api-key-here"

验证环境变量

echo $MEGALLM_API_KEY
# 输出: sk-mega-your-api-key-here

验证

检查配置文件

# 系统配置
cat ~/.config/opencode/opencode.json | jq .

# 项目配置
cat opencode.json | jq .
cat opencode.local.json | jq .

# 检查文件权限
ls -la ~/.config/opencode/opencode.json
ls -la opencode.json

验证 JSON 语法

# 验证 JSON
jq . ~/.config/opencode/opencode.json

# 应该显示格式化的 JSON 或错误(如果无效)

测试 API 连接

# 使用 MEGALLM_API_KEY 测试
curl -H "Authorization: Bearer $MEGALLM_API_KEY" \
     -H "Content-Type: application/json" \
     https://ai.megallm.io/v1/models

# 应该返回可用模型列表

测试 OpenCode

# 运行 OpenCode
opencode

# 检查版本
opencode --version

# 使用文件测试
echo "console.log('test')" > test.js
opencode test.js

故障排除

配置未加载

检查文件位置:

# 系统配置
ls -la ~/.config/opencode/opencode.json

# 项目配置
ls -la opencode.json

验证 JSON 语法:

jq . ~/.config/opencode/opencode.json
# 应该显示格式化的 JSON

检查您是否在正确的目录中:

pwd
# 对于项目级配置,应该是您的项目目录

API 密钥未识别

检查环境变量:

echo $MEGALLM_API_KEY

如果为空,则设置:

export MEGALLM_API_KEY="your-api-key"
echo 'export MEGALLM_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

验证密钥格式:

必须以 sk-mega- 开头
至少 20 个字符
没有额外的空格或引号

测试密钥:

curl -H "Authorization: Bearer $MEGALLM_API_KEY" \
     -H "Content-Type: application/json" \
     https://ai.megallm.io/v1/models

基础 URL 错误

检查配置:

jq '.provider.anthropic.options.baseURL' ~/.config/opencode/opencode.json
# 应该显示: "https://ai.megallm.io/v1"

常见错误:

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://ai.megallm.io/v1"  // <Icon icon="check" /> 正确
        // "baseURL": "https://ai.megallm.io/v1/"  // <Icon icon="xmark" /> 错误(尾部斜杠)
        // "baseURL": "https://ai.megallm.io"  // <Icon icon="xmark" /> 错误(缺少 /v1)
      }
    }
  }
}

项目配置未覆盖系统配置

验证您有项目配置:

ls -la opencode.json

确保正确的 JSON 结构: 项目配置应使用与系统配置相同的结构,包含 provider.anthropic.options。

JSON 语法错误

常见 JSON 错误:

// <Icon icon="xmark" /> 错误 - 尾部逗号
{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}",
      }
    }
  }
}

// <Icon icon="check" /> 正确
{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}"
      }
    }
  }
}

// <Icon icon="xmark" /> 错误 - 单引号
{
  'provider': {
    'anthropic': {
      'options': {
        'apiKey': '{env:MEGALLM_API_KEY}'
      }
    }
  }
}

// <Icon icon="check" /> 正确 - 双引号
{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY}"
      }
    }
  }
}

验证:

jq . ~/.config/opencode/opencode.json
# 如果无效将显示错误

最佳实践

使用本地配置存储 API 密钥

将 API 密钥保存在 opencode.local.json 中并添加到 .gitignore

共享基础配置

提交不含 API 密钥的 opencode.json 以保持团队一致性

项目特定设置

使用项目级配置进行项目特定的上下文和设置

验证 JSON

手动编辑后始终验证 JSON 语法

高级用法

多个配置文件

# 创建不同的配置文件
cat > ~/.config/opencode/opencode.dev.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY_DEV}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  }
}
EOF

cat > ~/.config/opencode/opencode.prod.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:MEGALLM_API_KEY_PROD}",
        "baseURL": "https://ai.megallm.io/v1"
      }
    }
  }
}
EOF

# 设置环境变量
export MEGALLM_API_KEY_DEV="sk-mega-dev-key"
export MEGALLM_API_KEY_PROD="sk-mega-prod-key"

# 切换配置文件
alias opencode-dev='cp ~/.config/opencode/opencode.dev.json ~/.config/opencode/opencode.json && opencode'
alias opencode-prod='cp ~/.config/opencode/opencode.prod.json ~/.config/opencode/opencode.json && opencode'

CI/CD 配置

# GitHub Actions 示例
- name: Configure OpenCode
  env:
    MEGALLM_API_KEY: ${{ secrets.MEGALLM_API_KEY }}
  run: |
    mkdir -p ~/.config/opencode
    cat > ~/.config/opencode/opencode.json << 'EOF'
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "anthropic": {
          "options": {
            "apiKey": "{env:MEGALLM_API_KEY}",
            "baseURL": "https://ai.megallm.io/v1"
          }
        }
      }
    }
    EOF

下一步

Claude Code 配置

配置 Claude Code

Codex 配置

配置 Codex/Windsurf

示例

查看实际示例

其他代理

配置其他 CLI 和 GUI 代理

模型目录

浏览可用模型

概述

配置

​配置文件

​系统级配置

​项目级配置

​手动设置

​系统级手动设置

​项目级手动设置

​配置优先级

​配置选项

​提供商设置

​工具设置

​完整示例

​团队配置

​验证环境变量

​验证

​检查配置文件

​验证 JSON 语法

​测试 API 连接

​测试 OpenCode

​故障排除

​最佳实践

使用本地配置存储 API 密钥

共享基础配置

项目特定设置

验证 JSON

​高级用法

​多个配置文件

​CI/CD 配置

​下一步

Claude Code 配置

Codex 配置

示例

其他代理

模型目录

配置文件

系统级配置

项目级配置

手动设置

系统级手动设置

项目级手动设置

配置优先级

配置选项

提供商设置

工具设置

完整示例

团队配置

验证环境变量

验证

检查配置文件

验证 JSON 语法

测试 API 连接

测试 OpenCode

故障排除

最佳实践

高级用法

多个配置文件

CI/CD 配置

下一步