配置文件与作用域
区分 settings、运行状态、权限和会话文件，理解覆盖顺序与迁移。
This page has not been translated into English yet. The original Chinese version is shown below.
Copilot CLI 默认将配置和本地运行数据放在 ~/.copilot。并非所有文件都应手工编辑，也并非把整个目录删除就能完成云端数据清理。
应该编辑哪个文件
| 文件或目录 | 用途 |
|---|---|
settings.json | 用户偏好，支持 JSONC，也可通过 /settings 修改 |
config.json | 自动管理的认证、插件元数据及运行状态 |
permissions-config.json | 按项目位置保存工具和目录批准 |
mcp-config.json | 用户级 MCP server 定义 |
lsp-config.json | 用户级语言服务器定义 |
providers.json | BYOK 提供商和模型注册表 |
copilot-instructions.md、instructions/ | 个人指令及 *.instructions.md 文件 |
agents/、skills/、hooks/、extensions/ | 个人扩展内容 |
旧版本曾把用户偏好和运行状态同时写进 config.json。当前版本会在启动时把可识别的用户设置迁移到 settings.json；loggedInUsers、installedPlugins、firstLaunchAt、staff 等内部状态保留在原文件。不要据此把整个 config.json 复制成设置文件。
配置覆盖顺序
通常按以下顺序加载，后者覆盖前者：内置默认值 → MDM 管理设置 → 用户设置 → 仓库设置 → 本地设置 → 环境变量 → 命令行参数。
| 作用域 | 位置 | 适用范围 |
|---|---|---|
| 用户 | ~/.copilot/settings.json | 所有仓库的个人默认值 |
| 仓库 | .github/copilot/settings.json | 随仓库共享 |
| 本地 | .github/copilot/settings.local.json | 当前仓库个人覆盖，加入 .gitignore |
这不是对每个字段都简单覆盖的承诺。仓库配置只支持官方列出的子集；其他字段即使在用户设置中有效，放到仓库文件也会被忽略。本地配置与仓库配置使用相同 Schema。
例如，deniedUrls、disabledMcpServers、disabledSkills 合并为并集，仓库只能追加；respectGitignore 只能收紧，不能通过仓库关闭用户的限制。仓库的 model、effortLevel、contextTier 仅在工作目录可信时生效。
MDM 的 permissions.disableBypassPermissionsMode 若设为 "disable"，用户不能覆盖；管理方的 sandbox 值构成不可放宽的最低限制，sandbox.failIfUnavailable 仅管理员可设。CLI 还会读取 .claude/settings.json 和 .claude/settings.local.json 中受支持的跨工具仓库配置子集，不表示兼容这些文件里的所有键。
改变配置位置
export COPILOT_HOME=/path/to/my/copilot-config这个变量替换整个 ~/.copilot 路径。旧位置的设置、会话、插件和权限不会自动在新位置出现；要保留它们，应有意识地复制或迁移所需内容。
缓存目录单独使用 COPILOT_CACHE_HOME 覆盖，不随 COPILOT_HOME 改变。默认位置是 macOS 的 ~/Library/Caches/copilot、Linux 的 $XDG_CACHE_HOME/copilot 或 ~/.cache/copilot、Windows 的 %LOCALAPPDATA%/copilot。
会话、日志与凭据后备存储
session-state/ 按会话 ID 保存 events.jsonl、计划、检查点和工作区文件，用于恢复会话。command-history-state/ 保存输入历史；session-store.db 是跨会话索引数据库。会话内输入 /session info 可查看当前日志路径，普通日志位于 logs/process-{timestamp}-{pid}.log。
installed-plugins/ 应通过插件卸载命令管理，以免元数据与文件不一致。mcp-oauth-config/ 和 mcp-secrets/ 可保存系统钥匙串不可用时的 MCP 后备凭据数据，不能把它们当作普通缓存随意公开。
删除本地 session-state/ 会失去本地恢复记录，不会删除已经同步到 GitHub 的会话。删除 session-store.db 后可用 /chronicle reindex 重建，但该命令还会同步会话数据，不只是本地重建。
配置没有生效
settings.json 读取、解析或校验失败时，CLI 会显示启动警告并忽略无效值；可识别的旧 config.json 设置仍可能合并。打开 /settings 的 Problems 标签定位问题。未知顶层键也会在该标签列出，$schema 例外。
如果文件本身有效，继续核对是否写到了错误作用域，或被仓库、管理员、环境变量和启动参数覆盖。日常修改方式见设置编辑器与命令。
托管字段的具体规则
官方总顺序将 MDM 描述为默认基线，但 MDM 专门章节又说明多数托管键会锁定。应优先检查具体字段：模型默认可在会话选择中改变，autoTier 普通值锁定，插件和市场逐条锁定，沙箱形成不可放宽的底线。不要把一般顺序用于证明用户总能覆盖企业设置，详见设备与托管配置。