LowHow 文档

中文

English

中文

English

深色模式

OpenCode 配置实战教程：从零开始定制你的 AI 助手 ​

📚 分类: AI 工具配置 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode (最新稳定版) 🌐 原文来源: OpenCode 官方文档 - 配置

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode 配置文件的层级结构和加载优先级
  • [ ] 独立创建全局和项目级别的配置文件
  • [ ] 配置 AI 模型、服务器端口、快捷键等核心选项
  • [ ] 使用环境变量和文件引用管理敏感信息（如 API 密钥）
  • [ ] 排除配置不生效等常见问题

最终效果 ​

你将拥有一个个性化的 OpenCode 配置文件，它可以：

  • 自动连接到指定的 AI 模型（如 Claude）
  • 在自定义端口上启动 Web 服务
  • 禁用自动更新，改为手动通知
  • 安全地引用 API 密钥，避免明文存储

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
OpenCode最新稳定版opencode --version
一个文本编辑器任意-

1. 选择一个配置文件位置 ​

OpenCode 会从多个位置加载配置，并且这些配置会合并在一起。后面的配置会覆盖前面的同名设置。理解这个优先级顺序是配置的关键。

优先级顺序 (从低到高)：

  1. 远程配置 (组织默认，通常由管理员设置)
  2. 全局配置 (~/.config/opencode/opencode.json) - 你的个人偏好
  3. 自定义配置 (通过 OPENCODE_CONFIG 环境变量指定)
  4. 项目配置 (项目根目录下的 opencode.json) - 针对特定项目

💡 提示：对于本教程，我们将主要操作全局配置和项目配置，因为它们最常用。

第 1 步：创建你的全局配置文件 ​

🎯 目标：创建一个全局配置文件，设置你的个人偏好（如默认模型、主题）。

📝 操作：

  1. 打开终端，创建配置目录：

    bash
    $ mkdir -p ~/.config/opencode

  2. 使用文本编辑器在 ~/.config/opencode/ 目录下创建 opencode.json 文件：

    bash
    $ code ~/.config/opencode/opencode.json   // 使用 VS Code
# 或者
$ vim ~/.config/opencode/opencode.json     // 使用 Vim

  3. 将以下基础配置内容粘贴到文件中：

    json
    {
  "$schema": "https://opencode.ai/config.json",  // 提供编辑器的自动补全和校验
  "model": "anthropic/claude-sonnet-4-5",         // 设置你的主力模型
  "theme": "dark",                                 // 设置主题 (如果可用)
  "autoupdate": "notify"                           // 不自动更新，但通知有新版本
}

✅ 验证：

  1. 保存文件并退出编辑器。
  2. 在终端运行 opencode 命令启动 OpenCode。
  3. OpenCode 应该会使用你在配置中指定的模型和主题启动。

🤔 为什么要这样做？

  • $schema 字段告诉编辑器去哪里找配置的规则，这样你写代码时就会有自动补全和错误提示。
  • model 字段直接指定了 AI 模型，这样你就不需要每次启动都手动选择了。

⚠️ 常见错误： 如果 OpenCode 启动时提示找不到模型，请检查：

  1. 你的模型 ID 是否正确。模型 ID 的格式通常是 提供商/模型名称。
  2. 你是否已经配置好对应提供商的 API 密钥（例如，通过 ANTHROPIC_API_KEY 环境变量）。

第 2 步：为特定项目创建配置文件 ​

🎯 目标：为你的项目创建一个独立的配置文件，覆盖全局设置。

📝 操作：

  1. 进入你的项目根目录：

    bash
    $ cd /path/to/your/project

  2. 在项目根目录下创建 opencode.json 文件：

    bash
    $ touch opencode.json

  3. 编辑该文件，添加以下内容：

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-haiku-4-5",          // 项目使用更快的模型，节省成本
  "server": {
    "port": 4096,                                   // 项目服务启动在 4096 端口
    "hostname": "0.0.0.0"                           // 允许局域网内其他设备访问
  }
}

✅ 验证：

  1. 保存文件。
  2. 在这个项目目录下启动 OpenCode 的 Web 服务：
    bash
    $ opencode web
  3. 你会看到服务启动在 http://0.0.0.0:4096。
  4. 打开浏览器访问 http://localhost:4096，应该能看到 OpenCode 的 Web 界面。

🤔 为什么要这样做？

  • 项目配置的优先级高于全局配置。在这个项目中，OpenCode 会使用 claude-haiku-4-5 模型，而不是你在全局设置的 claude-sonnet-4-5。这让你可以根据项目需求（比如测试项目用便宜模型，生产项目用强大模型）灵活调整。
  • 配置 server 选项后，你的项目就可以作为一个独立的 AI 服务运行。

💡 提示：opencode.json 文件可以安全地提交到 Git 仓库中，方便团队成员共享项目特定的配置。

第 3 步：安全地管理 API 密钥 ​

🎯 目标：使用环境变量或文件引用，避免在配置文件中明文存储 API 密钥。

📝 操作：

方法一：使用环境变量

  1. 在你的 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中添加环境变量：

    bash
    $ echo 'export ANTHROPIC_API_KEY="sk-your-api-key-here"' >> ~/.zshrc
$ source ~/.zshrc

    ⚠️ 注意：请务必将 sk-your-api-key-here 替换为你的真实 API 密钥。

  2. 在 opencode.json 配置文件中引用该变量：

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"   // 引用环境变量
      }
    }
  }
}

方法二：使用文件引用

  1. 创建一个只有你自己有权限读取的密钥文件：

    bash
    $ echo "sk-your-api-key-here" > ~/.secrets/openai-key
$ chmod 600 ~/.secrets/openai-key   // 确保只有你能读写

  2. 在 opencode.json 配置文件中引用该文件：

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"   // 引用文件内容
      }
    }
  }
}

✅ 验证：

  1. 保存配置文件。
  2. 运行 OpenCode 并尝试发起一个对话。
  3. 如果对话成功，说明 API 密钥被正确引用。

🤔 为什么要这样做？

  • 安全：将密钥放在环境变量或加密文件中，可以防止因误提交 opencode.json 到公共 Git 仓库而导致的密钥泄露。
  • 灵活：你可以为不同环境（开发、测试、生产）设置不同的环境变量，而无需修改配置文件本身。

第 4 步：配置自定义命令和快捷键 ​

🎯 目标：创建快捷命令来自动执行重复性任务。

📝 操作：

  1. 打开你的项目级 opencode.json 文件（或全局配置文件）。

  2. 添加 command 和 keybinds 配置：

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite for this project and report any failures. Focus on the failing tests and suggest fixes.",
      "description": "Run full test suite",
      "model": "anthropic/claude-haiku-4-5"   // 测试任务使用轻量模型
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support. Include proper typing and basic structure.",
      "description": "Create a new React component"
    }
  },
  "keybinds": {
    "Ctrl+Shift+T": "command:test",          // 按快捷键触发 'test' 命令
    "Ctrl+Shift+C": "command:component"       // 按快捷键触发 'component' 命令
  }
}

✅ 验证：

  1. 启动 OpenCode。
  2. 在 TUI 界面中，按下 Ctrl+Shift+T 快捷键。
  3. OpenCode 应该会自动执行你定义的 test 命令，开始分析测试用例。
  4. $ARGUMENTS 是一个特殊变量，当你运行 component MyButton 命令时，MyButton 会被替换进去。

🤔 为什么要这样做？

  • 效率：将复杂的提示词封装成一个简单的命令，可以节省大量时间。
  • 一致性：团队所有成员使用相同的命令，可以确保代码审查、测试等任务的标准一致。

💡 提示：你还可以在 ~/.config/opencode/commands/ 目录下创建 .md 文件来定义命令，效果相同。

第 5 步：配置 MCP 服务器（可选扩展） ​

🎯 目标：连接一个外部 MCP 服务器，让 AI 能访问外部数据或执行更多操作。

📝 操作：

  1. 打开你的 opencode.json 配置文件。
  2. 添加 mcp 配置，例如连接一个 Jira 服务器：
    json
    {
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

✅ 验证： 在 OpenCode 中提问与 Jira 相关的问题（如“查看我的未完成任务”）。如果 AI 能正确回答，说明 MCP 服务器连接成功。

⚠️ 常见错误： 如果连接失败，请检查：

  1. MCP 服务器的 URL 是否正确。
  2. 你的 OpenCode 客户端是否有网络权限访问该 URL。
  3. 该 MCP 服务器是否需要额外的身份验证（例如，通过 HTTP Header 传递 Token）。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 使用 disabled_providers 和 enabled_providers：如果你想只使用 Anthropic 和 OpenAI，可以这样配置：

    json
    {
  "enabled_providers": ["anthropic", "openai"]
}

  2. 配置上下文压缩 (compaction)：对于长对话，可以启用自动压缩来节省 Token：

    json
    {
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

常见问题 (FAQ) ​

Q1: 我的配置不生效怎么办？A: 请检查以下几点：

  1. 优先级问题：确认你的配置是否被更高优先级的配置覆盖了。例如，项目配置会覆盖全局配置。
  2. JSON 格式错误：使用在线 JSON 校验工具检查你的文件是否有语法错误（如多了一个逗号）。
  3. 文件路径错误：确认配置文件确实放在了正确的位置（如 ~/.config/opencode/opencode.json 或项目根目录下的 opencode.json）。
  4. 重启 OpenCode：修改配置文件后，需要完全重启 OpenCode 才能生效。

Q2: autoupdate 设置成 false 为什么还会更新？A: 如果你是通过 Homebrew 等包管理器安装的 OpenCode，autoupdate 设置不会生效。包管理器会独立管理更新。autoupdate 仅对通过官方脚本或二进制包安装的版本有效。

Q3: 如何重置所有配置？A: 删除配置文件即可。全局配置位于 ~/.config/opencode/opencode.json，项目配置位于项目根目录的 opencode.json。删除后，OpenCode 将使用默认设置启动。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 配置优先级：远程 < 全局 < 自定义 < 项目，后面的配置会覆盖前面的。
  2. 核心配置项：model、server、theme、autoupdate 等。
  3. 安全管理：使用 {env:...} 和 {file:...} 来安全地引用 API 密钥。
  4. 效率提升：通过 command 和 keybinds 创建自定义快捷操作。
  5. 扩展能力：通过 mcp 连接外部服务。

现在，你的 OpenCode 已经是一个完全定制化、高效且安全的 AI 助手了！

© 2026 LowHow