Alibaba Cloud Linux 4 Agentic Edition（Agentic OS）提供多种认证方式、模型切换及分层配置管理，支持灵活的配置管理方式。-Alibaba Cloud Linux(Alinux)-阿里云帮助中心

Alibaba Cloud Linux 4 Agentic Edition（Agentic OS）通过分层配置体系管理认证、模型、工具等设置，支持项目级与用户级配置文件多层覆盖。本文介绍了多种认证方式的接入方法、模型切换操作，以及配置文件的层级优先级和核心配置项说明。

1 认证方式

Agentic OS 第一次启动需要通过认证连接大语言模型服务。后续可以用 /auth命令切换认证方式。

目前支持以下认证方式。

阿里云认证

在交互式界面选择「Aliyun Authentication」，可获得一定的免费额度。

在 ECS 环境中，终端显示授权 URL 和二维码。在浏览器中打开该 URL 或手机扫描二维码，完成阿里云账号登录并授权
在非 ECS 环境中，使用阿里云 AK/SK 认证
- 获取 AK/SK：
  1. 登录阿里云控制台
  2. 在 AccessKey 管理页面创建 Key

通过阿里云认证的用户可享受免费调用额度，适合个人开发和测试使用。

注意：阿里云认证方式仅支持使用千问系列文本模型，不支持多模态模型。

百炼认证

百炼认证已经预制好Base Url，可以选择Coding Plan、Token Plan、以及自定义模型认证方式，提供API Key进行认证。

OpenAI 兼容端点 API Key 认证

在交互式界面选择「OpenAI Compatible 」，准备 API Key ，支持的 OpenAI 兼容端点包括：

自定义 Base URL：本地部署的模型（如 vLLM、Ollama）、第三方 API 代理服务等。

认证管理

操作	命令
查看当前认证状态	`/auth`
切换认证方式	`/auth`（在交互菜单中选择）

常见问题：认证失败时，检查 API Key 是否正确（注意前后空格）、网络是否能访问对应的 API 端点。Agentic OS 支持同时配置多种认证，会按优先级选择，也可通过 /auth 手动切换。

2 模型配置

切换模型

使用 /auth 命令切换当前会话使用的模型，选择已配置的认证配置，然后选择"Set as active provider"。

3 配置文件

配置层级与优先级

Agentic OS 的系统 Shell 入口 cosh 使用 JSON 格式的配置文件管理设置，优先级从高到低：

命令行参数 > 环境变量 > 项目配置 > 用户配置 > 默认值

配置文件位置

类型	路径	说明
系统设置	`/etc/copilot-shell/config.toml`	管理员默认值
用户设置	`~/.copilot-shell/config.toml`	个人全局配置
项目设置	`.copilot-shell/config.toml`（项目根目录）	项目级配置，可团队共享

配置文件位置

类型	路径	说明
系统设置	`/etc/copilot-shell/config.toml`	管理员默认值
用户设置	`~/.copilot-shell/config.toml`	个人全局配置
项目设置	`.copilot-shell/config.toml`（项目根目录）	项目级配置，可团队共享

cosh-core 按系统 → 用户 → 项目的顺序合并配置。项目配置可以设置 Agent、Hook、Skill、会话、active_model 和回答语言偏好，但会忽略 active_provider、Provider 定义、MCP server 和项目审计设置。cosh-shell 只读取用户文件，不读取系统或项目文件。

核心配置项

ai --- AI 与模型设置

配置项	类型	默认值	说明
`active_provider`	string	---	当前激活的 Provider
`active_model`	string	---	当前使用的模型名称
`output_language`	string	---	回答语言偏好
`thinking`	string	---	thinking 模式偏好

ai.providers. --- Provider 定义

配置项	类型	默认值	说明
`type`	string	---	Provider 类型，如 `dashscope`、`openai_compat`、`aliyun`
`base_url`	string	---	API 基础 URL
`api_key`	string	---	API 密钥，建议使用 `${VAR_NAME}` 环境变量展开
`model`	string	---	该 Provider 的默认模型
`auth_source`	string	---	认证源，如 `ecs_ram_role`
`access_key_id`	string	---	阿里云 Access Key ID
`access_key_secret`	string	---	阿里云 Access Key Secret
`security_token`	string	---	阿里云 Security Token
`explicit_cache`	boolean	false	是否启用显式缓存

agent --- Agent 行为设置

配置项	类型	默认值	说明
`approval_mode`	string	"recommend"	Core 审批模式：`recommend`、`auto`、`trust`
`max_turns`	number	50	单次 Agent 请求的最大轮次
`max_tool_calls_per_turn`	number	10	每轮最大工具调用数
`session_token_limit`	number	128000	会话 token 限制
`allowed_tools`	array	[]	免审批的工具列表

session --- 会话管理

配置项	类型	默认值	说明
`auto_persist`	boolean	true	是否自动持久化会话
`persist_dir`	string	"~/.copilot-shell/cosh-core/sessions"	会话持久化目录

session.compaction --- 会话压缩

配置项	类型	默认值	说明
`enabled`	boolean	true	启用压缩
`auto`	boolean	true	自动压缩
`trigger_ratio`	number	0.70	触发正常压缩的上下文比例
`emergency_ratio`	number	0.90	触发紧急保护的上下文比例
`target_ratio`	number	0.30	压缩后的目标上下文比例
`preserve_recent_runs`	number	2	保留的最近完整 Agent 运行数
`auto_compact_token_limit`	number	---	可选的绝对触发 token 限制
`model_context_window`	number	---	模型上下文窗口覆盖值
`model_max_output_tokens`	number	---	模型最大输出 token 覆盖值

必须保持 target_ratio <= trigger_ratio <= emergency_ratio。

shell --- Shell 交互设置

配置项	类型	默认值	说明
`default`	string	"auto"	默认 shell
`adapter_default`	string	"cosh-core"	默认适配器
`analysis_mode`	string	"smart"	分析模式：`smart`、`auto`、`manual`
`approval_mode`	string	"auto"	Shell 审批模式：`recommend`、`auto`、`trust`
`integration`	string	"enhanced"	Shell 集成模式：`enhanced`（默认，启用 marker hook 支持 AI 路由与命令事件，`Shift+Tab` 可在 Assisted 与 Shell-only 之间切换）、`native`（无 Hook，Shell 拥有全部输入）
`input_wait_timeout_secs`	number	120	输入等待超时秒数，`0` 表示禁用
`trusted_commands`	array	[]	受信任的命令列表
`trusted_project_roots`	array	[]	受信任的项目根目录列表

shell.recommendations --- Shell 建议

配置项	类型	默认值	说明
`enabled`	boolean	true	是否启用 Shell 建议
`bash_history`	boolean	false	是否使用 Bash history 生成建议

ui --- 界面设置

配置项	类型	默认值	说明
`language`	string	"auto"	UI 语言
`startup_banner`	boolean	true	启动横幅
`startup_hooks`	boolean	false	启动钩子
`debug`	boolean	false	调试模式
`log_level`	string	"warn"	UI 日志级别

skills --- 技能设置

配置项	类型	默认值	说明
`enabled`	boolean	false	是否启用自定义技能
`custom_paths`	array	[]	自定义技能路径列表

logging --- 日志设置

配置项	类型	默认值	说明
`level`	string	"warn"	日志级别

mcp.servers. --- MCP 服务器

MCP client 只能定义在系统或用户配置中。每个 server 使用 command（stdio）或 url（Streamable HTTP）之一；省略 allowed_tools 表示暴露全部工具，[ ] 表示不暴露工具。

配置项	类型	默认值	说明
`command`	string	---	stdio 服务器可执行文件路径
`url`	string	---	Streamable HTTP 端点
`args`	array	[]	命令行参数
`env`	table	{}	环境变量
`timeout_ms`	number	10000	请求超时毫秒
`startup_timeout_ms`	number	30000	启动超时毫秒
`allowed_tools`	array	---	允许暴露的工具列表

health --- 健康检查

配置项	类型	默认值	说明
`enabled`	boolean	true	是否启用健康检查
`role`	string	---	角色标识
`memory_sensitive`	boolean	false	内存敏感模式
`critical_mounts`	array	["/"]	关键挂载点列表
`verbose`	boolean	false	详细输出模式

health.services 使用 TOML 数组表定义：

[[health.services]]
name = "nginx"
expected = "active"

audit --- 审计设置

系统文件包含 [audit] 表时，以系统设置为准；否则使用用户设置。项目审计表会被忽略。

配置项	类型	默认值	说明
`mode`	string	"best_effort"	审计模式：`best_effort` 或 `required`
`retention_days`	number	30	审计数据保留天数
`max_disk_bytes`	number	1073741824	审计数据最大磁盘占用字节