# 主流智能体中文开放社区 · allagent.app（完整版）

生成时间: 2026-11-06T03:57:26.715Z
文档数: 16

---

# 配好了却仍然走官方端点

来源: https://allagent.app/errors/err-401-auth-token.html

## 原因

Claude Code 会同时读取 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN`。如果系统环境或旧的配置里还留着官方 key，它会优先用那一个，于是你的 Base URL 形同虚设，表现为"改了配置没生效"。

## 解法

1. 在配置里把 `ANTHROPIC_API_KEY` 显式置空字符串，不要删掉这个键
2. 只用 `ANTHROPIC_AUTH_TOKEN`（Bearer 头），它与 `ANTHROPIC_API_KEY`（x-api-key 头）不要同时给值
3. 改完必须重启 Claude Code，环境变量只在进程启动时读取一次，运行中改不会生效

---

# 接入后立刻返回 404

来源: https://allagent.app/errors/err-404-base-url-prefix.html

## 原因

两个客户端拼接路径的规则相反，这是最高频的一个坑：

- **Claude Code** 自己拼 `<base>/v1/messages`，所以 Base URL **不带** `/v1`；
- **Codex CLI** 自己拼 `<base>/responses`，所以 `base_url` **必须带** `/v1`。

反了就是 404，而且报错信息不提示路径问题。

## 解法

1. Claude Code：`ANTHROPIC_BASE_URL=https://api.example.com`（无 `/v1`）
2. Codex CLI：`base_url = "https://api.example.com/v1"`
3. 先用 curl 验证再启动客户端：`curl -X POST <base>/v1/messages -H "content-type: application/json" -d '{"model":"...","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'`

---

# 并发稍高就被限流

来源: https://allagent.app/errors/err-429-rate-limit.html

## 原因

两个原因叠加：前缀缓存没开（每次请求都把整段上下文重算一遍），以及客户端遇到 429 直接重打、没有指数退避。

## 解法

1. 在接入源侧开 Prompt 缓存，并确认中转层**原样透传** `cache_control` 标记，中转层一旦改写请求体，缓存全部失效，成本反而更高
2. 看返回里的 `cache_read_input_tokens`，为 0 就说明缓存没生效
3. 客户端侧配指数退避重试，Codex 用 `request_max_retries` / `stream_max_retries`
4. 并发确实超了，就降并发而不是加并发

---

# 客户端连不上接入点

来源: https://allagent.app/errors/err-connection-refused.html

## 原因

Agent 本身没问题，是它到接入点的这条路上断了：系统代理没被终端程序继承、端点域名在当前网络不可达、或者证书链不被信任。

## 解法

1. 先用 curl 验证端点本身通不通：`curl -I https://api.example.com/v1/models`
2. 检查系统代理是否配置，并在终端里显式导出 `HTTPS_PROXY` / `HTTP_PROXY`
3. 看证书链，必要时把企业根证书装进系统信任库
4. 仍然不通就换镜像线路，这也是整合包预置国内镜像的原因

---

# MCP 工具列表是空的

来源: https://allagent.app/errors/err-mcp-tool-search-disabled.html

## 原因

Claude Code 在检测到接入点不是官方地址时，会把 MCP 的 tool search 关掉以避免行为异常。MCP Server 本身装好了、也注册成功，但工具检索不到。

## 解法

1. 在配置里加 `ENABLE_TOOL_SEARCH=true`
2. 确认 MCP Server 的启动命令在 PATH 里能被找到
3. 确认工具 schema 里没有官方客户端才支持的字段

---

# 报模型不存在

来源: https://allagent.app/errors/err-model-not-found.html

## 原因

Claude Code 与 Codex 发出的都是 Anthropic / OpenAI 的官方模型别名。接入点如果只认自己那套命名，别名就会找不到，表现为后台任务报错，但手动发请求又是好的。

## 解法

1. **首选**：在接入点侧接受官方别名并内部映射，这样客户端零配置
2. **次选**：用 `ANTHROPIC_DEFAULT_OPUS_MODEL` / `_SONNET_MODEL` / `_HAIKU_MODEL` 指定实际模型名
3. Codex 侧确认 `model` 的值与接入点完全一致，大小写敏感
4. 先 curl 指定模型名验证通路，再怀疑客户端

---

# 装到一半权限被拒

来源: https://allagent.app/errors/err-npm-eacces-path.html

## 原因

Windows 用户目录含中文或空格时，npm 及其生命周期脚本会在创建目录这一步报权限错。这不是权限不够，是路径本身的问题。

## 解法

1. **不要装到用户目录**，改用固定的纯英文短路径，例如 `C:\AgentHub\packages`
2. 用 `--prefix` 指定安装前缀，避开系统 npm 目录
3. 路径别超过 200 字符，Windows 有 260 的上限
4. 这一步做完，环境问题就少了一大半，整合包预置的沙箱就是为它准备的

---

# Claude Code

来源: https://allagent.app/agents/claude-code.html

# Claude Code 接入配置

> 来源：Claude Code 官方环境变量文档。更新日期：2026-11-05。

## 安装

```bash
npm install -g @anthropic-ai/claude-code
```

## 接入点配置

Claude Code 通过环境变量切换接入地址，写在 `~/.claude/settings.json`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "ANTHROPIC_API_KEY": ""
  }
}
```

### 三个高频坑

1. **Base URL 不要带 `/v1`**。Claude Code 自己拼接 `/v1/messages`，带了会 404。
2. **`ANTHROPIC_API_KEY` 要显式置空**。系统里若残留官方 key，请求会静默走官方端点。
3. **用 `ANTHROPIC_AUTH_TOKEN`**，不要用 `ANTHROPIC_API_KEY`；两者同时存在会冲突。

### 其他可用变量

| 变量 | 作用 |
|---|---|
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 指定 Opus 档实际使用的模型名 |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 指定 Sonnet 档实际模型名 |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 指定 Haiku 档实际模型名 |
| `ENABLE_TOOL_SEARCH` | 非官方接入点下需设为 `true` 开启工具检索 |

## 模型名映射

Claude Code 使用 Anthropic 官方别名。若接入点不暴露同名模型，后台任务会报 model not found。解决方式：在接入点侧接受官方别名并内部映射，或用上表的 `ANTHROPIC_DEFAULT_*_MODEL` 指定实际模型名。

## 已知问题

| 现象 | 处理 |
|---|---|
| 配好接入点后仍然 404 | Base URL 不能带 `/v1`，客户端自己拼 `/v1/messages` |
| 改了配置不生效 | 环境变量只在进程启动时读一次，改完必须重启 |
| 仍然走官方端点 | 系统里残留的 `ANTHROPIC_API_KEY` 抢先被读，把它显式置空 |
| 后台任务报 model not found | 接入点没有同名模型，用 `ANTHROPIC_DEFAULT_*_MODEL` 指定实际模型 |

---

# Codex CLI

来源: https://allagent.app/agents/codex.html

# Codex CLI 接入配置

> 来源：Codex CLI 官方配置文档。更新日期：2026-11-05。

## 安装

```bash
npm install -g @openai/codex
```

## 自定义接入点

配置文件 `~/.codex/config.toml`：

```toml
model = "your-model-id"
model_provider = "community"

[model_providers.community]
name = "Community Gateway"
base_url = "https://api.example.com/v1"
env_key = "COMMUNITY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
```

### 五个高频坑

1. **base_url 要带 `/v1`**，与 Claude Code 相反（它自己拼 `/responses`）。
2. **`wire_api` 新版只支持 `"responses"`**。填 `"chat"` 会报 `wire_api is no longer supported`。
3. **`env_key` 写的是环境变量名**，不是 key 本身。
4. **`model_provider` 不能用保留名**（`openai` / `ollama`）。
5. **密钥前缀非 OpenAI 时**需要 `requires_openai_auth = false`。

## 配置优先级

CLI `-c` 参数 > 项目级 `.codex/config.toml` > `--profile` > 用户级 `~/.codex/config.toml` > 托管默认。

## 已知问题

| 现象 | 处理 |
|---|---|
| 配好后 404 | `base_url` 必须带 `/v1`，与 Claude Code 相反 |
| 报 wire_api 不受支持 | 新版只接受 `responses`，填 `chat` 会直接报错 |
| 密钥读不到 | `env_key` 写的是环境变量名，不是 key 本身 |
| provider 名冲突 | `model_provider` 不能用 `openai` / `ollama` 这类保留名 |
| 认证失败 | 密钥前缀不是 OpenAI 时需要 `requires_openai_auth = false` |

---

# Hermes Agent

来源: https://allagent.app/agents/hermes.html

## 它能做什么

- 长期记忆：跨会话检索历史，保存用户偏好
- 技能系统：按 `agentskills.io` 开放格式组织，Agent 自己创建并改进技能
- MCP：连接任意 MCP Server，并按需要过滤工具
- 消息网关：把同一个进程接到 Telegram、Discord、Slack、WhatsApp、飞书、企业微信、QQ 等平台
- 定时任务：用 cron 做日报、备份、巡检
- 七种终端后端：本地、Docker、SSH、Modal、Daytona 等

## 中文环境要注意什么

1. **需要 Python 与 Git**。Windows 上装依赖最多的一步，也是报错最多的地方
2. 原生 Windows 安装目录是 `%LOCALAPPDATA%\hermes`，WSL2 与 Linux 是 `~/.hermes`
3. 安装脚本一行命令：`iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)`，依赖 Python、Node.js、npm、ripgrep、FFmpeg
4. 别把上游和中文社区 fork 装进同一个 Python 环境

## 常用命令

```bash
hermes setup        # 完整设置向导
hermes model        # 选择模型服务商
hermes tools        # 配置启用的工具
hermes config set   # 设置单个配置项
hermes doctor       # 诊断常见问题
hermes update       # 更新
```

## 已知问题

| 现象 | 处理 |
|---|---|
| 提示「记忆满了」 | 实际是提示词注入额度耗尽，减少注入量或清理历史 |
| 技能装不上 | 确认 Git 在 PATH 里，且有写权限 |
| 网关连不上 | 检查 `hermes gateway` 是否在跑、端口是否被占用 |

---

# OpenClaw

来源: https://allagent.app/agents/openclaw.html

# OpenClaw 安装与配置

> 来源：OpenClaw 官方仓库。更新日期：2026-11-05。

## 安装

```bash
# 方式一：官方脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 方式二：npm
npm install -g openclaw@latest --allow-scripts=openclaw
```

## 模型接入

OpenClaw 的模型是可插拔 provider，切换 provider 不影响其他配置。

## 技能与 MCP

- Skills 采用 `SKILL.md` 约定；
- MCP Server 通过 OpenClaw 自身的配置声明。

## 安全提示

OpenClaw 官方仓库公开的安全公告较多，host exec 默认无确认、沙箱默认关闭。**在生产或含敏感数据的环境使用时，请显式开启命令确认与沙箱隔离，并只安装经过审查的技能。**

## 已知问题

| 现象 | 处理 |
|---|---|
| 安装时报 EACCES | 安装目录落在中文用户名下，改用 `--prefix` 指向纯英文短路径 |
| 命令找不到 | `--prefix` 的 shim 生成在目录根部，PATH 要加那个目录，不是 `node_modules/.bin` |
| 技能装不上 | 检查 Git 是否可用、目标目录是否可写 |
| 网关被外部访问 | 强制监听 loopback，不要绑定公网地址 |

---

# 缓存没开，成本翻倍

来源: https://allagent.app/daily/2026-11-03-cache-cost.html

# 缓存没开，成本翻倍

一位群友的账单是预期的三倍。Agent 侧配置没问题，最后定位在中转层。

## 发生了什么

Claude Code 靠 `cache_control` 标记让前缀缓存生效。中转层如果改写了请求体、加了字段、或者换了模型名，缓存就全部失效，每一次请求都把整段上下文重新算一遍。

表现是隐蔽的：功能一切正常，只有账单变高。

## 怎么看出来

看返回里的 `cache_read_input_tokens`。这个值是 0，缓存就没生效。

## 修法

中转层原样透传 `cache_control`、`system`、`tools` 这几块，字节级不动；只允许替换模型名。加一个断言：透传前后请求体哈希必须一致（模型名除外）。

**今天更新**：报错字典的 429 条目补上了缓存这一层排查顺序。

---

# 中文路径把 npm 拦在门外

来源: https://allagent.app/daily/2026-11-04-chinese-path.html

# 中文路径把 npm 拦在门外

今天遇到三次 `npm error code EACCES`，三次都是同一个原因：安装目录落在了 `C:\Users\中文名\` 下面。

这不是权限不够，是路径本身的问题。

## 30 秒修好

不要装到用户目录。改用一个固定的纯英文短路径：

```bash
npm i -g --prefix "C:\AgentHub\packages" openclaw@latest --allow-scripts=openclaw
```

注意 `--prefix` 指向的目录里会直接生成可执行文件（`openclaw.cmd`），所以往 PATH 里加的是这个目录本身，不是它下面的 `node_modules/.bin`。

## 顺带一条

路径超过 200 字符也会出问题，Windows 有 260 的上限。

**今天更新**：安装适配文档补了「沙箱路径规划」一节，四个 Agent 的安装路径统一到同一套。

---

# 一个 /v1，两个答案

来源: https://allagent.app/daily/2026-11-05-base-url.html

# 一个 /v1，两个答案

今天群里最集中的一个问题是「配好了还是 404」。答案藏在两个客户端拼路径的规则里：

- Claude Code 自己拼 `<base>/v1/messages`，Base URL **不带** `/v1`
- Codex CLI 自己拼 `<base>/responses`，`base_url` **必须带** `/v1`

写反了就是 404，而且报错信息完全不提路径。

## 更隐蔽的一个

如果系统里还留着 `ANTHROPIC_API_KEY`，它会抢先被读，你的 Base URL 形同虚设，表现为"改了配置没生效"。把它显式置空，只留 `ANTHROPIC_AUTH_TOKEN`。

## 还有一条

环境变量只在进程启动时读取一次。改完配置不重启，等于没改。

**今天更新**：报错字典新增「接入后立刻返回 404」与「配好了却仍然走官方端点」两条，均附可直接复制的配置。

---

# 中文 Agent 知识库

来源: https://allagent.app/docs/index.html

# 中文 Agent 知识库

这里收录主流 Agent 在中文网络环境下的安装、配置与排错方法。

## 覆盖的 Agent

- [Claude Code](./agents/claude-code.md)
- [Codex CLI](./agents/codex.md)
- [OpenClaw](./agents/openclaw.md)

## 常见问题

- [安装与国内网络适配](./guides/installation.md)
- [报错字典](./guides/errors.md)

---

# 国内网络环境安装适配

来源: https://allagent.app/docs/installation.html

# 国内网络环境安装适配

> 更新日期：2026-11-05。

## 三个最常见的失败原因

### 1. 中文用户名与空格路径

Windows 用户目录含中文或空格时，npm 与部分 Python 包的安装脚本会失败。

**处理方式**：不要在用户目录下安装，改用固定纯英文短路径（例如 `C:\AgentHub`），并保持路径长度低于 200 字符。

### 2. 缺 Node / Python / Git

**处理方式**：用便携版运行时，不修改系统环境：

- npm 全局安装使用 `--prefix` 指定隔离目录；
- 需要注意，可执行文件的 shim 生成在 **`--prefix` 指定的目录根部**，不是 `node_modules/.bin`，注入 PATH 时必须指向 prefix 根目录。

### 3. PowerShell 执行策略

下载的 `.ps1` 安装脚本在 `Restricted` 策略下会被拦截。

**处理方式**：由程序直接调用可执行文件完成安装，不经过 PowerShell 脚本；确需调用时使用进程级 `-ExecutionPolicy Bypass`，不修改系统级策略。

---