首次配置

先连接提供商并选择模型，再按需保存默认设置。

文档核验：2026-10-06，依据当前官方文档。本文未执行账号认证或模型 API 调用测试；模型 ID 仅作配置示例，以你本机的可用列表为准。

# 连接提供商#

在项目目录打开终端，启动 OpenCode：

bash
复制
opencode

在 OpenCode 的交互界面（TUI）中输入 /connect，选择提供商，按提示完成认证或输入 API 密钥：

text
复制
/connect

连接后，在 TUI 中输入 /models 选择模型。这些斜杠命令不是系统终端命令：

text
复制
/models

通过 /connect 保存的凭据位于 ~/.local/share/opencode/auth.json。这是凭据文件，不是项目配置文件，不要提交到仓库。不同服务的认证要求见官方提供商文档↗。

# 保存默认配置#

OpenCode 使用 JSON 或 JSONC（允许注释的 JSON）。全局配置放在 ~/.config/opencode/opencode.json，也可使用 opencode.jsonc；项目配置放在项目根目录的 opencode.json 或 opencode.jsonc。

例如，在全局或项目配置中保存默认模型：

json
复制
1{
2  "$schema": "https://opencode.ai/config.json",
3  "model": "anthropic/claude-sonnet-4-5"
4}

模型 ID 使用 提供商 ID/模型 ID。先在系统终端查看可用名称，再替换示例值：

bash
复制
opencode models

已通过 /connect 连接的常见提供商通常不需要重复填写 provider。全局配置和项目配置会合并；同一个键冲突时，项目配置覆盖全局值。OPENCODE_CONFIG 可指定自定义文件，它在全局配置之后、项目配置之前加载。完整顺序见官方配置文档↗。

旧教程中的 ~/.opencode/config.toml 和 [provider]、[model] 表结构不适用于这里的配置。迁移时需要改写字段和层级，不能只改扩展名。也可参考站内配置文档。

# 使用环境变量引用密钥（可选）#

如果你通过环境变量管理密钥，可在配置中引用它，而不把真实密钥写进项目文件：

json
复制
1{
2  "$schema": "https://opencode.ai/config.json",
3  "provider": {
4    "anthropic": {
5      "options": {
6        "apiKey": "{env:ANTHROPIC_API_KEY}"
7      }
8    }
9  }
10}

启动 OpenCode 的进程必须能读取 ANTHROPIC_API_KEY。未设置的环境变量会被替换为空字符串。环境变量引用不会创建密钥，也不会自动完成账号认证。

# 检查配置是否生效#

1. 用编辑器的 JSON Schema 提示检查字段与格式；JSON 文件不能包含注释，带注释请用 JSONC。
2. 在项目目录重新启动 opencode，确认没有配置解析错误。
3. 打开 /models，检查目标提供商和模型是否出现。
4. 如需验证 API 连通性，可发送一条简短请求；这一步会调用所选服务，可能产生费用。出现模型列表本身并不代表 API 调用成功。

当前官方 CLI 文档↗没有将 opencode --check 或 opencode config set model ... 列为配置方法。默认模型应写入 model 字段；临时指定模型可使用：

bash
复制
opencode --model anthropic/claude-sonnet-4-5

# 代理配置（按需）#

OpenCode 支持标准代理环境变量。将示例端口改成你的代理实际监听端口，并为本地服务绕过代理：

bash
复制
1export HTTP_PROXY="http://127.0.0.1:7890"
2export HTTPS_PROXY="http://127.0.0.1:7890"
3export NO_PROXY="localhost,127.0.0.1"
4opencode

已有 NO_PROXY 时保留原有条目并补上本地地址。不要沿用旧教程的 [proxy] TOML 配置，详情见官方网络文档↗。

# 下一步#

继续学习基础对话，或查看多模型配置。