通常只改两个文件
~/.dsh/settings.yaml 配置 provider、地址、模型；~/.dsh/.credentials.yaml 配置 API Key 变量。没有安装 Harness 或创建 Web profile 时，需先完成初始化。
API Key 不要写入教程、日志或公开仓库。凭据文件必须是顶层 YAML 映射，不能包裹在 credentials 或 keys 字段下。
1. 准备配置目录和凭据
cp ~/.dsh/settings.yaml ~/.dsh/settings.yaml.backup
mkdir -p ~/.dsh
chmod 700 ~/.dsh
touch ~/.dsh/.credentials.yaml
chmod 600 ~/.dsh/.credentials.yaml
mkdir -p ~/.dsh
chmod 700 ~/.dsh
touch ~/.dsh/.credentials.yaml
chmod 600 ~/.dsh/.credentials.yaml
在凭据文件中填写变量，apiKeyEnv 会通过变量名读取它：
OPENAI_API_KEY: your-key
DEEPSEEK_API_KEY: your-deepseek-key
DEEPSEEK_API_KEY: your-deepseek-key
2. 配置云桥API OpenAI 兼容服务
编辑 ~/.dsh/settings.yaml，将默认 provider 指向云桥API：
还没有 API Key？请先阅读第一节：注册与兑换卡密，再阅读第二节：获取 API Key 与 URL，完成创建和复制。
agent-default-model:
provider: yunqiao
model: gpt-5.6-sol
llm-pi-ai:
providers:
yunqiao:
displayName: Yunqiao OpenAI
apiKeyEnv: OPENAI_API_KEY
api: openai-completions
baseURL: https://ai.aiyq.cloud/v1
models:
- id: gpt-5.6-sol
name: GPT-5.6 Sol
contextWindow: 131072
maxTokens: 8192
provider: yunqiao
model: gpt-5.6-sol
llm-pi-ai:
providers:
yunqiao:
displayName: Yunqiao OpenAI
apiKeyEnv: OPENAI_API_KEY
api: openai-completions
baseURL: https://ai.aiyq.cloud/v1
models:
- id: gpt-5.6-sol
name: GPT-5.6 Sol
contextWindow: 131072
maxTokens: 8192
字段规则provider 必须匹配 providers 下的键；model 必须匹配 models[].id；apiKeyEnv 只写变量名；api 使用 openai-completions；baseURL 和模型 ID 按服务商实际限制填写。
3. 多模型与 DeepSeek 官方 API
同一 provider 可在 models 下添加多个模型；未列出的模型不会出现在 Harness 选择列表中。
models:
- id: gpt-5.6-sol
name: GPT-5.6 Sol
- id: gpt-5.4
name: GPT-5.4
agent-default-model:
provider: deepseek-official
model: deepseek-chat
llm-deepseek:
apiKeyEnv: DEEPSEEK_API_KEY
baseURL: https://api.deepseek.com
- id: gpt-5.6-sol
name: GPT-5.6 Sol
- id: gpt-5.4
name: GPT-5.4
agent-default-model:
provider: deepseek-official
model: deepseek-chat
llm-deepseek:
apiKeyEnv: DEEPSEEK_API_KEY
baseURL: https://api.deepseek.com
官方 DeepSeek 路由与 OpenAI 兼容中转站是两条不同配置：前者使用 llm-deepseek / deepseek-official，后者使用 llm-pi-ai / 自定义 provider。
4. 重启与验证
launchctl kickstart -k gui/$(id -u)/ai.deepseek-harness.web
launchctl print gui/$(id -u)/ai.deepseek-harness.web | rg 'state =|pid =|last exit code'
curl --fail --silent --show-error -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8787/
launchctl print gui/$(id -u)/ai.deepseek-harness.web | rg 'state =|pid =|last exit code'
curl --fail --silent --show-error -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8787/
页面正常应返回 HTTP 200。也可以先独立验证上游：
api_key=$(awk -F': ' '$1 == "OPENAI_API_KEY" {print $2}' ~/.dsh/.credentials.yaml)
curl --fail --silent --show-error --header "Authorization: Bearer $api_key" https://ai.aiyq.cloud/v1/models
curl --fail --silent --show-error --header "Authorization: Bearer $api_key" https://ai.aiyq.cloud/v1/models
不要把包含真实 Key 的命令输出粘贴到聊天、工单或日志中。
5. 常见错误
401 / 403检查 Key、有效期、模型权限，以及 apiKeyEnv 是否和凭据变量一致。
404检查 baseURL、模型 ID 和协议类型，不要随意拼接路径。
默认模型没变化确认 provider/model 与 providers 键和 models[].id 完全一致，然后重启 Web 服务。
Key 不生效确认 credentials 是顶层 YAML、权限为 600，apiKeyEnv 只写变量名。