Claude Code — 完整开发指南

通过 Hermes 终端将编码任务委托给 Claude Code（Anthropic 的自主编码 Agent CLI）。Claude Code v2.x 可以自主读取文件、编写代码、运行 Shell 命令、生成子 Agent 以及管理 Git 工作流程。

前置条件

• 安装：npm install -g @anthropic-ai/claude-code
• 认证：运行 claude 进行一次登录（Pro/Max 用户使用浏览器 OAuth，或设置 ANTHROPIC_API_KEY）
• 控制台认证：claude auth login --console（API Key 计费模式）
• SSO 认证：claude auth login --sso（企业版）
• 查看状态：claude auth status（JSON 格式）或 claude auth status --text（人类可读）
• 健康检查：claude doctor — 检查自动更新器和安装健康状态
• 版本检查：claude --version（需要 v2.x+）
• 更新：claude update 或 claude upgrade

两种编排模式

Hermes 与 Claude Code 有两种完全不同的交互方式。根据任务选择。

模式1：Print 模式（-p）— 非交互式（推荐用于大多数任务）

Print 模式运行一次性任务，返回结果后退出。不需要 PTY，没有交互式提示。这是最干净的集成路径。

terminal(command="claude -p '为 src/ 中的所有 API 调用添加错误处理' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)

何时使用 Print 模式：

• 一次性编码任务（修复 Bug、添加功能、重构）
• CI/CD 自动化和脚本编写
• 使用 --json-schema 进行结构化数据提取
• 管道输入处理（cat file | claude -p "分析这个文件"）
• 任何不需要多轮对话的任务

Print 模式跳过所有交互式对话框 — 没有工作区信任提示，没有权限确认。这使得它非常适合自动化。

模式2：通过 tmux 的交互式 PTY — 多轮会话

交互式模式提供一个完整的对话式 REPL，你可以发送后续提示、使用斜杠命令，并实时观察 Claude 工作。需要 tmux 编排。

# 启动一个 tmux 会话
terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")

# 在内部启动 Claude Code
terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")

# 等待启动，然后发送任务
# （大约等待 3-5 秒欢迎界面）
terminal(command="sleep 5 && tmux send-keys -t claude-work '将认证模块重构为使用 JWT 令牌' Enter")

# 通过捕获面板监控进度
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")

# 发送后续任务
terminal(command="tmux send-keys -t claude-work '现在为新的 JWT 代码添加单元测试' Enter")

# 完成后退出
terminal(command="tmux send-keys -t claude-work '/exit' Enter")

何时使用交互式模式：

• 多轮迭代工作（重构 → 审查 → 修复 → 测试周期）
• 需要人机协同决策的任务
• 探索性编码会话
• 需要使用 Claude 的斜杠命令时（/compact、/review、/model）

PTY 对话框处理（交互式模式关键）

Claude Code 在首次启动时会出现最多两个确认对话框。你必须通过 tmux send-keys 处理它们：

对话框1：工作区信任（首次访问目录）

❯ 1. 是的，我信任这个文件夹    ← 默认选项（直接按 Enter）
  2. 不，退出

处理：tmux send-keys -t <session> Enter — 默认选择正确。

对话框2：绕过权限警告（仅在启用 --dangerously-skip-permissions 时出现）

❯ 1. 不，退出              ← 默认（错误选项！）
  2. 是的，我接受

处理：必须先向下导航，再按 Enter：

tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter

稳健的对话框处理模式

# 使用权限绕过启动
terminal(command="tmux send-keys -t claude-work 'claude --dangerously-skip-permissions "你的任务"' Enter")

# 处理信任对话框（Enter 选择默认的"是"）
terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")

# 处理权限对话框（先向下再 Enter 选择"是的，我接受"）
terminal(command="sleep 3 && tmux send-keys -t claude-work Down && sleep 0.3 && tmux send-keys -t claude-work Enter")

# 现在等待 Claude 工作
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")

注意：在首次接受某个目录的信任后，信任对话框不会再次出现。只有权限对话框会在每次使用 --dangerously-skip-permissions 时重复出现。

CLI 子命令

Print 模式深入

结构化 JSON 输出

terminal(command="claude -p '分析 auth.py 的安全问题' --output-format json --max-turns 5", workdir="/project", timeout=120)

返回包含以下字段的 JSON 对象：

{
  "type": "result",
  "subtype": "success",
  "result": "分析文本...",
  "session_id": "75e2167f-...",
  "num_turns": 3,
  "total_cost_usd": 0.0787,
  "duration_ms": 10276,
  "stop_reason": "end_turn",
  "terminal_reason": "completed",
  "usage": { "input_tokens": 5, "output_tokens": 603, ... },
  "modelUsage": { "claude-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
}

关键字段：session_id 用于恢复会话，num_turns 表示 Agent 循环次数，total_cost_usd 用于支出跟踪，subtype 用于成功/错误检测（success、error_max_turns、error_budget）。

流式 JSON 输出

如需实时 Token 流，使用带 --verbose 的 stream-json：

terminal(command="claude -p '写一段摘要' --output-format stream-json --verbose --include-partial-messages", timeout=60)

返回按换行符分隔的 JSON 事件。使用 jq 过滤实时文本：

claude -p "解释 X 的概念" --output-format stream-json --verbose --include-partial-messages | 
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

流事件包括 system/api_retry，包含 attempt、max_retries 和 error 字段（例如 rate_limit、billing_error）。

双向流式传输

如需实时输入和输出流式传输：

claude -p "任务描述" --input-format stream-json --output-format stream-json --replay-user-messages

--replay-user-messages 在 stdout 上重新输出用户消息，用于确认。

管道输入

# 通过管道传输文件进行分析
terminal(command="cat src/auth.py | claude -p '审查此代码中的 Bug' --max-turns 1", timeout=60)

# 通过管道传输多个文件
terminal(command="cat src/*.py | claude -p '查找所有 TODO 注释' --max-turns 1", timeout=60)

# 通过管道传输命令输出
terminal(command="git diff HEAD~3 | claude -p '总结这些变更' --max-turns 1", timeout=60)

用于结构化提取的 JSON Schema

terminal(command="claude -p '列出 src/ 中的所有函数' --output-format json --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' --max-turns 5", workdir="/project", timeout=90)

从 JSON 结果中解析 structured_output 字段。Claude 在返回前会根据 Schema 验证输出。

会话延续

# 开始一个任务
terminal(command="claude -p '开始重构数据库层' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)

# 使用会话 ID 恢复
terminal(command="claude -p '继续并添加连接池' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)["session_id"])') --max-turns 5", workdir="/project", timeout=120)

# 或恢复同一目录中最近的会话
terminal(command="claude -p '上次做了什么？' --continue --max-turns 1", workdir="/project", timeout=30)

# Fork 会话（新建 ID，保留历史）
terminal(command="claude -p '尝试不同的方法' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)

CI/脚本的 Bare 模式

terminal(command="claude --bare -p '运行所有测试并报告失败项' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)

--bare 跳过钩子、插件、MCP 发现和 CLAUDE.md 加载。启动最快。需要 ANTHROPIC_API_KEY（跳过 OAuth）。

在 bare 模式下选择性加载上下文：

过载时的备用模型

terminal(command="claude -p '任务描述' --fallback-model haiku --max-turns 5", timeout=90)

当默认模型过载时，自动回退到指定的备用模型（仅限 print 模式）。

完整 CLI 标志参考

会话与环境

模型与性能

权限与安全

输出与输入格式

系统提示与上下文

调试

Agent 团队

--allowedTools / --disallowedTools 的工具名称语法

Read                    # 所有文件读取
Edit                    # 文件编辑（已有文件）
Write                   # 文件创建（新文件）
Bash                    # 所有 Shell 命令
Bash(git *)             # 仅 Git 命令
Bash(git commit *)      # 仅 Git commit 命令
Bash(npm run lint:*)    # 通配符模式匹配
WebSearch               # 网页搜索能力
WebFetch                # 网页抓取
mcp__<服务器>__<工具>     # 特定的 MCP 工具

设置与配置

设置优先级（从高到低）

1. CLI 标志 — 覆盖一切
2. 本地项目：.claude/settings.local.json（个人，被 gitignore）
3. 项目：.claude/settings.json（团队共享，被 Git 跟踪）
4. 用户：~/.claude/settings.json（全局）

设置中的权限配置

{
  "permissions": {
    "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
    "ask": ["Write(*.ts)", "Bash(git push*)"],
    "deny": ["Read(.env)", "Bash(rm -rf *)"]
  }
}

记忆文件（CLAUDE.md）层级

1. 全局：~/.claude/CLAUDE.md — 适用于所有项目
2. 项目：./CLAUDE.md — 项目特定上下文（被 Git 跟踪）
3. 本地：.claude/CLAUDE.local.md — 个人项目覆盖（被 gitignore）

在交互模式中使用 # 前缀快速添加到记忆：# 始终使用 2 空格缩进。

交互式会话：斜杠命令

会话与上下文

开发与审查

配置与工具

自定义斜杠命令

创建 .claude/commands/<名称>.md（项目共享）或 ~/.claude/commands/<名称>.md（个人）：

# .claude/commands/deploy.md
运行部署流程：
1. 运行所有测试
2. 构建 Docker 镜像
3. 推送到镜像仓库
4. 更新 $ARGUMENTS 环境（默认：staging）

使用方式：/deploy production — $ARGUMENTS 会被替换为用户输入的内容。

技能（自然语言调用）

与需要手动调用的斜杠命令不同，.claude/skills/ 中的技能是 Markdown 指南，当任务匹配时 Claude 通过自然语言自动调用：

# .claude/skills/database-migration.md
当被问到创建或修改数据库迁移时：
1. 使用 Alembic 生成迁移
2. 始终创建回滚函数
3. 在本地数据库副本上测试迁移

交互式会话：键盘快捷键

通用控制

模式切换

多行输入

输入前缀

专业技巧：「ultrathink」

在提示中使用「ultrathink」关键词以在特定轮次中获得最大推理努力。这会触发最深层的思考模式，无论当前的 /effort 设置如何。

PR 审查模式

快速审查（Print 模式）

terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p '审查此差异中的 Bug、安全问题和风格问题。请做到全面。' --max-turns 1", timeout=60)

深度审查（交互式 + Worktree）

terminal(command="tmux new-session -d -s review -x 140 -y 40")
terminal(command="tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter")
terminal(command="sleep 5 && tmux send-keys -t review Enter")  # 信任对话框
terminal(command="sleep 2 && tmux send-keys -t review '审查与 main 分支的所有差异。检查 Bug、安全问题、竞态条件和缺失的测试。' Enter")
terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")

按编号进行 PR 审查

terminal(command="claude -p '全面审查此 PR' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)

带 tmux 的 Claude Worktree

terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")

在 .claude/worktrees/feature-x 创建隔离的 Git Worktree，同时创建一个 tmux 会话。在可用时使用 iTerm2 原生面板，添加 --tmux=classic 使用传统 tmux。

并行运行多个 Claude 实例

同时运行多个独立的 Claude 任务：

# 任务1：修复后端
terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p "修复 src/auth.py 中的认证 Bug" --allowedTools "Read,Edit" --max-turns 10' Enter")

# 任务2：编写测试
terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p "为 API 端点编写集成测试" --allowedTools "Read,Write,Bash" --max-turns 15' Enter")

# 任务3：更新文档
terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p "使用新的 API 端点更新 README.md" --allowedTools "Read,Edit" --max-turns 5' Enter")

# 监控所有任务
terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")

CLAUDE.md — 项目上下文文件

Claude Code 自动从项目根目录加载 CLAUDE.md。用它来持久化项目上下文：

# 项目：我的 API

## 架构
- FastAPI 后端，SQLAlchemy ORM
- PostgreSQL 数据库，Redis 缓存
- pytest 测试，覆盖率目标 90%

## 关键命令
- `make test` — 运行完整测试套件
- `make lint` — ruff + mypy
- `make dev` — 在 :8000 启动开发服务器

## 代码规范
- 所有公共函数使用类型提示
- 使用 Google 风格的文档字符串
- YAML 使用 2 空格缩进，Python 使用 4 空格
- 禁止通配符导入

要具体。不要写「写出好代码」，而是用「JS 使用 2 空格缩进」或「测试文件使用 .test.ts 后缀」。具体的指令能节省纠正周期。

规则目录（模块化 CLAUDE.md）

对于有很多规则的项目，使用规则目录代替一个庞大的 CLAUDE.md：

• 项目规则：.claude/rules/*.md — 团队共享，被 Git 跟踪
• 用户规则：~/.claude/rules/*.md — 个人，全局

规则目录中的每个 .md 文件都会作为额外上下文加载。这比把所有内容塞进一个 CLAUDE.md 更清晰。

自动记忆

Claude 自动学习项目上下文并存储在 ~/.claude/projects/<项目>/memory/ 中。

• 限制：每个项目 25KB 或 200 行
• 这与 CLAUDE.md 分开 — 是 Claude 自己对项目的笔记，跨会话累积

自定义子 Agent

在 .claude/agents/（项目）、~/.claude/agents/（个人）或通过 --agents CLI 标志（会话）定义专门的 Agent：

Agent 位置优先级

1. .claude/agents/ — 项目级别，团队共享
2. --agents CLI 标志 — 会话特定，动态
3. ~/.claude/agents/ — 用户级别，个人

创建 Agent

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 安全专注的代码审查
model: opus
tools: [Read, Bash]
---
你是一名资深安全工程师。审查代码时关注：
- 注入漏洞（SQL、XSS、命令注入）
- 认证/授权缺陷
- 代码中的密钥
- 不安全的反序列化

通过以下方式调用：@security-reviewer review the auth module

通过 CLI 动态定义 Agent

terminal(command="claude --agents '{"reviewer": {"description": "审查代码", "prompt": "你是一个专注于性能的代码审查者"}}' -p '使用 @reviewer 来检查 auth.py'", timeout=120)

Claude 可以编排多个 Agent：「使用 @db-expert 优化查询，然后使用 @security 审计变更。」

钩子 — 事件自动化

在 .claude/settings.json（项目）或 ~/.claude/settings.json（全局）中配置：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write(*.py)",
      "hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "if echo "$CLAUDE_TOOL_INPUT" | grep -q 'rm -rf'; then echo '已拦截！' && exit 2; fi"}]
    }],
    "Stop": [{
      "hooks": [{"type": "command", "command": "echo 'Claude 完成了一条响应' >> /tmp/claude-activity.log"}]
    }]
  }
}

全部 8 种钩子类型

钩子环境变量

安全钩子示例

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{"type": "command", "command": "if echo "$CLAUDE_TOOL_INPUT" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo '危险命令已拦截！' && exit 2; fi"}]
  }]
}

MCP 集成

为数据库、API 和服务添加外部工具服务器：

# GitHub 集成
terminal(command="claude mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)

# PostgreSQL 查询
terminal(command="claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)

# Puppeteer Web 测试
terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)

MCP 作用域

Print/CI 模式中的 MCP

terminal(command="claude --bare -p '查询数据库' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)

--strict-mcp-config 忽略除 --mcp-config 之外的所有 MCP 服务器。

在对话中引用 MCP 资源：@github:issue://123

MCP 限制与调优

• 工具描述：每个服务器 2KB 上限（工具描述和服务器指令）
• 结果大小：默认有上限；使用 maxResultSizeChars 注释允许最多 500K 字符用于大输出
• 输出 Token：export MAX_MCP_OUTPUT_TOKENS=50000 — 限制 MCP 服务器输出，防止上下文溢出
• 传输协议：stdio（本地进程）、http（远程）、sse（服务器推送事件）

监控交互式会话

读取 TUI 状态

# 定期捕获以检查 Claude 是在工作还是在等待输入
terminal(command="tmux capture-pane -t dev -p -S -10")

关注这些指示器：

• ❯ 在底部 = 等待你的输入（Claude 已完成或正在提问）
• ● 行 = Claude 正在主动使用工具（读取、写入、运行命令）
• ⏵⏵ bypass permissions on = 状态栏显示权限模式
• ◐ medium · /effort = 状态栏中的当前努力级别
• ctrl+o to expand = 工具输出被截断（可在交互模式下展开）

上下文窗口健康

在交互模式中使用 /context 查看上下文使用情况的彩色网格。关键阈值：

• < 70% — 正常运行，全精度
• 70-85% — 精度开始下降，考虑 /compact
• > 85% — 幻觉风险显著增加，使用 /compact 或 /clear

环境变量

成本与性能技巧

1. 使用 --max-turns 在 print 模式中防止失控循环。大多数任务从 5-10 开始。
2. 使用 --max-budget-usd 设置成本上限。注意：系统提示缓存创建最低约 $0.05。
3. 使用 --effort low 处理简单任务（更快、更便宜）。high 或 max 用于复杂推理。
4. CI/脚本使用 --bare 跳过插件/钩子发现的开销。
5. 使用 --allowedTools 限制到仅需要的工具（例如审查时仅 Read）。
6. 交互式会话中在上下文变大时使用 /compact。
7. 管道输入代替让 Claude 读取文件，当你只需要分析已知内容时。
8. 使用 --model haiku 处理简单任务（更便宜），--model opus 用于复杂的多步骤工作。
9. print 模式中使用 --fallback-model haiku 优雅处理模型过载。
10. 不同任务开启新会话 — 会话持续 5 小时；新鲜上下文更高效。
11. CI 中使用 --no-session-persistence 避免在磁盘上积累保存的会话。

常见陷阱与注意事项

1. 交互式模式必须使用 tmux — Claude Code 是一个完整的 TUI 应用。在 Hermes 终端中单独使用 pty=true 可以工作，但 tmux 提供了 capture-pane 用于监控和 send-keys 用于输入，这对编排至关重要。
2. --dangerously-skip-permissions 对话框默认为「不，退出」 — 你必须先按 Down 再按 Enter 来接受。Print 模式（-p）完全跳过此对话框。
3. --max-budget-usd 最低约 $0.05 — 仅系统提示缓存创建就需要这个成本。设置更低会立即报错。
4. --max-turns 仅限 print 模式 — 在交互式会话中被忽略。
5. Claude 可能使用 python 而不是 python3 — 在没有 python 符号链接的系统上，Claude 的 bash 命令首次尝试会失败但会自动修正。
6. 会话恢复需要同一目录 — --continue 找到当前工作目录最近的会话。
7. --json-schema 需要足够的 --max-turns — Claude 在生成结构化输出之前需要读取文件，这需要多轮交互。
8. 信任对话框每个目录只出现一次 — 仅首次，之后缓存。
9. 后台 tmux 会话持续存在 — 完成后始终使用 tmux kill-session -t <名称> 清理。
10. 斜杠命令（如 /commit）仅在交互模式中可用 — 在 -p 模式中，用自然语言描述任务。
11. --bare 跳过 OAuth — 需要 ANTHROPIC_API_KEY 环境变量或设置中的 apiKeyHelper。
12. 上下文退化是真实存在的 — 上下文窗口使用超过 70% 时 AI 输出质量明显下降。使用 /context 监控并主动 /compact。

Hermes Agent 使用规则

1. 优先为单一任务使用 print 模式（-p） — 更干净，无需对话框处理，结构化输出
2. 多轮交互式工作使用 tmux — 编排 TUI 的唯一可靠方法
3. 始终设置 workdir — 让 Claude 专注于正确的项目目录
4. print 模式中设置 --max-turns — 防止无限循环和失控成本
5. 监控 tmux 会话 — 使用 tmux capture-pane -t <会话> -p -S -50 检查进度
6. 寻找 ❯ 提示符 — 表示 Claude 正在等待输入（已完成或在提问）
7. 清理 tmux 会话 — 完成后终止它们以避免资源泄漏
8. 向用户报告结果 — 完成后总结 Claude 做了什么以及有什么变化
9. 不要终止慢速会话 — Claude 可能正在做多步骤工作；检查进度而不是直接杀掉
10. 使用 --allowedTools — 将能力限制到任务实际需要的范围

一、OpenClaw 智能体框架概述

OpenClaw 是国产开源智能体框架，支持快速构建 AI Agent 应用，提供技能开发、工具集成、多智能体协作等核心能力。

1. 核心特性

• 技能系统：通过 SKILL.md 定义技能，支持自动发现和加载
• 多通道集成：Telegram、Discord、微信、飞书等 10+ 通道
• 工具链：exec、web_fetch、cron、memory 等内置工具
• 多智能体：subagent 协作、session 管理
• 上下文管理：LCM 无损上下文压缩

二、安装部署

2. 安装步骤

1. 安装 OpenClaw CLI
2. 初始化工作区
3. 配置 API Key 和模型
4. 启动 Gateway 服务

三、最佳实践

• 技能描述要精确，避免歧义触发
• 利用 memory/ 目录持久化状态
• 善用 subagent 处理并行任务

一、OpenClaw 个人AI智能体部署

在本地电脑部署 OpenClaw 智能体，打造7x24小时在线的私人AI助手。

1. 部署方案

二、安装步骤

1. 安装 Node.js v22+
2. npm install -g openclaw
3. openclaw init 初始化工作区
4. 配置 .env 文件
5. openclaw gateway start

三、通道配置

支持 Telegram / Discord / 微信 / 飞书 / Web UI 等通道。

One API 是一个开源的 LLM API 管理与代理工具，支持多种大模型和服务商，提供丰富的管理功能。

一、支持多种大模型

1. OpenAI ChatGPT 系列模型（支持 Azure OpenAI API）
2. Anthropic Claude 系列模型（支持 AWS Claude）
3. Google PaLM2 / Gemini 系列模型
4. Mistral 系列模型
5. 字节跳动豆包大模型（火山引擎）
6. 百度文心一言系列模型
7. 阿里通义千问系列模型
8. 讯飞星火认知大模型
9. 智谱 ChatGLM 系列模型
10. 360 智脑
11. 腾讯混元大模型
12. Moonshot AI
13. 百川大模型
14. MINIMAX
15. Groq
16. Ollama
17. 零一万物
18. 阶跃星辰
19. Coze
20. Cohere
21. DeepSeek
22. Cloudflare Workers AI
23. DeepL
24. together.ai
25. novita.ai
26. 硅基流动 SiliconCloud
27. xAI

二、支持配置镜像以及众多第三方代理服务

三、支持通过负载均衡的方式访问多个渠道

四、支持 stream 模式，可以通过流式传输实现打字机效果

五、支持多机部署

六、支持令牌管理

设置令牌的过期时间、额度、允许的 IP 范围以及允许的模型访问。

七、支持兑换码管理

支持批量生成和导出兑换码，可使用兑换码为账户进行充值。

八、支持渠道管理，批量创建渠道

九、支持用户分组以及渠道分组

支持为不同分组设置不同的倍率。

十、支持渠道设置模型列表

十一、支持查看额度明细

十二、支持用户邀请奖励

十三、支持以美元为单位显示额度

十四、支持发布公告

设置充值链接，设置新用户初始额度。

十五、支持模型映射

重定向用户的请求模型，如无必要请不要设置，设置之后会导致请求体被重新构造而非直接透传，会导致部分还未正式支持的字段无法传递成功。

十六、支持失败自动重试

十七、支持绘图接口

十八、支持 Cloudflare AI Gateway

渠道设置的代理部分填写 https://gateway.ai.cloudflare.com/v1/ACCOUNT_TAG/GATEWAY/openai 即可。

十九、支持丰富的自定义设置

1. 支持自定义系统名称、logo 以及页脚。
2. 支持自定义首页和关于页面，可以选择使用 HTML & Markdown 代码进行自定义，或者使用一个单独的网页通过 iframe 嵌入。

二十、支持通过系统访问令牌调用管理 API

在无需二开的情况下扩展和自定义 One API 的功能，详情请参考 API 文档。

二十一、支持 Cloudflare Turnstile 用户校验

二十二、支持用户管理

支持多种用户登录注册方式：

1. 邮箱登录注册（支持注册邮箱白名单）以及通过邮箱进行密码重置
2. 支持飞书授权登录
3. 支持 GitHub 授权登录
4. 微信公众号授权（需要额外部署 WeChat Server）

二十三、支持主题切换

设置环境变量 THEME 即可，默认为 default，欢迎 PR 更多主题。

二十四、配合 Message Pusher 可将报警信息推送到多种 App 上

中文 | English | 日本語

部署教程 · 使用方法 · 意见反馈 · 截图展示 · 在线演示 · 常见问题 · 相关项目 · 赞赏支持

功能

部署

基于 Docker 进行部署

使用 SQLite 的部署命令：
docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api
使用 MySQL 的部署命令，在上面的基础上添加 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi"，请自行修改数据库连接参数，不清楚如何修改请参见下面环境变量一节。
例如：
docker run --name one-api -d --restart always -p 3000:3000 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

server{
   server_name openai.justsong.cn;  # 请根据实际情况修改你的域名

   location / {
          client_max_body_size  64m;
          proxy_http_version 1.1;
          proxy_pass http://localhost:3000;  # 请根据实际情况修改你的端口
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-For $remote_addr;
          proxy_cache_bypass $http_upgrade;
          proxy_set_header Accept-Encoding gzip;
          proxy_read_timeout 300s;  # GPT-4 需要较长的超时时间，请自行调整
   }
}

Ubuntu 安装 certbot：
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
生成证书 & 修改 Nginx 配置
sudo certbot --nginx
根据指示进行操作
重启 Nginx
sudo service nginx restart

通过宝塔面板进行一键部署

基于 Docker Compose 进行部署

目前支持 MySQL 启动，数据存储在 ./data/mysql 文件夹内
docker-compose up -d

查看部署状态
docker-compose ps

手动部署

   git clone https://github.com/songquanpeng/one-api.git

   # 构建前端
   cd one-api/web/default
   npm install
   npm run build

   # 构建后端
   cd ../..
   go mod download
   go build -ldflags "-s -w" -o one-api
   

   chmod u+x one-api
   ./one-api --port 3000 --log-dir ./logs
   

docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-web

docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.justsong.cn -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-web

OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://:/v1"

graph LR
    A(用户)
    A --->|使用 One API 分发的 key 进行请求| B(One API)
    B -->|中继请求| C(OpenAI)
    B -->|中继请求| D(Azure)
    B -->|中继请求| E(其他 OpenAI API 格式下游渠道)
    B -->|中继并修改请求体和返回体| F(非 OpenAI API 格式下游渠道)

相关项目

注意

概述

One API 是一个开源的 API 管理和分发平台，支持将多种 AI 模型提供商（OpenAI、Anthropic、Google、DeepSeek 等）统一到一个兼容 OpenAI 格式的 API 接口下，方便管理和调用。

Docker 部署

快速启动

docker run --name one-api -d 
  --restart always 
  -p 3000:3000 
  -e TZ=Asia/Shanghai 
  -v /home/ubuntu/data/one-api:/data 
  justsong/one-api

Docker Compose

version: '3'
services:
  one-api:
    image: justsong/one-api
    container_name: one-api
    restart: always
    ports:
      - "3000:3000"
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/data

Nginx 反向代理配置

server {
    listen 443 ssl http2;
    server_name api.eake.cn;

    ssl_certificate /etc/ssl/api.eake.cn.pem;
    ssl_certificate_key /etc/ssl/api.eake.cn.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE 支持
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
    }
}

渠道配置

添加 OpenAI 渠道

1. 进入管理后台 → 渠道管理 → 添加渠道
2. 类型选择：OpenAI
3. 填写 Base URL 和 API Key
4. 选择要支持的模型

添加其他渠道

令牌管理

在「令牌」页面创建 API Token，设定额度、过期时间和可用模型。创建后获得的 sk-xxx 即为统一调用密钥。

统一调用示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-one-api-token",
    base_url="https://api.eake.cn/v1"
)

# 调用任何已配置的模型
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

One API 简介

One API 是一个开源的 AI API 管理和分发平台，支持将多个 AI 供应商的API统一为一个接口格式（兼容OpenAI格式），实现负载均衡、令牌管理、用量计费等功能。非常适合需要管理多个API Key或搭建API中转服务的场景。

Docker 部署（推荐）

创建数据目录

mkdir -p /opt/one-api/data

启动容器

docker run --name one-api -d 
  --restart always 
  -p 3000:3000 
  -e TZ=Asia/Shanghai 
  -v /opt/one-api/data:/data 
  justsong/one-api

Nginx 反向代理配置

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/ssl/certs/api.example.com.pem;
    ssl_certificate_key /etc/ssl/certs/api.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE支持
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
    }
}

初始化配置

登录管理后台

访问 https://api.example.com，默认管理员账号：

• 用户名：root
• 密码：123456

⚠️ 首次登录后立即修改密码！

添加渠道（Channel）

渠道是API供应商的接入配置：

创建令牌（Token）

令牌是分发给用户的访问密钥：

• 设置额度限制
• 限制可用模型
• 设置过期时间
• 启用/禁用IP白名单

渠道配置示例

OpenAI 渠道

DeepSeek 渠道

Anthropic 渠道

负载均衡策略

同一模型可配置多个渠道，One API自动负载均衡：

• 优先级：数字越小优先级越高
• 权重：同优先级按权重分配
• 自动重试：某渠道失败自动切换

使用方式

部署完成后，将 Base URL 改为 One API 地址，使用 One API 生成的令牌即可：

from openai import OpenAI

client = OpenAI(
    api_key="sk-one-api-token-xxx",  # One API 令牌
    base_url="https://api.example.com/v1"  # One API 地址
)

# 像使用 OpenAI 一样调用
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

数据备份

# 备份SQLite数据库
cp /opt/one-api/data/one-api.db /opt/one-api/data/one-api.db.bak

# 或导出MySQL
mysqldump -u root -p one_api > one_api_backup.sql

常见问题

Q: 渠道报错 401？
A: 检查API Key是否正确，是否已过期。

Q: 流式输出中断？
A: Nginx需关闭 proxy_buffering，确保SSE正常传输。

Q: 如何查看日志？
A: docker logs one-api -f --tail 100

一、概述

OpenAI API 提供 GPT 系列模型的程序化访问，支持文本生成、对话、函数调用、图像生成、语音合成与识别、嵌入向量等功能。所有接口兼容 OpenAI 格式，可通过 REST API 或官方 SDK 调用。

二、认证

所有请求需在 HTTP Header 中携带 API Key：

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

API Key 在 platform.openai.com/api-keys 创建，建议通过环境变量管理：

export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

三、Base URL

https://api.openai.com/v1

四、模型列表

五、Chat Completions

请求

POST /v1/chat/completions

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "top_p": 1,
  "max_tokens": 4096,
  "stream": false,
  "stop": null,
  "presence_penalty": 0,
  "frequency_penalty": 0
}

参数说明

响应

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1717100000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

六、Function Calling（函数调用）

定义函数

"tools": [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "获取指定城市的当前天气",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {"type": "string", "description": "城市名称"},
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
      },
      "required": ["city"]
    }
  }
}]

处理函数调用

// 模型返回 tool_calls
if (response.choices[0].finish_reason === "tool_calls") {
  const toolCall = response.choices[0].message.tool_calls[0];
  // 执行实际函数
  const result = await getWeather(toolCall.function.arguments);
  // 将结果返回给模型
  const followUp = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [
      ...previousMessages,
      response.choices[0].message,
      {
        role: "tool",
        tool_call_id: toolCall.id,
        content: JSON.stringify(result)
      }
    ]
  });
}

七、图像生成（DALL·E）

POST /v1/images/generations

{
  "model": "dall-e-3",
  "prompt": "A white siamese cat in a cyberpunk city",
  "n": 1,
  "size": "1024x1024",
  "quality": "hd",
  "style": "vivid"
}

可选尺寸：1024x1024, 1792x1024, 1024x1792

八、语音识别（Whisper）

POST /v1/audio/transcriptions
Content-Type: multipart/form-data

file: audio.mp3
model: whisper-1
language: zh

九、语音合成（TTS）

POST /v1/audio/speech

{
  "model": "tts-1",
  "input": "你好，世界！",
  "voice": "alloy"
}

可用声音：alloy, echo, fable, onyx, nova, shimmer

十、文本嵌入

POST /v1/embeddings

{
  "model": "text-embedding-3-large",
  "input": "The food was delicious"
}

十一、速率限制

遇到 429 错误时使用指数退避重试。

十二、错误码

一、概述

Anthropic Claude API 提供 Claude 系列模型的访问，以长上下文、高质量输出和安全对齐著称。API 同时支持 OpenAI 兼容格式和原生 Anthropic 格式。

二、认证

x-api-key: sk-ant-xxxxxxxxxxxxxxxx
anthropic-version: 2023-06-01

API Key 在 console.anthropic.com 创建。

三、Base URL

原生格式：https://api.anthropic.com/v1
OpenAI兼容：https://api.anthropic.com/v1/openai

四、模型列表

五、Messages API

请求

POST /v1/messages

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 4096,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "top_p": 1,
  "top_k": 0,
  "stream": false
}

参数说明

响应

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "Hello! How can I help you?"}
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 10,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

六、多模态输入

图像（Base64）

"messages": [{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "iVBORw0KGgo..."
      }
    },
    {"type": "text", "text": "描述这张图片"}
  ]
}]

图像（URL）

"content": [
  {
    "type": "image",
    "source": {
      "type": "url",
      "url": "https://example.com/photo.jpg"
    }
  },
  {"type": "text", "text": "分析这张图"}
]

PDF文档

"content": [
  {
    "type": "document",
    "source": {
      "type": "base64",
      "media_type": "application/pdf",
      "data": "JVBERi0xLjQ..."
    }
  },
  {"type": "text", "text": "总结文档要点"}
]

七、Tool Use（工具调用）

定义工具

"tools": [{
  "name": "calculator",
  "description": "执行数学计算",
  "input_schema": {
    "type": "object",
    "properties": {
      "expression": {"type": "string", "description": "数学表达式"}
    },
    "required": ["expression"]
  }
}]

处理工具调用

// 模型返回 tool_use block
if (response.stop_reason === "tool_use") {
  const toolBlock = response.content.find(b => b.type === "tool_use");
  
  // 执行函数并返回结果
  const result = await calculator(toolBlock.input.expression);
  
  const followUp = await client.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 4096,
    tools: tools,
    messages: [
      {"role": "user", "content": "计算 2+2"},
      {"role": "assistant", "content": response.content},
      {
        "role": "user",
        "content": [{
          "type": "tool_result",
          "tool_use_id": toolBlock.id,
          "content": result.toString()
        }]
      }
    ]
  });
}

八、扩展思考（Extended Thinking）

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [
    {"role": "user", "content": "证明费马大定理的特殊情况n=4"}
  ]
}

响应中会包含 thinking 类型的 content block，展示推理过程。

九、流式输出

const stream = client.messages.stream({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{"role": "user", "content": "Hello!"}]
});

stream.on("text", (text) => {
  process.stdout.write(text);
});

十、Prompt Caching（提示缓存）

标记可缓存的内容块，减少重复计费：

"system": [{
  "type": "text",
  "text": "很长的系统指令...",
  "cache_control": {"type": "ephemeral"}
}]

缓存命中的 token 价格降低 90%。

十一、速率限制

十二、错误码

一、概述

DeepSeek API 完全兼容 OpenAI API 格式，现有 OpenAI SDK 和代码可零成本迁移。同时提供 Anthropic API 兼容格式。DeepSeek 以极低价格提供顶级模型能力，性价比业界领先。

二、认证

Authorization: Bearer your-deepseek-api-key

API Key 在 platform.deepseek.com/api_keys 创建。

三、Base URL

OpenAI兼容格式：https://api.deepseek.com
Anthropic兼容格式：https://api.deepseek.com/anthropic
聊天补全端点：https://api.deepseek.com/chat/completions

四、模型列表

五、使用 OpenAI SDK 调用

from openai import OpenAI

client = OpenAI(
    api_key="your-deepseek-api-key",
    base_url="https://api.deepseek.com"
)

# 非思考模式
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    stream=False
)
print(response.choices[0].message.content)

六、思考模式

DeepSeek 独有的深度推理能力，模型在回答前进行长链推理：

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "求解 x^2 + 5x + 6 = 0"}
    ],
    thinking={"type": "enabled"},
    reasoning_effort="high",  # low / medium / high
    stream=False
)

思考模式响应结构

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "方程 x^2 + 5x + 6 = 0 的解为 x = -2 或 x = -3",
      "reasoning_content": "这是一个一元二次方程...n使用因式分解...n(x+2)(x+3)=0..."
    }
  }]
}

reasoning_effort 参数

七、流式输出

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True
)

for chunk in stream:
    # 普通内容
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    # 思考内容（思考模式下）
    if hasattr(chunk.choices[0].delta, 'reasoning_content') and chunk.choices[0].delta.reasoning_content:
        # 可选择不输出思考过程
        pass

八、cURL 调用示例

curl https://api.deepseek.com/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" 
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "thinking": {"type": "enabled"},
    "reasoning_effort": "high",
    "stream": false
  }'

九、Function Calling

与 OpenAI 格式完全一致：

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "北京天气如何？"}],
    tools=tools
)

十、JSON 输出

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "列出中国前5大城市"}],
    response_format={"type": "json_object"}
)

十一、定价

十二、Agent 工具集成

无需编码，直接在主流AI工具中使用：

十三、速率限制

默认限制（付费用户）：

• RPM: 60（v4-pro）/ 120（v4-flash）
• TPM: 2,000,000

余额不足时自动降级为免费层级限速。

十四、错误码

一、概述

Google Gemini API 提供 Gemini 系列模型的访问，支持文本生成、多模态理解、代码执行、搜索增强、图像/视频/音乐生成等能力。以超长上下文（1M tokens）和丰富的多模态生态著称。

二、认证

API Key 方式（简单）

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

API Key 在 Google AI Studio 创建。

服务账号方式（生产环境）

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

三、Base URL

REST API: https://generativelanguage.googleapis.com/v1beta
OpenAI兼容: https://generativelanguage.googleapis.com/v1beta/openai

四、模型列表

五、文本生成

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel('gemini-3-pro')

# 单次生成
response = model.generate_content(
    "解释量子计算的原理",
    generation_config=genai.types.GenerationConfig(
        temperature=0.7,
        top_p=0.95,
        top_k=40,
        max_output_tokens=2048,
        candidate_count=1
    )
)
print(response.text)

参数说明

六、多轮对话

chat = model.start_chat(history=[])

response1 = chat.send_message("我想学习Python")
response2 = chat.send_message("推荐一些入门项目")

# 查看历史
for msg in chat.history:
    print(f"{msg.role}: {msg.parts[0].text}")

七、系统指令

model = genai.GenerativeModel(
    'gemini-3-pro',
    system_instruction=[
        "你是一位专业的Python讲师。",
        "回答使用Markdown格式，包含代码示例。",
        "语气友好且专业。"
    ]
)

八、多模态输入

图像

import PIL.Image

img = PIL.Image.open('photo.jpg')
response = model.generate_content(["描述这张图片", img])

多图

img1 = PIL.Image.open('img1.jpg')
img2 = PIL.Image.open('img2.jpg')
response = model.generate_content([
    "比较这两张图片的异同",
    img1, img2
])

视频

# 上传视频文件
video = genai.upload_file("video.mp4")

# 等待处理完成
while video.state.name == "PROCESSING":
    time.sleep(5)
    video = genai.get_file(video.name)

response = model.generate_content([
    "总结这个视频的内容",
    video
])

音频

audio = genai.upload_file("speech.mp3")
response = model.generate_content([
    "转录这段音频",
    audio
])

九、搜索增强（Grounding）

response = model.generate_content(
    "2026年最新的AI新闻",
    tools="google_search_retrieval"
)
# 回答中包含搜索来源引用

十、代码执行

response = model.generate_content(
    "计算斐波那契数列前100项的和",
    tools="code_execution"
)
# 模型自动编写并执行Python代码

十一、图像生成（多模态输出）

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro",
    contents="生成一张日落风景画",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

十二、文件上传与RAG

# 上传文件
file = genai.upload_file("document.pdf",
    mime_type="application/pdf"
)

# 缓存大文件（减少重复上传费用）
cache = genai.caching.CachedContent.create(
    model="gemini-3-pro",
    contents=[file],
    ttl=datetime.timedelta(hours=2)
)

model = genai.GenerativeModel.from_cached_content(cache)
response = model.generate_content("总结文档要点")

十三、流式输出

response = model.generate_content("写一首诗", stream=True)
for chunk in response:
    print(chunk.text, end="")

十四、定价

免费额度：15 RPM, 1M TPM, 1500 RPD（Flash模型）

十五、错误码

一、概述

Midjourney 是基于AI的图像生成平台，通过文本提示词创建高质量艺术作品。当前版本 V6.1，同时提供 Niji 6 动漫专用模型。平台通过 Discord 运行，支持 Web 界面编辑。

二、入门配置

注册与订阅

1. 访问 midjourney.com 注册
2. 加入官方 Discord 服务器
3. 选择订阅方案

订阅方案

三、核心命令

四、生成后操作

五、参数完整列表

六、版本对比

七、提示词最佳实践

基本公式

主体 + 场景/环境 + 光照/氛围 + 风格/媒介 + 参数

示例

/imagine prompt: a lone samurai standing on a cliff edge, cherry blossoms in wind, golden hour cinematic lighting, ukiyo-e style with modern colors, highly detailed --ar 16:9 --s 750 --v 6.1

技巧

• 英文提示词效果优于中文
• 用逗号分隔关键词，不要写长句
• 材质词提升质感：crystal, marble, neon, holographic
• 镜头词控制构图：close-up, wide angle, bird's eye, macro
• 艺术家参考设定风格：in the style of Greg Rutkowski
• 用 --no 排除不需要的元素
• 迭代优化：生成 → 选择最佳 → 变体 → 放大 → 局部修改

八、角色一致性工作流

1. 生成满意的角色图
2. 复制该图的URL
3. 在后续提示词中使用 --cref URL --cw 100
4. 保持提示词中角色描述一致
5. 可同时使用 --sref 保持风格一致

九、常见问题

Q: 快速时长用完了怎么办？
A: 切换到 Relax 模式（Standard及以上），生成时间约1-2分钟。

Q: 可以商用吗？
A: Pro及Mega方案生成的图片可商用。General商用条款需遵守。

Q: 如何获取图片URL？
A: 点击生成的图片 → 右键 → 复制图片地址。

Q: 生成的图片有手部问题怎么办？
A: V6.1大幅改善了手部，用 --style raw 减少风格化干扰，或使用 Vary (Region) 局部重绘手部。

一、概述

通义千问是阿里云推出的大语言模型服务，提供 Qwen 系列模型的 API 访问。兼容 OpenAI API 格式，支持文本生成、对话、函数调用、长文档理解、图像理解、语音合成等能力。以超高性价比和完善的中文能力著称。

二、认证

通过阿里云 DashScope 平台管理 API Key：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

API Key 在 DashScope 控制台 创建。

三、Base URL

OpenAI兼容格式：https://dashscope.aliyuncs.com/compatible-mode/v1
原生格式：https://dashscope.aliyuncs.com/api/v1

四、模型列表

五、使用 OpenAI SDK 调用

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

response = client.chat.completions.create(
    model="qwen-max",
    messages=[
        {"role": "system", "content": "你是通义千问助手。"},
        {"role": "user", "content": "你好！"}
    ],
    temperature=0.7,
    top_p=0.8,
    max_tokens=2048,
    stream=False
)
print(response.choices[0].message.content)

六、cURL 调用示例

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions 
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "qwen-max",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

七、流式输出

stream = client.chat.completions.create(
    model="qwen-max",
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

八、Function Calling

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="qwen-max",
    messages=[{"role": "user", "content": "上海今天天气如何？"}],
    tools=tools,
    tool_choice="auto"
)

九、多模态（图像理解）

import base64

with open("image.jpg", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="qwen-vl-max",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"}},
            {"type": "text", "text": "描述这张图片"}
        ]
    }]
)

十、超长上下文（qwen-long）

response = client.chat.completions.create(
    model="qwen-long",
    messages=[
        {"role": "system", "content": "你是一个文档分析助手。"},
        {"role": "user", "content": very_long_text}  # 支持百万级token
    ],
    max_tokens=4096
)

十一、定价

新用户赠送 100 万 tokens 免费额度。

十二、速率限制

十三、错误码

一、概述

文心一言（ERNIE Bot）是百度推出的大语言模型服务，提供 ERNIE 系列模型的 API 访问。支持文本生成、对话、函数调用、图像理解、文生图等能力。国内首批通过大模型备案，企业级服务成熟。

二、认证

采用 Access Token 方式认证，通过 API Key + Secret Key 获取：

# 获取 Access Token
curl https://aip.baidubce.com/oauth/2.0/token 
  -d "grant_type=client_credentials&client_id=YOUR_API_KEY&client_secret=YOUR_SECRET_KEY"

# 返回
{"access_token": "24.xxxxxxxxxxxx", "expires_in": 2592000}

Access Token 有效期30天，建议缓存复用。

API Key 和 Secret Key 在 千帆控制台 创建。

三、Base URL

https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop

四、模型列表

五、Chat 请求

POST https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions_pro?access_token=xxx

{
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "temperature": 0.7,
  "top_p": 0.9,
  "max_output_tokens": 2048,
  "stream": false,
  "system": "你是文心一言助手"
}

参数说明

响应

{
  "id": "as-xxx",
  "object": "chat.completion",
  "created": 1717100000,
  "result": "你好！我是文心一言，有什么可以帮你的？",
  "is_truncated": false,
  "need_clear_history": false,
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 15,
    "total_tokens": 20
  }
}

六、Function Calling

"functions": [{
  "name": "get_weather",
  "description": "获取天气信息",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {"type": "string", "description": "城市名"}
    },
    "required": ["city"]
  }
}]

模型返回 function_call 字段时，执行对应函数并将结果追加到 messages 中继续对话。

七、流式输出

curl "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions_pro?access_token=xxx" 
  -H "Content-Type: application/json" 
  -d '{"messages":[{"role":"user","content":"你好"}],"stream":true}'

返回 Server-Sent Events (SSE) 格式数据流。

八、文生图

POST https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/txt2img?access_token=xxx

{
  "prompt": "一只在赛博朋克城市中的白色猫",
  "n": 1,
  "size": "1024x1024",
  "style": "vivid"
}

九、OpenAI 兼容模式

千帆平台同时提供 OpenAI 兼容接口，可直接使用 OpenAI SDK：

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://qianfan.baidubce.com/v1"
)

response = client.chat.completions.create(
    model="ernie-4.0-8k",
    messages=[{"role": "user", "content": "你好"}]
)

十、定价

ERNIE Speed 和 ERNIE Lite 免费使用，适合开发测试。

十一、速率限制

十二、错误码

一、概述

豆包是字节跳动推出的大语言模型服务，提供 Doubao 系列模型的 API 访问。通过火山引擎平台调用，兼容 OpenAI API 格式。以极低价格和中文理解能力著称，Doubao-Pro 价格仅为同级别模型的十分之一。

二、认证

通过火山引擎 API Key 认证：

Authorization: Bearer xxxxxxxxxx

API Key 在 火山引擎方舟控制台 创建。

三、Base URL

OpenAI兼容格式：https://ark.cn-beijing.volces.com/api/v3

四、模型列表

五、使用 OpenAI SDK 调用

from openai import OpenAI

client = OpenAI(
    api_key="your-ark-api-key",
    base_url="https://ark.cn-beijing.volces.com/api/v3"
)

response = client.chat.completions.create(
    model="doubao-1.5-pro-32k",
    messages=[
        {"role": "system", "content": "你是豆包助手。"},
        {"role": "user", "content": "你好！"}
    ],
    temperature=0.7,
    max_tokens=2048
)
print(response.choices[0].message.content)

六、推理模型（深度思考）

response = client.chat.completions.create(
    model="doubao-1.5-pro-32k",
    messages=[{"role": "user", "content": "证明根号2是无理数"}],
    extra_body={
        "thinking": {"type": "enabled"},
        "reasoning_effort": "high"
    }
)

# 思考过程在 reasoning_content 中
print(response.choices[0].message.reasoning_content)
print(response.choices[0].message.content)

七、流式输出

stream = client.chat.completions.create(
    model="doubao-1.5-pro-32k",
    messages=[{"role": "user", "content": "解释量子计算"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

八、Function Calling

tools = [{
    "type": "function",
    "function": {
        "name": "search_web",
        "description": "搜索互联网信息",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "搜索关键词"}
            },
            "required": ["query"]
        }
    }
}]

response = client.chat.completions.create(
    model="doubao-1.5-pro-32k",
    messages=[{"role": "user", "content": "最新AI新闻"}],
    tools=tools,
    tool_choice="auto"
)

九、多模态（图像理解）

response = client.chat.completions.create(
    model="doubao-1.5-vision-pro-32k",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
            {"type": "text", "text": "描述这张图片"}
        ]
    }]
)

十、定价

新用户赠送 50 万 tokens 免费额度。

十一、速率限制

十二、错误码

一、概述

智谱 AI 推出的 GLM（General Language Model）系列大模型，提供从轻量到旗舰的完整模型矩阵。兼容 OpenAI API 格式，支持文本生成、对话、函数调用、图像理解、文生图、代码执行等能力。GLM-4V 多模态模型支持超高分辨率图像理解。

二、认证

Authorization: Bearer xxxxxxxxxx.xxxxxxxx

API Key 在 智谱开放平台 创建。

三、Base URL

https://open.bigmodel.cn/api/paas/v4

四、模型列表

五、使用 OpenAI SDK 调用

from openai import OpenAI

client = OpenAI(
    api_key="your-zhipu-api-key",
    base_url="https://open.bigmodel.cn/api/paas/v4"
)

response = client.chat.completions.create(
    model="glm-5",
    messages=[
        {"role": "system", "content": "你是智谱AI助手。"},
        {"role": "user", "content": "你好！"}
    ],
    temperature=0.7,
    top_p=0.7,
    max_tokens=2048,
    stream=False
)
print(response.choices[0].message.content)

六、原生 SDK 调用

from zhipuai import ZhipuAI

client = ZhipuAI(api_key="your-api-key")

response = client.chat.completions.create(
    model="glm-5",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

七、流式输出

response = client.chat.completions.create(
    model="glm-5",
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

八、Function Calling

tools = [{
    "type": "function",
    "function": {
        "name": "query_weather",
        "description": "查询天气",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "城市"}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="glm-5",
    messages=[{"role": "user", "content": "北京天气"}],
    tools=tools
)

if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    # 执行函数并返回结果
    result = query_weather(json.loads(tool_call.function.arguments)["location"])
    
    follow_up = client.chat.completions.create(
        model="glm-5",
        messages=[
            {"role": "user", "content": "北京天气"},
            response.choices[0].message,
            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
        ],
        tools=tools
    )

九、多模态（图像理解）

response = client.chat.completions.create(
    model="glm-4v-plus",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
            {"type": "text", "text": "详细描述这张图片"}
        ]
    }]
)

十、文生图（CogView）

response = client.images.generations(
    model="cogview-4",
    prompt="一只在水墨画风格的山间行走的猫",
    size="1024x1024"
)
print(response.data[0].url)

十一、定价

十二、速率限制

十三、错误码

一、概述

Moonshot AI（月之暗面）推出的 Kimi 系列模型，以超长上下文和卓越的文档理解能力著称。Kimi K2 支持 128K 上下文，擅长处理长文档、学术论文、代码仓库等场景。兼容 OpenAI API 格式。

二、认证

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key 在 Moonshot 开放平台 创建。

三、Base URL

https://api.moonshot.cn/v1

四、模型列表

五、使用 OpenAI SDK 调用

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://api.moonshot.cn/v1"
)

response = client.chat.completions.create(
    model="kimi-k2",
    messages=[
        {"role": "system", "content": "你是 Kimi 智能助手。"},
        {"role": "user", "content": "你好！"}
    ],
    temperature=0.7,
    max_tokens=2048
)
print(response.choices[0].message.content)

六、cURL 调用示例

curl https://api.moonshot.cn/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $MOONSHOT_API_KEY" 
  -d '{
    "model": "kimi-k2",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

七、流式输出

stream = client.chat.completions.create(
    model="kimi-k2",
    messages=[{"role": "user", "content": "解释量子纠缠"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

八、Function Calling

tools = [{
    "type": "function",
    "function": {
        "name": "search_web",
        "description": "搜索互联网",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "搜索词"}
            },
            "required": ["query"]
        }
    }
}]

response = client.chat.completions.create(
    model="kimi-k2",
    messages=[{"role": "user", "content": "搜索最新的AI新闻"}],
    tools=tools,
    tool_choice="auto"
)

九、文件处理（核心特色）

Kimi 支持上传文件并在对话中引用，适合长文档分析：

# 1. 上传文件
file = client.files.create(
    file=open("paper.pdf", "rb"),
    purpose="file-extract"
)

# 2. 获取文件内容
file_content = client.files.content(file.id)
text = file_content.text

# 3. 在对话中使用
response = client.chat.completions.create(
    model="kimi-k2",
    messages=[
        {"role": "system", "content": "你是文档分析助手。"},
        {"role": "user", "content": f"以下是文档内容：n{text}nn请总结要点。"}
    ]
)

支持格式：PDF、Word、Excel、PPT、TXT、Markdown、CSV 等。

十、定价

十一、速率限制

十二、错误码

一、概述

MiniMax 是国内领先的 AI 模型服务商，提供文本生成、语音合成（TTS）、语音识别（ASR）、音乐生成、视频生成等全栈 AI 能力。以语音合成质量业界领先著称，同时提供高性价比的文本模型。兼容 OpenAI API 格式。

二、认证

Authorization: Bearer xxxxxxxxxx.xxxxxxxx

API Key 在 MiniMax 开放平台 创建。

三、Base URL

https://api.minimax.chat/v1

四、模型列表

五、文本生成

from openai import OpenAI

client = OpenAI(
    api_key="your-minimax-api-key",
    base_url="https://api.minimax.chat/v1"
)

response = client.chat.completions.create(
    model="MiniMax-M2.7",
    messages=[
        {"role": "system", "content": "你是MiniMax助手。"},
        {"role": "user", "content": "你好！"}
    ],
    temperature=0.7,
    max_tokens=2048
)
print(response.choices[0].message.content)

六、语音合成（TTS）— 核心特色

MiniMax 的语音合成被认为是国内最自然的 TTS 服务之一：

POST https://api.minimax.chat/v1/t2a_v2?GroupId=your-group-id

{
  "model": "speech-01-turbo",
  "text": "你好，欢迎使用MiniMax语音合成服务。",
  "stream": false,
  "voice_setting": {
    "voice_id": "Chinese_Female_Gentle",
    "speed": 1.0,
    "vol": 1.0,
    "pitch": 0
  },
  "audio_setting": {
    "sample_rate": 32000,
    "format": "mp3"
  }
}

预设声音列表（部分）

支持声音克隆：上传10-30秒音频即可创建自定义音色。

流式TTS

{
  "model": "speech-01-turbo",
  "text": "这是一段很长的文本...",
  "stream": true,
  "voice_setting": {
    "voice_id": "Chinese_Female_Gentle"
  }
}

返回 SSE 格式音频流，实现边生成边播放。

七、语音识别（ASR）

POST https://api.minimax.chat/v1/asr?GroupId=your-group-id

{
  "model": "speech-01",
  "file": "base64-encoded-audio",
  "language": "zh"
}

八、视频生成

POST https://api.minimax.chat/v1/video_generation

{
  "model": "video-01",
  "prompt": "一只猫在雨中撑伞漫步",
  "aspect_ratio": "16:9"
}

视频生成异步任务，需轮询查询状态。

九、音乐生成

POST https://api.minimax.chat/v1/music_generation

{
  "model": "music-01",
  "prompt": "轻快的电子音乐，节奏明快",
  "duration": 30
}

十、Function Calling

tools = [{
    "type": "function",
    "function": {
        "name": "get_stock_price",
        "description": "查询股票价格",
        "parameters": {
            "type": "object",
            "properties": {
                "symbol": {"type": "string", "description": "股票代码"}
            },
            "required": ["symbol"]
        }
    }
}]

response = client.chat.completions.create(
    model="MiniMax-M2.7",
    messages=[{"role": "user", "content": "茅台股价多少？"}],
    tools=tools
)

十一、定价

十二、错误码

API密钥管理指南

一、什么是 API 密钥

API 密钥（API Key）是调用 AI 模型服务的通行证，每个密钥对应一个独立账户，用于身份认证和用量统计。

二、获取密钥

三、安全规范

四、常见问题

1. 密钥显示无效怎么办？

检查密钥是否过期或被平台吊销，重新到对应平台控制台生成新密钥。

2. 费用异常如何处理？

第一时间在平台后台关闭密钥，排查用量记录，联系客服申诉。

模型选择指南

一、按任务类型选择

二、性能对比

三、模型特点详解

1. Claude 4.7 Opus

• 优势：代码生成、复杂推理、长文本理解
• 上下文：200K tokens
• 适用场景：软件开发、技术文档、研究分析

2. GPT-5.5 Instant

• 优势：响应速度快、免费额度充足
• 上下文：128K tokens
• 适用场景：日常对话、快速问答、内容生成

3. DeepSeek V4-Flash

• 优势：成本极低、中文友好
• 上下文：64K tokens
• 适用场景：批量处理、成本敏感项目

4. Gemini 3.1 Pro

• 优势：超长上下文、科学推理
• 上下文：1M tokens
• 适用场景：论文分析、多文档处理

四、使用建议

优先选择：复杂任务用 Claude，日常对话用 GPT-5.5 Instant，中文场景用豆包，成本敏感用 DeepSeek V4-Flash

API 中转站使用指南

一、什么是 API 中转站

API 中转站（API Relay）统一管理多个 AI 平台的 API 分发，简化接入流程，支持密钥轮换和流量控制。

二、快速开始

三、支持的模型

四、常见问题

1. 请求超时怎么办？

尝试切换模型或稍后重试，高峰期可能响应较慢。

2. 如何查看账单？

登录后在「用量统计」页面查看详细消费记录。

One API 管理后台使用指南

一、One API 是什么

One API 是一款开源的 API 中转管理平台，支持多渠道统一管理、AI 模型接入与分发，适合个人或企业搭建 API 分发站。

二、核心功能

三、操作指南

1. 添加渠道

在「渠道」页面点击「新增渠道」，填写 API 端点、密钥和模型名称。

2. 创建令牌

在「令牌」页面创建新令牌，设置额度限制和有效期。

3. 查看日志

在「日志」页面查看每次 API 请求的详情，便于排查问题。

四、常见问题

1. 渠道显示离线？

检查密钥是否正确，API 端点是否可达，网络连接是否正常。

2. 如何限制用户额度？

在令牌管理中设置额度上限，超出后自动封禁该令牌。

一、获取API密钥

使用EAKE AI平台的API服务，首先需要获取API密钥：

1. 注册并登录 api.eake.cn
2. 进入「令牌」页面，点击「创建新令牌」
3. 设置令牌名称和额度，点击创建
4. 复制生成的API密钥（仅显示一次，请妥善保存）

二、API基础调用

2.1 接口地址

https://api.eake.cn/v1/chat/completions

2.2 请求示例

curl https://api.eake.cn/v1/chat/completions -H Content-Type: application/json -H Authorization: Bearer YOUR_API_KEY -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hello}]}

2.3 Python调用

from openai import OpenAI
client = OpenAI(api_key=YOUR_API_KEY, base_url=https://api.eake.cn/v1)
response = client.chat.completions.create(model=claude-sonnet-4-20250514, messages=[{role:user,content:hello}])
print(response.choices[0].message.content)

三、支持的模型

• Anthropic：Claude Opus 4、Sonnet 4、Sonnet 3.5
• OpenAI：GPT-4.1、GPT-4.1 mini、o3
• Google：Gemini 2.5 Pro、Gemini 2.5 Flash
• 国产：DeepSeek R1、Qwen 3、GLM-5、Kimi K2

四、计费说明

平台采用预充值模式，按实际token用量计费。

五、常见问题

Q: 提示Insufficient quota怎么办？余额不足，请前往充值页面充值。

Q: 支持流式输出吗？支持，请求中设置stream:true即可。

Hermes Agent 部署与配置完全指南

Hermes Agent 是 Nous Research 开发的开源 AI 智能体，支持15+平台接入，具备记忆、技能学习、语音交互等能力。本指南覆盖从零部署到生产使用的全流程。

一、环境要求

• Python 3.11+
• Node.js 20+（浏览器工具依赖）
• Git、ffmpeg、ripgrep
• uv 包管理器

二、一键安装

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

三、模型配置

运行 hermes model 交互式选择模型和 provider，或手动编辑 ~/.hermes/config.yaml：

model:
  default: doubao-seed-2-0-pro-260215
  provider: custom
  base_url: " http://localhost:8866/v1\
 api_key: \your-api-key\
 context_length: 128000

四、平台接入

Hermes 支持 Telegram、Discord、微信、Slack 等 15+ 平台：

hermes gateway setup # 交互式配置
hermes gateway run # 前台运行
hermes gateway install # 安装为系统服务

五、语音功能

在 config.yaml 中添加：

voice:
 stt:
 enabled: true
 provider: local
 local:
 model: base
 tts:
 enabled: true
 provider: edge
 edge:
 voice: zh-CN-XiaoxiaoNeural

安装本地 STT：pip install faster-whisper

在聊天中发送 /voice on 启用语音模式。

六、Skills 管理

hermes skills list # 查看已装skills
hermes skills search \关键词\ # 搜索skills
hermes skills install identifier # 安装skill

七、Web UI 部署

npm install -g hermes-web-ui
hermes-web-ui start 8648 # 启动Web界面

配合 Nginx 反向代理即可对外提供 Web 访问。

常见问题

Q: 502 Bad Gateway？
A: 检查 hermes-web-ui 是否在运行，端口是否匹配 nginx 配置。

Q: 回复出现英文/配置内容？
A: 在 AGENTS.md 中添加强制中文和禁止输出文档的规则，并考虑升级模型。

Q: 语音不生效？
A: 确认 faster-whisper 已安装，voice 配置已写入，发送 /voice on 开启。

Claude Code 是 Anthropic 官方推出的终端编程工具，基于 Claude 3.5 Sonnet 模型，支持直接在命令行中与 AI 协作完成代码编写、调试、重构和解释等任务。

核心能力

• 智能代码生成：通过自然语言描述需求，自动生成完整代码文件
• 代码审查与优化：分析代码逻辑，提供改进建议和性能优化方案
• 多轮对话迭代：支持持续对话，可完成从设计到实现的完整流程
• 文件批量处理：支持一次处理多个文件，适合大型项目重构
• 安全沙箱执行：所有代码操作在隔离环境中执行

安装方法

npm install -g @anthropic-ai/claude-code
npx claude-code

基本使用

claude-code
# 解释代码
"请解释 src/utils/auth.js 的工作原理"
# 重构代码
"将这个函数重构为 TypeScript，并添加类型注解"
# 写测试
"为这个模块生成 Jest 单元测试"

进阶技巧

• 使用 @ 引用本地文件：@src/main.ts 请分析这个模块
• 使用 /approval 查看所有待执行的写操作
• 使用 /model 切换不同 Claude 模型
• 设置 CLAUDE_API_KEY 环境变量使用自有 API Key

适用场景

• 快速原型开发：用自然语言描述即可生成功能代码
• 遗留代码维护：自动分析并重构老旧代码
• 代码评审：辅助进行代码审查和 Bug 定位
• 学习新技术：通过对话方式快速理解陌生代码库

Claude Code 是现代 AI 原生开发工具的代表，让开发者从繁琐的重复编码中解放出来，专注于更具创造性的工作。

One API 是一个开源的 API 中转管理平台，支持将多个 AI 服务商的 API 统一接入，通过自定义渠道实现负载均衡、限流控制和成本优化。

架构设计

                    ┌─────────────┐
                    │   Nginx     │  (HTTPS 443)
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
  ┌─────▼─────┐      ┌────▼────┐      ┌─────▼─────┐
  │ One API 1 │      │ One API2│      │ One API 3│
  │  :3000    │      │  :3001   │      │  :3002   │
  └─────┬─────┘      └────┬────┘      └─────┬─────┘
        └──────────────────┼──────────────────┘
                           │
              ┌────────────▼────────────┐
              │      MySQL 共享存储       │
              └──────────────────────────┘

Docker Compose 部署

version: "3.8"
services:
  one-api:
    image: ssawing/one-api:latest
    container_name: one-api
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    depends_on:
      - mysql
  mysql:
    image: mysql:8.0
    container_name: one-api-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: your_strong_password
      MYSQL_DATABASE: one_api
    volumes:
      - ./mysql:/var/lib/mysql

高可用配置要点

• 多实例部署：通过 Nginx upstream 配置多个 One API 实例，轮询负载均衡
• 会话共享：所有实例连接同一个 MySQL 数据库，渠道配置实时同步
• 健康检查：Nginx upstream 配置 max_fails 和 fail_timeout，自动摘除故障节点
• SSL 终端：在 Nginx 层处理 HTTPS，容器间通信走 HTTP
• 数据持久化：MySQL 主从复制，One API /data 目录映射到宿主机

安全加固

• 修改管理后台路径（如 /admin-secret-path/）防止扫描
• 设置复杂的渠道 Token，定期轮换
• 通过 Nginx limit_req 限制单 IP 请求频率
• 配置 Key 鉴权白名单

高可用部署的核心是冗余 + 故障自动切换。生产环境建议使用 K8s 进行容器编排和自动恢复。

Claude Code 完全指南

指南概述

Claude Code 完全指南 —— 从安装到高效使用 是一份从入门到精通的完整教程，帮助你快速掌握该工具的核心用法。

前置要求

• 基础的命令行操作能力
• 已安装必要的运行环境（如 Node.js、Python、Docker 等）
• 拥有对应的 API 密钥或账号

安装步骤

1. 环境准备：检查并安装所需依赖
2. 获取凭证：注册账号并获取 API Key
3. 初始化配置：按照向导完成初始设置
4. 验证安装：运行测试命令确认可用

核心功能详解

本指南将逐一介绍各项核心功能的使用方法和最佳实践，包括但不限于：基本操作、高级配置、常见问题排查、性能优化建议等。

进阶技巧

• 自定义快捷键和工作流
• 与现有工具链的集成方案
• 团队协作的最佳实践
• 安全性和权限管理

故障排除

汇总了用户最常遇到的问题及其解决方案，包括网络连接问题、认证失败、输出异常等典型情况的排查思路。

One API 部署指南

指南概述

One API 部署指南 —— 统一管理多个AI模型接口 是一份从入门到精通的完整教程，帮助你快速掌握该工具的核心用法。

前置要求

• 基础的命令行操作能力
• 已安装必要的运行环境（如 Node.js、Python、Docker 等）
• 拥有对应的 API 密钥或账号

安装步骤

1. 环境准备：检查并安装所需依赖
2. 获取凭证：注册账号并获取 API Key
3. 初始化配置：按照向导完成初始设置
4. 验证安装：运行测试命令确认可用

核心功能详解

本指南将逐一介绍各项核心功能的使用方法和最佳实践，包括但不限于：基本操作、高级配置、常见问题排查、性能优化建议等。

进阶技巧

• 自定义快捷键和工作流
• 与现有工具链的集成方案
• 团队协作的最佳实践
• 安全性和权限管理

故障排除

汇总了用户最常遇到的问题及其解决方案，包括网络连接问题、认证失败、输出异常等典型情况的排查思路。

Gemini CLI 快速上手

指南概述

Gemini CLI 快速上手 —— Google免费AI编程助手 是一份从入门到精通的完整教程，帮助你快速掌握该工具的核心用法。

前置要求

• 基础的命令行操作能力
• 已安装必要的运行环境（如 Node.js、Python、Docker 等）
• 拥有对应的 API 密钥或账号

安装步骤

1. 环境准备：检查并安装所需依赖
2. 获取凭证：注册账号并获取 API Key
3. 初始化配置：按照向导完成初始设置
4. 验证安装：运行测试命令确认可用

核心功能详解

本指南将逐一介绍各项核心功能的使用方法和最佳实践，包括但不限于：基本操作、高级配置、常见问题排查、性能优化建议等。

进阶技巧

• 自定义快捷键和工作流
• 与现有工具链的集成方案
• 团队协作的最佳实践
• 安全性和权限管理

故障排除

汇总了用户最常遇到的问题及其解决方案，包括网络连接问题、认证失败、输出异常等典型情况的排查思路。

Cursor AI 使用手册

指南概述

Cursor AI 使用手册 —— AI驱动的代码编辑器 是一份从入门到精通的完整教程，帮助你快速掌握该工具的核心用法。

前置要求

• 基础的命令行操作能力
• 已安装必要的运行环境（如 Node.js、Python、Docker 等）
• 拥有对应的 API 密钥或账号

安装步骤

1. 环境准备：检查并安装所需依赖
2. 获取凭证：注册账号并获取 API Key
3. 初始化配置：按照向导完成初始设置
4. 验证安装：运行测试命令确认可用

核心功能详解

本指南将逐一介绍各项核心功能的使用方法和最佳实践，包括但不限于：基本操作、高级配置、常见问题排查、性能优化建议等。

进阶技巧

• 自定义快捷键和工作流
• 与现有工具链的集成方案
• 团队协作的最佳实践
• 安全性和权限管理

故障排除

汇总了用户最常遇到的问题及其解决方案，包括网络连接问题、认证失败、输出异常等典型情况的排查思路。

OpenAI API 快速接入指南

指南概述

OpenAI API 快速接入指南 是一份从入门到精通的完整教程，帮助你快速掌握该工具的核心用法。

前置要求

• 基础的命令行操作能力
• 已安装必要的运行环境（如 Node.js、Python、Docker 等）
• 拥有对应的 API 密钥或账号

安装步骤

1. 环境准备：检查并安装所需依赖
2. 获取凭证：注册账号并获取 API Key
3. 初始化配置：按照向导完成初始设置
4. 验证安装：运行测试命令确认可用

核心功能详解

本指南将逐一介绍各项核心功能的使用方法和最佳实践，包括但不限于：基本操作、高级配置、常见问题排查、性能优化建议等。

进阶技巧

• 自定义快捷键和工作流
• 与现有工具链的集成方案
• 团队协作的最佳实践
• 安全性和权限管理

故障排除

汇总了用户最常遇到的问题及其解决方案，包括网络连接问题、认证失败、输出异常等典型情况的排查思路。

Docker入门

指南概述

Docker入门 —— AI项目容器化部署 是一份从入门到精通的完整教程，帮助你快速掌握该工具的核心用法。

前置要求

• 基础的命令行操作能力
• 已安装必要的运行环境（如 Node.js、Python、Docker 等）
• 拥有对应的 API 密钥或账号

安装步骤

1. 环境准备：检查并安装所需依赖
2. 获取凭证：注册账号并获取 API Key
3. 初始化配置：按照向导完成初始设置
4. 验证安装：运行测试命令确认可用

核心功能详解

本指南将逐一介绍各项核心功能的使用方法和最佳实践，包括但不限于：基本操作、高级配置、常见问题排查、性能优化建议等。

进阶技巧

• 自定义快捷键和工作流
• 与现有工具链的集成方案
• 团队协作的最佳实践
• 安全性和权限管理

故障排除

汇总了用户最常遇到的问题及其解决方案，包括网络连接问题、认证失败、输出异常等典型情况的排查思路。

Claude Code 是 Anthropic 推出的智能体式编程工具，可直接读取你的代码库、编辑文件、运行命令，并集成开发工具。支持终端、IDE 扩展、桌面应用与浏览器多种形态。

安装

• macOS / Linux / WSL：curl -fsSL https://claude.ai/install.sh | bash
• Windows PowerShell：irm https://claude.ai/install.ps1 | iex
• Homebrew：brew install --cask claude-code
• WinGet：winget install Anthropic.ClaudeCode

首次运行 claude 会引导登录（Claude 订阅或 Anthropic Console 账号），终端 CLI 与 VS Code 也支持第三方模型供应商。

快速开始

cd your-project
claude

常用能力

• 多文件编辑与跨工具协作
• 斜杠命令与权限审批
• 第三方 Provider 接入（绕过官方登录）

适用场景：功能开发、Bug 修复、自动化重构与跨文件任务。

Claude Desktop 是 Anthropic 的桌面客户端，在 IDE / 终端之外以独立应用运行 Claude Code，可可视化查看 diff、并排多会话、定时任务与云端会话。

安装

• macOS / Windows：从 Claude 官网下载安装包
• 在桌面端登录 Claude 账号后即可使用

核心特性

• 可视化 diff 审查代码改动
• 多会话并排管理
• 定时 recurring 任务
• 启动云端会话（Cloud Sessions）

适用场景：不想依赖终端、希望图形化审查与多任务管理的开发者。

Codex CLI 是 OpenAI 官方的智能体式命令行编码工具，将 Codex 模型能力带入终端，支持代码读写、命令执行与多模态输入。

安装

npm install -g @openai/codex

需配置 OpenAI API Key（环境变量 OPENAI_API_KEY 或登录）。

常用命令

• codex：启动交互式会话
• codex exec "重构这个函数"：一次性执行任务
• codex --help：查看全部选项

配置

支持通过 ~/.codex/config.toml 配置模型、审批模式与网络访问策略。

适用场景：受 OpenAI 生态约束、需要官方 Codex 模型能力的终端工作流。

Gemini CLI 是 Google 开源的 AI 智能体，将 Gemini 模型能力直接带入终端，开源免费、支持超长上下文与多工具调用。

安装

npm install -g @google/gemini-cli
# 或免安装运行
npx @google/gemini-cli

需配置 Gemini API Key（GEMINI_API_KEY 或 Google 登录）。

常用命令

• gemini：启动交互式会话
• /help：查看斜杠命令
• @path/to/file：在提示中引用文件
• /chat save / /chat resume：保存与恢复会话

特性

• 100 万 token 超长上下文
• MCP 与扩展机制
• 免费额度友好

适用场景：需要超长上下文、偏好 Google 模型与开源方案的开发者。

OpenCode 是一个开源的终端 AI 编码智能体，提供类 Cursor 的 TUI 交互体验，支持多种模型供应商与可扩展工具链。

安装

npm install -g opencode-ai

快速开始

opencode

启动后进入交互式 TUI，可选择模型供应商、会话管理与文件上下文。

核心特性

• 终端 TUI 交互界面
• 多模型 / 多 Provider 支持
• 会话与上下文管理
• 可扩展工具与技能

适用场景：喜欢终端 TUI、希望自托管与多模型切换的开发者。

OpenClaw 是一个自托管的 AI 智能体多通道网关，可运行在任意操作系统，将 Discord、iMessage、Signal、Slack、Telegram、WhatsApp 等聊天应用连接到一个 Always-on 的 AI 助手。采用 MIT 开源协议。

环境要求

• Node 24.15+（推荐），或 Node 22 LTS（22.22.3+），或 Node 25.9+
• 一个 Provider 的 API Key
• 约 5 分钟上手

安装与启动

openclaw onboard   # 引导式初始化
openclaw gateway   # 启动网关

核心能力

• 多通道网关：单一 Gateway 同时服务所有已配置通道
• 多智能体路由：按 agent / 工作区 / 发送者隔离会话
• 媒体支持与插件通道（Matrix、Nostr、Twitch、Zalo 等）
• 控制面板（Web Control UI）、CLI、移动节点

适用场景：希望把 AI 助手接入私人通讯软件、自托管且数据自主控制的开发者与高阶用户。

Hermes Agent 是一个面向任务自动化的 AI 智能体，支持模型路由、技能系统与记忆管理，可作为通用助手在终端中执行多步骤任务。

安装

npm install -g hermes-agent

快速开始

hermes

启动后可通过自然语言下达任务，支持工具调用、记忆与技能扩展。

核心特性

• 技能系统（Skills）与记忆（Memory）管理
• 多模型路由与 Provider 配置
• 定时任务与子 Agent 编排

适用场景：需要可定制智能体、技能化工作流与长期记忆的自动化场景。

Qoder CLI 是 Qoder 提供的智能编程命令行工具，将 Qoder 的代码理解与生成能力带入本地终端工作流。

安装

npm install -g @qoder-ai/qodercli

快速开始

qoder

启动交互式会话后可直接对当前项目进行问答、改码与任务编排。

核心特性

• 项目级代码理解与索引
• 对话式改码与任务执行
• 与 Qoder 平台能力联动

适用场景：偏好 Qoder 代码模型、希望在终端获得项目级智能编程支持的开发者。