环境变量 (Archive)

Archived original-language source from the legacy CrabClaw docs. This page is intentionally not machine-translated.

[!NOTE] 本文档已更新以适配 Rust CLI + Go Gateway 混合架构。

Crab Claw（蟹爪）从多个来源获取环境变量。规则是不覆盖已有的值。 当前环境变量名和状态目录仍保留 CRABCLAW_* / ~/.crabclaw 兼容标识。

优先级（从高到低）

1. 进程环境 — Gateway 进程从父 shell / 守护进程继承的环境变量。
2. 当前工作目录下的 .env — dotenv 默认行为，不覆盖已有值。
3. 全局 .env — 位于 ~/.crabclaw/.env（即 $CRABCLAW_STATE_DIR/.env），不覆盖已有值。
4. 配置文件 env 块 — 在 ~/.crabclaw/crabclaw.json 中，仅当环境变量缺失时应用。
5. 可选的登录 shell 导入 — 通过 env.shellEnv.enabled 或 CRABCLAW_LOAD_SHELL_ENV=1 启用，仅对缺失的期望键生效。

如果配置文件完全不存在，则跳过第 4 步；Shell 导入仍在启用时运行。

配置文件 env 块

两种等效方式设置内联环境变量（均不覆盖已有值）：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Shell 环境导入

env.shellEnv 运行您的登录 shell 并仅导入缺失的期望键：

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

等效环境变量：

• CRABCLAW_LOAD_SHELL_ENV=1
• CRABCLAW_SHELL_ENV_TIMEOUT_MS=15000

配置中的环境变量替换

可以在配置字符串值中使用 ${VAR_NAME} 语法直接引用环境变量：

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

详见 配置：环境变量替换。

路径相关环境变量

CRABCLAW_HOME

设置后，CRABCLAW_HOME 将替代系统主目录（$HOME）用于所有内部路径解析。这使得无头服务账户可以实现完整的文件系统隔离。

优先级： CRABCLAW_HOME > $HOME > USERPROFILE > 系统默认主目录

示例（macOS LaunchDaemon）：

<key>EnvironmentVariables</key>
<dict>
  <key>CRABCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

<key>EnvironmentVariables</key>
<dict>
  <key>CRABCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

CRABCLAW_HOME 也可以设置为带波浪号的路径（如 ~/svc），使用前会通过 $HOME 展开。

相关文档

• Gateway 配置
• FAQ：环境变量和 .env 加载
• 模型概览