⚡
OpenCodeDocs

Bạn có thể cấu hình OpenCode thông qua file config JSON.

Định dạng

OpenCode hỗ trợ cả hai định dạng JSON và JSONC (JSON với Comments).

{
  "$schema": "https://opencode.ai/config.json",
  // Cấu hình theme
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
}

Vị trí lưu trữ

Bạn có thể đặt file config ở nhiều vị trí khác nhau và chúng có thứ tự ưu tiên khác nhau.

:::note Các file cấu hình được gộp lại với nhau, không phải thay thế. :::

Các file cấu hình được gộp lại, không phải thay thế. Các thiết lập từ các vị trí config sau được kết hợp. Config sau chỉ ghi đè config trước cho các key bị trùng. Các thiết lập không trùng từ tất cả config đều được giữ lại.

Ví dụ, nếu config global của bạn đặt theme: "opencode" và autoupdate: true, và config project đặt model: "anthropic/claude-sonnet-4-5", cấu hình cuối cùng sẽ bao gồm cả ba thiết lập.

Thứ tự ưu tiên

Các nguồn config được load theo thứ tự này (nguồn sau ghi đè nguồn trước):

  1. Remote config (từ .well-known/opencode) - mặc định của tổ chức
  2. Global config (~/.config/opencode/opencode.json) - tùy chọn người dùng
  3. Custom config (biến môi trường OPENCODE_CONFIG) - ghi đè tùy chỉnh
  4. Project config (opencode.json trong project) - thiết lập riêng cho project
  5. Thư mục .opencode - agents, commands, plugins
  6. Inline config (biến môi trường OPENCODE_CONFIG_CONTENT) - ghi đè lúc runtime

Điều này có nghĩa config project có thể ghi đè mặc định global, và config global có thể ghi đè mặc định remote của tổ chức.

:::note Các thư mục .opencode và ~/.config/opencode sử dụng tên số nhiều cho các thư mục con: agents/, commands/, modes/, plugins/, skills/, tools/, và themes/. Tên số ít (ví dụ agent/) cũng được hỗ trợ để tương thích ngược. :::

Remote

Các tổ chức có thể cung cấp cấu hình mặc định thông qua endpoint .well-known/opencode. Nó được tự động fetch khi bạn xác thực với provider hỗ trợ.

Remote config được load đầu tiên, đóng vai trò lớp nền. Tất cả các nguồn config khác (global, project) có thể ghi đè các mặc định này.

Ví dụ, nếu tổ chức của bạn cung cấp MCP servers bị tắt mặc định:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Bạn có thể bật các server cụ thể trong config local:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Đặt config OpenCode global trong ~/.config/opencode/opencode.json. Sử dụng config global cho các tùy chọn cá nhân như themes, providers, hoặc keybinds.

Config global ghi đè mặc định remote của tổ chức.

Theo project

Thêm opencode.json vào thư mục gốc project. Config project có độ ưu tiên cao nhất trong các file config tiêu chuẩn - nó ghi đè cả config global và remote.

:::tip Đặt config riêng cho project ở thư mục gốc của project. :::

Khi OpenCode khởi động, nó tìm file config trong thư mục hiện tại hoặc đi lên đến thư mục Git gần nhất.

File này cũng an toàn để commit vào Git và sử dụng cùng schema với config global.

Đường dẫn tùy chỉnh

Chỉ định đường dẫn file config tùy chỉnh bằng biến môi trường OPENCODE_CONFIG.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Config tùy chỉnh được load giữa config global và project trong thứ tự ưu tiên.

Thư mục tùy chỉnh

Chỉ định thư mục config tùy chỉnh bằng biến môi trường OPENCODE_CONFIG_DIR. Thư mục này sẽ được tìm kiếm agents, commands, modes, và plugins giống như thư mục .opencode tiêu chuẩn, và nên tuân theo cùng cấu trúc.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

Thư mục tùy chỉnh được load sau config global và các thư mục .opencode, nên nó có thể ghi đè các thiết lập của chúng.

Schema

File config có schema được định nghĩa tại opencode.ai/config.json.

Editor của bạn sẽ có thể validate và autocomplete dựa trên schema này.

TUI

Bạn có thể cấu hình các thiết lập riêng cho TUI thông qua option tui.

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Các option có sẵn:

  • scroll_acceleration.enabled - Bật tăng tốc cuộn kiểu macOS. Ưu tiên hơn scroll_speed.
  • scroll_speed - Hệ số tốc độ cuộn tùy chỉnh (mặc định: 3, tối thiểu: 1). Bị bỏ qua nếu scroll_acceleration.enabled là true.
  • diff_style - Điều khiển hiển thị diff. "auto" tự điều chỉnh theo độ rộng terminal, "stacked" luôn hiển thị một cột.

Tìm hiểu thêm về sử dụng TUI tại đây.

Server

Bạn có thể cấu hình thiết lập server cho các lệnh opencode serve và opencode web thông qua option server.

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["http://localhost:5173"]
  }
}

Các option có sẵn:

  • port - Cổng để lắng nghe.
  • hostname - Hostname để lắng nghe. Khi mdns được bật và không có hostname được đặt, mặc định là 0.0.0.0.
  • mdns - Bật mDNS service discovery. Cho phép các thiết bị khác trong mạng phát hiện OpenCode server của bạn.
  • cors - Các origin bổ sung cho phép CORS khi sử dụng HTTP server từ browser client. Giá trị phải là full origin (scheme + host + optional port), ví dụ https://app.example.com.

Tìm hiểu thêm về server tại đây.

Tools

Bạn có thể quản lý các tools mà LLM có thể sử dụng thông qua option tools.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Tìm hiểu thêm về tools tại đây.

Models

Bạn có thể cấu hình các providers và models muốn sử dụng trong config OpenCode thông qua các option provider, model và small_model.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Option small_model cấu hình một model riêng cho các tác vụ nhẹ như tạo tiêu đề. Mặc định, OpenCode cố gắng sử dụng model rẻ hơn nếu có từ provider của bạn, nếu không sẽ fallback về model chính.

Các option provider có thể bao gồm timeout và setCacheKey:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout - Timeout request tính bằng milliseconds (mặc định: 300000). Đặt false để tắt.
  • setCacheKey - Đảm bảo luôn đặt cache key cho provider được chỉ định.

Bạn cũng có thể cấu hình local models. Tìm hiểu thêm.

Options riêng cho Provider

Một số providers hỗ trợ các option cấu hình bổ sung ngoài các thiết lập chung timeout và apiKey.

Amazon Bedrock

Amazon Bedrock hỗ trợ cấu hình riêng cho AWS:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}
  • region - Vùng AWS cho Bedrock (mặc định là biến môi trường AWS_REGION hoặc us-east-1)
  • profile - AWS named profile từ ~/.aws/credentials (mặc định là biến môi trường AWS_PROFILE)
  • endpoint - URL endpoint tùy chỉnh cho VPC endpoints. Đây là alias cho option baseURL chung sử dụng thuật ngữ AWS. Nếu cả hai được chỉ định, endpoint được ưu tiên.

:::note Bearer tokens (AWS_BEARER_TOKEN_BEDROCK hoặc /connect) được ưu tiên hơn xác thực dựa trên profile. Xem thứ tự ưu tiên xác thực để biết chi tiết. :::

Tìm hiểu thêm về cấu hình Amazon Bedrock.

Themes

Bạn có thể cấu hình theme muốn sử dụng trong config OpenCode thông qua option theme.

{
  "$schema": "https://opencode.ai/config.json",
  "theme": ""
}

Tìm hiểu thêm tại đây.

Agents

Bạn có thể cấu hình các agents chuyên biệt cho các tác vụ cụ thể thông qua option agent.

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Tắt các tools chỉnh sửa file cho agent chỉ review
        "write": false,
        "edit": false,
      },
    },
  },
}

Bạn cũng có thể định nghĩa agents bằng các file markdown trong ~/.config/opencode/agents/ hoặc .opencode/agents/. Tìm hiểu thêm tại đây.

Agent mặc định

Bạn có thể đặt agent mặc định bằng option default_agent. Điều này xác định agent nào được sử dụng khi không có agent nào được chỉ định rõ ràng.

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

Agent mặc định phải là primary agent (không phải subagent). Có thể là agent tích hợp sẵn như "build" hoặc "plan", hoặc agent tùy chỉnh bạn đã định nghĩa. Nếu agent được chỉ định không tồn tại hoặc là subagent, OpenCode sẽ fallback về "build" với cảnh báo.

Thiết lập này áp dụng trên tất cả các giao diện: TUI, CLI (opencode run), desktop app, và GitHub Action.

Chia sẻ

Bạn có thể cấu hình tính năng share thông qua option share.

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

Option này nhận:

  • "manual" - Cho phép chia sẻ thủ công qua commands (mặc định)
  • "auto" - Tự động chia sẻ các cuộc hội thoại mới
  • "disabled" - Tắt hoàn toàn tính năng chia sẻ

Mặc định, sharing được đặt ở chế độ thủ công nơi bạn cần chia sẻ cuộc hội thoại một cách rõ ràng bằng lệnh /share.

Commands

Bạn có thể cấu hình các commands tùy chỉnh cho các tác vụ lặp đi lặp lại thông qua option command.

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

Bạn cũng có thể định nghĩa commands bằng các file markdown trong ~/.config/opencode/commands/ hoặc .opencode/commands/. Tìm hiểu thêm tại đây.

Keybinds

Bạn có thể tùy chỉnh phím tắt thông qua option keybinds.

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {}
}

Tìm hiểu thêm tại đây.

Tự động cập nhật

OpenCode sẽ tự động tải các bản cập nhật mới khi khởi động. Bạn có thể tắt tính năng này với option autoupdate.

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

Nếu bạn không muốn cập nhật nhưng muốn được thông báo khi có phiên bản mới, đặt autoupdate thành "notify". Lưu ý rằng điều này chỉ hoạt động nếu không cài đặt qua package manager như Homebrew.

Formatters

Bạn có thể cấu hình các code formatters thông qua option formatter.

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Tìm hiểu thêm về formatters tại đây.

Permissions

Mặc định, opencode cho phép tất cả các thao tác mà không yêu cầu phê duyệt rõ ràng. Bạn có thể thay đổi điều này bằng option permission.

Ví dụ, để đảm bảo các tools edit và bash yêu cầu phê duyệt của người dùng:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Tìm hiểu thêm về permissions tại đây.

Compaction

Bạn có thể điều khiển hành vi nén context thông qua option compaction.

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}
  • auto - Tự động nén session khi context đầy (mặc định: true).
  • prune - Xóa các output tool cũ để tiết kiệm tokens (mặc định: true).

Watcher

Bạn có thể cấu hình các pattern bỏ qua cho file watcher thông qua option watcher.

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Các pattern tuân theo cú pháp glob. Sử dụng để loại trừ các thư mục gây nhiễu khỏi việc theo dõi file.

MCP servers

Bạn có thể cấu hình các MCP servers muốn sử dụng thông qua option mcp.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

Tìm hiểu thêm tại đây.

Plugins

Plugins mở rộng OpenCode với các tools, hooks, và tích hợp tùy chỉnh.

Đặt các file plugin trong .opencode/plugins/ hoặc ~/.config/opencode/plugins/. Bạn cũng có thể load plugins từ npm thông qua option plugin.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Tìm hiểu thêm tại đây.

Instructions

Bạn có thể cấu hình các hướng dẫn cho model đang sử dụng thông qua option instructions.

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Option này nhận một mảng các đường dẫn và glob patterns đến các file hướng dẫn. Tìm hiểu thêm về rules tại đây.

Providers bị tắt

Bạn có thể tắt các providers được load tự động thông qua option disabled_providers. Điều này hữu ích khi bạn muốn ngăn một số providers được load ngay cả khi credentials có sẵn.

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

:::note disabled_providers được ưu tiên hơn enabled_providers. :::

Option disabled_providers nhận một mảng các provider ID. Khi một provider bị tắt:

  • Nó sẽ không được load ngay cả khi các biến môi trường được đặt.
  • Nó sẽ không được load ngay cả khi API keys được cấu hình qua lệnh /connect.
  • Các models của provider sẽ không xuất hiện trong danh sách chọn model.

Providers được bật

Bạn có thể chỉ định danh sách cho phép các providers thông qua option enabled_providers. Khi được đặt, chỉ các providers được chỉ định mới được bật và tất cả các providers khác sẽ bị bỏ qua.

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

Điều này hữu ích khi bạn muốn giới hạn OpenCode chỉ sử dụng các providers cụ thể thay vì tắt từng cái một.

:::note disabled_providers được ưu tiên hơn enabled_providers. :::

Nếu một provider xuất hiện trong cả enabled_providers và disabled_providers, disabled_providers được ưu tiên để tương thích ngược.

Experimental

Key experimental chứa các options đang được phát triển tích cực.

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

:::caution Các option experimental không ổn định. Chúng có thể thay đổi hoặc bị xóa mà không báo trước. :::

Biến

Bạn có thể sử dụng thay thế biến trong các file config để tham chiếu biến môi trường và nội dung file.

Biến môi trường

Sử dụng {env:VARIABLE_NAME} để thay thế biến môi trường:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Nếu biến môi trường không được đặt, nó sẽ được thay thế bằng chuỗi rỗng.

Files

Sử dụng {file:path/to/file} để thay thế nội dung của một file:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Đường dẫn file có thể là:

  • Tương đối với thư mục chứa file config
  • Hoặc đường dẫn tuyệt đối bắt đầu bằng / hoặc ~

Các trường hợp sử dụng hữu ích:

  • Giữ dữ liệu nhạy cảm như API keys trong các file riêng biệt.
  • Đưa các file hướng dẫn lớn vào mà không làm rối config.
  • Chia sẻ các đoạn cấu hình chung giữa nhiều file config.